42 defining specific doxygen APIs

cmake/CompilerWarnings.cmake

@@ -2,7 +2,7 @@
 # different compilers and build settings.
 function(set_project_warnings project_name)
     # Create option for forcing errors for all warnings.
-    option(WARNINGS_AS_ERRORS "Treat compiler warnings as errors" OFF)
+    option(WARNINGS_AS_ERRORS "Treat compiler warnings as errors" ON)
 
     # Create option to turn on sanitizers.
     option(USE_SANITIZERS "Turn on sanitizers to help reporting of runtime errors" OFF)

cmake/Doxygen.cmake

@@ -21,8 +21,11 @@ function(enable_doxygen)
         set(DOXYGEN_JAVADOC_BLOCK NO)
         set(DOXYGEN_FULL_PATH_NAMES NO)
         set(DOXYGEN_STRIP_CODE_COMMENTS NO)
-        set(DOXYGEN_FILE_PATTERNS  *.c *.cpp *.h *.f90 *.F90 *.md)
+        set(DOXYGEN_FILE_PATTERNS  *.c *.cpp *.h *.f90 *.F90 *.md )
         set(DOXYGEN_EXTENSION_MAPPING "F90=Fortran")
+        set(DOXYGEN_SORT_MEMBER_DOCS NO)
+        set(DOXYGEN_WARN_AS_ERROR NO)
+        set(DOXYGEN_LAYOUT_FILE ${PROJECT_SOURCE_DIR}/documentation/Doxygen/DoxygenLayout.xml)
         set(DOXYGEN_HTML_HEADER ${PROJECT_SOURCE_DIR}/documentation/Doxygen/html/header.html)
         set(DOXYGEN_HTML_FOOTER ${PROJECT_SOURCE_DIR}/documentation/Doxygen/html/footer.html)
 

documentation/Doxygen/DoxygenLayout.xml

