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 >

include/openPMD/openPMD.hpp

@@ -20,6 +20,10 @@
  */
 #pragma once
 
+/** Public definitions of openPMD-api
+ */
+namespace openPMD {}
+
 // IWYU pragma: begin_exports
 #include "openPMD/Dataset.hpp"
 #include "openPMD/Datatype.hpp"
@@ -31,6 +35,7 @@
 #include "openPMD/RecordComponent.hpp"
 #include "openPMD/Record.hpp"
 #include "openPMD/Series.hpp"
+#include "openPMD/UnitDimension.hpp"
 
 #include "openPMD/backend/Attributable.hpp"
 #include "openPMD/backend/Attribute.hpp"

src/IO/ADIOS/ADIOS1IOHandler.cpp

@@ -306,9 +306,11 @@ ADIOS1IOHandlerImpl::initialize_group(std::string const &name)
     return group;
 }
 
+#ifndef DOXYGEN_SHOULD_SKIP_THIS
 #define CommonADIOS1IOHandlerImpl ADIOS1IOHandlerImpl
 #include "CommonADIOS1IOHandler.cpp"
 #undef CommonADIOS1IOHandlerImpl
+#endif
 
 #else
 ADIOS1IOHandler::ADIOS1IOHandler(std::string path, AccessType at)

src/IO/ADIOS/ParallelADIOS1IOHandler.cpp

@@ -319,9 +319,11 @@ ParallelADIOS1IOHandlerImpl::initialize_group(std::string const &name)
     return group;
 }
 
+#ifndef DOXYGEN_SHOULD_SKIP_THIS
 #define CommonADIOS1IOHandlerImpl ParallelADIOS1IOHandlerImpl
 #include "CommonADIOS1IOHandler.cpp"
 #undef CommonADIOS1IOHandlerImpl
+#endif
 
 #else
 #   if openPMD_HAVE_MPI

src/Record.cpp

@@ -19,6 +19,8 @@
  * If not, see <http://www.gnu.org/licenses/>.
  */
 #include "openPMD/Record.hpp"
+#include "openPMD/RecordComponent.hpp"
+#include "openPMD/backend/BaseRecord.hpp"
 
 #include <iostream>
 
@@ -131,7 +133,7 @@ Record::read()
     readAttributes();
 }
 
-template
+template <>
 BaseRecord<RecordComponent>::mapped_type&
 BaseRecord<RecordComponent>::operator[](std::string&& key);
 } // openPMD

src/binding/python/BaseRecord.cpp

@@ -42,14 +42,4 @@ void init_BaseRecord(py::module &m) {
         .def_property_readonly("unit_dimension", &BaseRecord< BaseRecordComponent >::unitDimension);
     py::class_<BaseRecord< PatchRecordComponent >, Container< PatchRecordComponent > >(m, "Base_Record_Patch_Record_Component")
         .def_property_readonly("unit_dimension", &BaseRecord< PatchRecordComponent >::unitDimension);
-
-    py::enum_<UnitDimension>(m, "Unit_Dimension")
-        .value("L", UnitDimension::L)
-        .value("M", UnitDimension::M)
-        .value("T", UnitDimension::T)
-        .value("I", UnitDimension::I)
-        .value("theta", UnitDimension::theta)
-        .value("N", UnitDimension::N)
-        .value("J", UnitDimension::J)
-    ;
 }

src/binding/python/UnitDimension.cpp

@@ -0,0 +1,40 @@
+/* Copyright 2018-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/>.
+ */
+#include <pybind11/pybind11.h>
+#include <pybind11/stl.h>
+
+#include "openPMD/UnitDimension.hpp"
+
+namespace py = pybind11;
+using namespace openPMD;
+
+
+void init_UnitDimension(py::module &m) {
+    py::enum_<UnitDimension>(m, "Unit_Dimension")
+        .value("L", UnitDimension::L)
+        .value("M", UnitDimension::M)
+        .value("T", UnitDimension::T)
+        .value("I", UnitDimension::I)
+        .value("theta", UnitDimension::theta)
+        .value("N", UnitDimension::N)
+        .value("J", UnitDimension::J)
+    ;
+}

src/binding/python/openPMD.cpp

@@ -50,13 +50,15 @@ void init_PatchRecordComponent(py::module &);
 void init_Record(py::module &);
 void init_RecordComponent(py::module &);
 void init_Series(py::module &);
+void init_UnitDimension(py::module &);
 
 
 PYBIND11_MODULE(openpmd_api, m) {
     // m.doc() = ...;
 
     // note: order from parent to child classes
     init_AccessType(m);
+    init_UnitDimension(m);
     init_Attributable(m);
     init_Container(m);
     init_BaseRecord(m);