Merge pull request #654 from ax3l/doc-doxygenWarnings

Doxygen: Fix Many Warnings

Author: ax3l

.github/workflows/source.yml

@@ -4,12 +4,19 @@ on: [push, pull_request]
 
 jobs:
   style:
-
     runs-on: ubuntu-latest
-
     steps:
     - uses: actions/checkout@v1
     - name: TABs
       run: .github/workflows/source/hasTabs
     - name: End-of-Line whitespaces
       run: .github/workflows/source/hasEOLwhiteSpace
+
+  documentation:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v1
+    - name: Install
+      run: sudo apt-get install -y --no-install-recommends doxygen
+    - name: Doxygen
+      run: .github/workflows/source/buildDoxygen

.github/workflows/source/buildDoxygen

@@ -0,0 +1,16 @@
+#!/usr/bin/env bash
+#
+# Copyright 2020 Axel Huebl
+#
+# License: LGPLv3+
+
+# search recursive inside a folder if a file contains tabs
+#
+# @result 0 if no files are found, else 1
+#
+
+set -eu -o pipefail
+
+cd docs
+echo "WARN_AS_ERROR = YES" >> Doxyfile
+doxygen

CMakeLists.txt

@@ -532,6 +532,7 @@ if(openPMD_HAVE_PYTHON)
         src/binding/python/RecordComponent.cpp
         src/binding/python/MeshRecordComponent.cpp
         src/binding/python/Series.cpp
+        src/binding/python/UnitDimension.cpp
     )
     target_link_libraries(openPMD.py PRIVATE openPMD)
 

docs/Doxyfile

@@ -1,7 +1,11 @@
 PROJECT_NAME      = "openPMD-api"
 XML_OUTPUT        = xml
-INPUT             = ../
-EXCLUDE_PATTERNS  = */share/openPMD/thirdParty/*
+INPUT             = ../src ../include
+EXCLUDE_PATTERNS  = *CommonADIOS1IOHandler.cpp *benchmark*
+
+# TAGFILES += "cppreference-doxygen-web.tag.xml=http://en.cppreference.com/w/"
+BUILTIN_STL_SUPPORT = YES
+
 GENERATE_LATEX    = NO
 GENERATE_MAN      = NO
 GENERATE_RTF      = NO
@@ -14,13 +18,17 @@ JAVADOC_AUTOBRIEF = YES
 USE_MDFILE_AS_MAINPAGE = README.md
 
 # "enable" all frontends and backends
-PREDEFINED        = openPMD_HAVE_MPI=1 \
+MACRO_EXPANSION   = YES
+PREDEFINED        = DOXYGEN_SHOULD_SKIP_THIS \
+                    openPMD_HAVE_MPI=1 \
                     openPMD_HAVE_HDF5=1 \
                     openPMD_HAVE_ADIOS1=1 \
                     openPMD_HAVE_ADIOS2=1 \
                     openPMD_HAVE_PYTHON=1 \
                     OPENPMD_private:=private \
-                    OPENPMD_protected:=protected
+                    OPENPMD_protected:=protected \
+                    __attribute__(x)= \
+                    __declspec(x)=
 
 # ideally, you want to warn on missing doc coverage!
 WARN_IF_UNDOCUMENTED = NO

include/openPMD/IO/ADIOS/ADIOS2IOHandler.hpp

@@ -223,8 +223,8 @@ class ADIOS2IOHandlerImpl
 
     /**
      * @brief nameOfAttribute
-     * @param The Writable at whose level the attribute lies.
-     * @param The openPMD name of the attribute.
+     * @param writable The Writable at whose level the attribute lies.
+     * @param attribute The openPMD name of the attribute.
      * @return The ADIOS2 name of the attribute, consisting of
      * the variable that the attribute is associated with
      * (possibly the empty string, representing no variable)

include/openPMD/IO/AbstractIOHandlerImplCommon.hpp

@@ -97,7 +97,7 @@ class AbstractIOHandlerImplCommon : public AbstractIOHandlerImpl
     /**
      * Figure out the file position of the writable and extend it.
      * @param writable The writable.
-     * @param write The extension string.
+     * @param extend The extension string.
      * @return The current file position.
      */
     virtual std::shared_ptr< FilePositionType >

include/openPMD/UnitDimension.hpp

@@ -0,0 +1,42 @@
+/* Copyright 2020 Axel Huebl
+ *
+ * This file is part of openPMD-api.
+ *
+ * openPMD-api is free software: you can redistribute it and/or modify
+ * it under the terms of of either the GNU General Public License or
+ * the GNU Lesser General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * openPMD-api is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License and the GNU Lesser General Public License
+ * for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * and the GNU Lesser General Public License along with openPMD-api.
+ * If not, see <http://www.gnu.org/licenses/>.
+ */
+#pragma once
+
+#include <cstdint>
+
+
+namespace openPMD
+{
+    /** Physical dimension of a record
+     *
+     * Dimensional base quantities of the international system of quantities
+     */
+    enum class UnitDimension : uint8_t
+    {
+        L = 0, //!< length
+        M,     //!< mass
+        T,     //!< time
+        I,     //!< electric current
+        theta, //!< thermodynamic temperature
+        N,     //!< amount of substance
+        J      //!< luminous intensity
+    };
+} // namespace openPMD

include/openPMD/backend/BaseRecord.hpp

@@ -22,6 +22,7 @@
 
 #include "openPMD/backend/Container.hpp"
 #include "openPMD/RecordComponent.hpp"
+#include "openPMD/UnitDimension.hpp"
 
 #include <array>
 #include <string>
@@ -30,10 +31,6 @@
 
 namespace openPMD
 {
-enum class UnitDimension : uint8_t
-{
-    L = 0, M, T, I, theta, N, J
-};
 
 template< typename T_elem >
 class BaseRecord : public Container< T_elem >

include/openPMD/backend/BaseRecordComponent.hpp

@@ -64,7 +64,7 @@ class BaseRecordComponent : public Attributable
 namespace detail
 {
 /**
- * Functor template to be used in combination with <switchType>"()"
+ * Functor template to be used in combination with switchType::operator()
  * to set a default value for constant record components via the
  * respective type's default constructor.
  * Used to implement empty datasets in subclasses of BaseRecordComponent

include/openPMD/backend/Container.hpp

@@ -41,7 +41,7 @@ namespace traits
     /** Container Element Creation Policy
      *
      * The operator() of this policy is called after the container
-     * ::insert of a new element. The passed parameter is an iterator to the
+     * insert() of a new element. The passed parameter is an iterator to the
      * newly added element.
      */
     template< typename U >