@@ -0,0 +1,240 @@
+<doxygenlayout version="1.0">
+  <!-- Generated by doxygen 1.9.4 -->
+  <!-- Navigation index tabs for HTML output -->
+  <navindex>
+    <tab type="mainpage" visible="yes" title=""/>
+    <tab type="pages" visible="yes" title="" intro=""/>
+    <tab type="modules" visible="yes" title="API" intro=""/>
+    <tab type="namespaces" visible="yes" title="">
+      <tab type="namespacelist" visible="yes" title="" intro=""/>
+      <tab type="namespacemembers" visible="yes" title="" intro=""/>
+    </tab>
+    <tab type="concepts" visible="yes" title="">
+    </tab>
+    <tab type="interfaces" visible="yes" title="">
+      <tab type="interfacelist" visible="yes" title="" intro=""/>
+      <tab type="interfaceindex" visible="$ALPHABETICAL_INDEX" title=""/>
+      <tab type="interfacehierarchy" visible="yes" title="" intro=""/>
+    </tab>
+    <tab type="classes" visible="yes" title="">
+      <tab type="classlist" visible="yes" title="" intro=""/>
+      <tab type="classindex" visible="$ALPHABETICAL_INDEX" title=""/>
+      <tab type="hierarchy" visible="yes" title="" intro=""/>
+      <tab type="classmembers" visible="yes" title="" intro=""/>
+    </tab>
+    <tab type="structs" visible="yes" title="">
+      <tab type="structlist" visible="yes" title="" intro=""/>
+      <tab type="structindex" visible="$ALPHABETICAL_INDEX" title=""/>
+    </tab>
+    <tab type="exceptions" visible="yes" title="">
+      <tab type="exceptionlist" visible="yes" title="" intro=""/>
+      <tab type="exceptionindex" visible="$ALPHABETICAL_INDEX" title=""/>
+      <tab type="exceptionhierarchy" visible="yes" title="" intro=""/>
+    </tab>
+    <tab type="files" visible="yes" title="">
+      <tab type="filelist" visible="yes" title="" intro=""/>
+      <tab type="globals" visible="yes" title="" intro=""/>
+    </tab>
+    <tab type="examples" visible="yes" title="" intro=""/>
+  </navindex>
+
+  <!-- Layout definition for a class page -->
+  <class>
+    <briefdescription visible="yes"/>
+    <includes visible="$SHOW_HEADERFILE"/>
+    <inheritancegraph visible="$CLASS_GRAPH"/>
+    <collaborationgraph visible="$COLLABORATION_GRAPH"/>
+    <memberdecl>
+      <nestedclasses visible="yes" title=""/>
+      <publictypes title=""/>
+      <services title=""/>
+      <interfaces title=""/>
+      <publicslots title=""/>
+      <signals title=""/>
+      <publicmethods title=""/>
+      <publicstaticmethods title=""/>
+      <publicattributes title=""/>
+      <publicstaticattributes title=""/>
+      <protectedtypes title=""/>
+      <protectedslots title=""/>
+      <protectedmethods title=""/>
+      <protectedstaticmethods title=""/>
+      <protectedattributes title=""/>
+      <protectedstaticattributes title=""/>
+      <packagetypes title=""/>
+      <packagemethods title=""/>
+      <packagestaticmethods title=""/>
+      <packageattributes title=""/>
+      <packagestaticattributes title=""/>
+      <properties title=""/>
+      <events title=""/>
+      <privatetypes title=""/>
+      <privateslots title=""/>
+      <privatemethods title=""/>
+      <privatestaticmethods title=""/>
+      <privateattributes title=""/>
+      <privatestaticattributes title=""/>
+      <friends title=""/>
+      <related title="" subtitle=""/>
+      <membergroups visible="yes"/>
+    </memberdecl>
+    <detaileddescription title=""/>
+    <memberdef>
+      <inlineclasses title=""/>
+      <typedefs title=""/>
+      <enums title=""/>
+      <services title=""/>
+      <interfaces title=""/>
+      <constructors title=""/>
+      <functions title=""/>
+      <related title=""/>
+      <variables title=""/>
+      <properties title=""/>
+      <events title=""/>
+    </memberdef>
+    <allmemberslink visible="yes"/>
+    <usedfiles visible="$SHOW_USED_FILES"/>
+    <authorsection visible="yes"/>
+  </class>
+
+  <!-- Layout definition for a namespace page -->
+  <namespace>
+    <briefdescription visible="yes"/>
+    <memberdecl>
+      <nestednamespaces visible="yes" title=""/>
+      <constantgroups visible="yes" title=""/>
+      <interfaces visible="yes" title=""/>
+      <classes visible="yes" title=""/>
+      <concepts visible="yes" title=""/>
+      <structs visible="yes" title=""/>
+      <exceptions visible="yes" title=""/>
+      <typedefs title=""/>
+      <sequences title=""/>
+      <dictionaries title=""/>
+      <enums title=""/>
+      <functions title=""/>
+      <variables title=""/>
+      <membergroups visible="yes"/>
+    </memberdecl>
+    <detaileddescription title=""/>
+    <memberdef>
+      <inlineclasses title=""/>
+      <typedefs title=""/>
+      <sequences title=""/>
+      <dictionaries title=""/>
+      <enums title=""/>
+      <functions title=""/>
+      <variables title=""/>
+    </memberdef>
+    <authorsection visible="yes"/>
+  </namespace>
+
+  <!-- Layout definition for a concept page -->
+  <concept>
+    <briefdescription visible="yes"/>
+    <includes visible="$SHOW_HEADERFILE"/>
+    <definition visible="yes" title=""/>
+    <detaileddescription title=""/>
+    <authorsection visible="yes"/>
+  </concept>
+
+  <!-- Layout definition for a file page -->
+  <file>
+    <briefdescription visible="yes"/>
+    <includes visible="$SHOW_INCLUDE_FILES"/>
+    <includegraph visible="$INCLUDE_GRAPH"/>
+    <includedbygraph visible="$INCLUDED_BY_GRAPH"/>
+    <sourcelink visible="yes"/>
+    <memberdecl>
+      <interfaces visible="yes" title=""/>
+      <classes visible="yes" title=""/>
+      <structs visible="yes" title=""/>
+      <exceptions visible="yes" title=""/>
+      <namespaces visible="yes" title=""/>
+      <concepts visible="yes" title=""/>
+      <constantgroups visible="yes" title=""/>
+      <defines title=""/>
+      <typedefs title=""/>
+      <sequences title=""/>
+      <dictionaries title=""/>
+      <enums title=""/>
+      <functions title=""/>
+      <variables title=""/>
+      <membergroups visible="yes"/>
+    </memberdecl>
+    <detaileddescription title=""/>
+    <memberdef>
+      <inlineclasses title=""/>
+      <defines title=""/>
+      <typedefs title=""/>
+      <sequences title=""/>
+      <dictionaries title=""/>
+      <enums title=""/>
+      <functions title=""/>
+      <variables title=""/>
+    </memberdef>
+    <authorsection/>
+  </file>
+
+  <!-- Layout definition for a group page -->
+  <group>
+    <briefdescription visible="yes"/>
+    <groupgraph visible="$GROUP_GRAPHS"/>
+    <memberdecl>
+      <nestedgroups visible="yes" title=""/>
+      <dirs visible="yes" title=""/>
+      <files visible="yes" title=""/>
+      <namespaces visible="yes" title=""/>
+      <concepts visible="yes" title=""/>
+      <classes visible="yes" title=""/>
+      <defines title=""/>
+      <typedefs title=""/>
+      <sequences title=""/>
+      <dictionaries title=""/>
+      <enums title=""/>
+      <enumvalues title=""/>
+      <functions title=""/>
+      <variables title=""/>
+      <signals title=""/>
+      <publicslots title=""/>
+      <protectedslots title=""/>
+      <privateslots title=""/>
+      <events title=""/>
+      <properties title=""/>
+      <friends title=""/>
+      <membergroups visible="yes"/>
+    </memberdecl>
+    <detaileddescription title=""/>
+    <memberdef>
+      <pagedocs/>
+      <inlineclasses title=""/>
+      <defines title=""/>
+      <typedefs title=""/>
+      <sequences title=""/>
+      <dictionaries title=""/>
+      <enums title=""/>
+      <enumvalues title=""/>
+      <functions title=""/>
+      <variables title=""/>
+      <signals title=""/>
+      <publicslots title=""/>
+      <protectedslots title=""/>
+      <privateslots title=""/>
+      <events title=""/>
+      <properties title=""/>
+      <friends title=""/>
+    </memberdef>
+    <authorsection visible="yes"/>
+  </group>
+
+  <!-- Layout definition for a directory page -->
+  <directory>
+    <briefdescription visible="yes"/>
+    <directorygraph visible="yes"/>
+    <memberdecl>
+      <dirs visible="yes"/>
+      <files visible="yes"/>
+    </memberdecl>
+    <detaileddescription title=""/>
+  </directory>
+</doxygenlayout>

documentation/Doxygen/Profiler.md

@@ -48,4 +48,4 @@ class A {
 
 ## Communication Efficiency {#comme}
 
-TBD
+TBD

src/c++/profiler.cpp

@@ -39,11 +39,6 @@ Profiler::Profiler(){
 
 }
 
-/**
- * @brief  Start timing.
- *
- */
-
 size_t Profiler::start(std::string_view region_name)
 {
 
@@ -66,11 +61,6 @@ size_t Profiler::start(std::string_view region_name)
   return hash;
 }
 
-/**
- * @brief  Stop timing.
- *
- */
-
 void Profiler::stop(size_t const hash)
 {
 
@@ -109,11 +99,6 @@ void Profiler::stop(size_t const hash)
 
 }
 
-/**
- * @brief  Write profile information.
- *
- */
-
 void Profiler::write()
 {
   // Write each one
@@ -123,19 +108,6 @@ void Profiler::write()
   }
 }
 
-/**
- * @brief  Get the total (inclusive) time of everything below the specified hash.
- *
- * @param[in] hash  The hash corresponding to the region of interest. 
- *
- * @note   This function is normally expected to be used to return the total
- *         wallclock time for whole run. Since this value is required only from
- *         thread 0, the function does not take a thread ID argument and returns
- *         the value for thread 0 only. Taking the hash argument avoids the need
- *         to store the top-level hash inside the profiler itself.
- *
- */
-
 double Profiler::get_thread0_walltime(size_t const hash)
 {
   auto tid = static_cast<hashtable_iterator_t_>(0);

src/c++/profiler.h

@@ -25,6 +25,11 @@
 
 #include "hashtable.h"
 
+/**
+ * @defgroup API C++
+ * @brief C++ API for the profiler
+ */
+
 /**
  * @brief  Top-level profiler class.
  *
@@ -49,13 +54,53 @@ class Profiler
   public:
 
     // Constructors
+/**
+ * @ingroup API
+ * @brief Constructor for profiler class
+ */
     Profiler();
 
     // Member functions
-    size_t start(std::string_view);
-    void   stop (size_t const);
+
+/**
+ * @ingroup API
+ * @brief  Start timing.
+ *
+ * @param[in] region_name A unique name for the region being timed.
+ *
+ */
+    size_t start(std::string_view region_name);
+
+/**
+ * @ingroup API
+ * @brief  Stop timing.
+ *
+ * @param[in] hash  The hash corresponding to the region to be stopped.
+ */
+    void   stop (size_t hash);
+
+/**
+ * @ingroup API
+ * @brief  Write profile information.
+ *
+ */
     void   write();
-    double get_thread0_walltime(size_t const);
+
+
+/**
+ * @ingroup API
+ * @brief  Get the total (inclusive) time of everything below the specified hash.
+ *
+ * @param[in] hash  The hash corresponding to the region of interest.
+ *
+ * @note   This function is normally expected to be used to return the total
+ *         wallclock time for whole run. Since this value is required only from
+ *         thread 0, the function does not take a thread ID argument and returns
+ *         the value for thread 0 only. Taking the hash argument avoids the need
+ *         to store the top-level hash inside the profiler itself.
+ *
+ */
+    double get_thread0_walltime(size_t hash);
 };
 
 // Declare global profiler