Fix doxygen errors (#3962)

* Switch warnings as errors to default OFF * Enable mac docs * Add doxygen action uses step * Use html div around snippet * Allow preset name to be an argument to cmake-ctest.yml
HDFGroup · Jan 29, 2024 · 365e233 · 365e233
1 parent 1bea9e6
commit 365e233
Show file tree

Hide file tree

Showing 37 changed files with 209 additions and 72 deletions.
diff --git a/.github/workflows/cmake-ctest.yml b/.github/workflows/cmake-ctest.yml
@@ -8,6 +8,10 @@ on:
         description: "The common base name of the source tarballs"
         required: true
         type: string
+      preset_name:
+        description: "The common base name of the preset configuration name to control the build"
+        required: true
+        type: string
 
 permissions:
   contents: read
@@ -24,6 +28,11 @@ jobs:
       - name: Install Dependencies (Windows)
         run: choco install ninja
 
+      - name: Install Dependencies
+        uses: ssciwr/doxygen-install@v1
+        with:
+          version: "1.10.0"
+
       - name: Enable Developer Command Prompt
         uses: ilammy/[email protected]
 
@@ -59,7 +68,7 @@ jobs:
       - name: Run ctest (Windows)
         run: |
           cd "${{ runner.workspace }}/hdf5/hdfsrc"
-          cmake --workflow --preset=ci-StdShar-MSVC --fresh
+          cmake --workflow --preset=${{ inputs.preset_name }}-MSVC --fresh
         shell: bash
 
       - name: Publish binary (Windows)
@@ -70,7 +79,7 @@ jobs:
           Copy-Item -Path ${{ runner.workspace }}/hdf5/hdfsrc/COPYING -Destination ${{ runner.workspace }}/build/hdf5/
           Copy-Item -Path ${{ runner.workspace }}/hdf5/hdfsrc/COPYING_LBNL_HDF5 -Destination ${{ runner.workspace }}/build/hdf5/
           Copy-Item -Path ${{ runner.workspace }}/hdf5/hdfsrc/README.md -Destination ${{ runner.workspace }}/build/hdf5/
-          Copy-Item -Path ${{ runner.workspace }}/hdf5/build/ci-StdShar-MSVC/* -Destination ${{ runner.workspace }}/build/hdf5/ -Include *.zip
+          Copy-Item -Path ${{ runner.workspace }}/hdf5/build/${{ inputs.preset_name }}-MSVC/* -Destination ${{ runner.workspace }}/build/hdf5/ -Include *.zip
           cd "${{ runner.workspace }}/build"
           7z a -tzip ${{ steps.set-file-base.outputs.FILE_BASE }}-win-vs2022_cl.zip hdf5
         shell: pwsh
@@ -96,7 +105,12 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Install CMake Dependencies (Linux)
-        run: sudo apt-get install ninja-build doxygen graphviz
+        run: sudo apt-get install ninja-build graphviz
+
+      - name: Install Dependencies
+        uses: ssciwr/doxygen-install@v1
+        with:
+          version: "1.10.0"
 
       - name: Set file base name (Linux)
         id: set-file-base
@@ -122,7 +136,7 @@ jobs:
       - name: Run ctest (Linux)
         run: |
           cd "${{ runner.workspace }}/hdf5/hdfsrc"
-          cmake --workflow --preset=ci-StdShar-GNUC --fresh
+          cmake --workflow --preset=${{ inputs.preset_name }}-GNUC --fresh
         shell: bash
 
       - name: Publish binary (Linux)
@@ -133,7 +147,7 @@ jobs:
           cp ${{ runner.workspace }}/hdf5/hdfsrc/COPYING ${{ runner.workspace }}/build/hdf5
           cp ${{ runner.workspace }}/hdf5/hdfsrc/COPYING_LBNL_HDF5 ${{ runner.workspace }}/build/hdf5
           cp ${{ runner.workspace }}/hdf5/hdfsrc/README.md ${{ runner.workspace }}/build/hdf5
-          cp ${{ runner.workspace }}/hdf5/build/ci-StdShar-GNUC/*.tar.gz ${{ runner.workspace }}/build/hdf5
+          cp ${{ runner.workspace }}/hdf5/build/${{ inputs.preset_name }}-GNUC/*.tar.gz ${{ runner.workspace }}/build/hdf5
           cd "${{ runner.workspace }}/build"
           tar -zcvf ${{ steps.set-file-base.outputs.FILE_BASE }}-ubuntu-2204_gcc.tar.gz hdf5
         shell: bash
@@ -156,7 +170,7 @@ jobs:
         uses: actions/upload-artifact@v4
         with:
               name: docs-doxygen
-              path: ${{ runner.workspace }}/hdf5/build/ci-StdShar-GNUC/hdf5lib_docs/html
+              path: ${{ runner.workspace }}/hdf5/build/${{ inputs.preset_name }}-GNUC/hdf5lib_docs/html
               if-no-files-found: error # 'warn' or 'ignore' are also available, defaults to `warn`
 
   build_and_test_mac:
@@ -166,7 +180,12 @@ jobs:
     runs-on: macos-11
     steps:
       - name: Install Dependencies (MacOS)
-        run: brew install ninja doxygen
+        run: brew install ninja
+
+      - name: Install Dependencies
+        uses: ssciwr/doxygen-install@v1
+        with:
+          version: "1.10.0"
 
       - name: Set file base name (MacOS)
         id: set-file-base
@@ -201,7 +220,7 @@ jobs:
         id: run-ctest
         run: |
           cd "${{ runner.workspace }}/hdf5/hdfsrc"
-          cmake --workflow --preset=ci-StdShar-Clang --fresh
+          cmake --workflow --preset=${{ inputs.preset_name }}-Clang --fresh
         shell: bash
 
       - name: Publish binary (MacOS)
@@ -212,7 +231,7 @@ jobs:
           cp ${{ runner.workspace }}/hdf5/hdfsrc/COPYING ${{ runner.workspace }}/build/hdf5
           cp ${{ runner.workspace }}/hdf5/hdfsrc/COPYING_LBNL_HDF5 ${{ runner.workspace }}/build/hdf5
           cp ${{ runner.workspace }}/hdf5/hdfsrc/README.md ${{ runner.workspace }}/build/hdf5
-          cp ${{ runner.workspace }}/hdf5/build/ci-StdShar-Clang/*.tar.gz ${{ runner.workspace }}/build/hdf5
+          cp ${{ runner.workspace }}/hdf5/build/${{ inputs.preset_name }}-Clang/*.tar.gz ${{ runner.workspace }}/build/hdf5
           cd "${{ runner.workspace }}/build"
           tar -zcvf ${{ steps.set-file-base.outputs.FILE_BASE }}-osx12.tar.gz hdf5
         shell: bash
@@ -265,7 +284,7 @@ jobs:
       - name: Run ctest (Linux S3)
         run: |
           cd "${{ runner.workspace }}/hdf5/hdfsrc"
-          cmake --workflow --preset=ci-StdShar-GNUC-S3 --fresh
+          cmake --workflow --preset=${{ inputs.preset_name }}-GNUC-S3 --fresh
         shell: bash
 
       - name: Publish binary (Linux S3)
@@ -276,7 +295,7 @@ jobs:
           cp ${{ runner.workspace }}/hdf5/hdfsrc/COPYING ${{ runner.workspace }}/build/hdf5
           cp ${{ runner.workspace }}/hdf5/hdfsrc/COPYING_LBNL_HDF5 ${{ runner.workspace }}/build/hdf5
           cp ${{ runner.workspace }}/hdf5/hdfsrc/README.md ${{ runner.workspace }}/build/hdf5
-          cp ${{ runner.workspace }}/hdf5/build/ci-StdShar-GNUC-S3/*.tar.gz ${{ runner.workspace }}/build/hdf5
+          cp ${{ runner.workspace }}/hdf5/build/${{ inputs.preset_name }}-GNUC-S3/*.tar.gz ${{ runner.workspace }}/build/hdf5
           cd "${{ runner.workspace }}/build"
           tar -zcvf ${{ steps.set-file-base.outputs.FILE_BASE }}-ubuntu-2204_gcc_s3.tar.gz hdf5
         shell: bash
@@ -350,7 +369,7 @@ jobs:
           CXX: ${{ steps.setup-fortran.outputs.cxx }}
         run: |
           cd "${{ runner.workspace }}/hdf5/hdfsrc"
-          cmake --workflow --preset=ci-StdShar-Intel --fresh
+          cmake --workflow --preset=${{ inputs.preset_name }}-Intel --fresh
         shell: pwsh
 
       - name: Publish binary (Windows_intel)
@@ -361,7 +380,7 @@ jobs:
           Copy-Item -Path ${{ runner.workspace }}/hdf5/hdfsrc/COPYING -Destination ${{ runner.workspace }}/build/hdf5/
           Copy-Item -Path ${{ runner.workspace }}/hdf5/hdfsrc/COPYING_LBNL_HDF5 -Destination ${{ runner.workspace }}/build/hdf5/
           Copy-Item -Path ${{ runner.workspace }}/hdf5/hdfsrc/README.md -Destination ${{ runner.workspace }}/build/hdf5/
-          Copy-Item -Path ${{ runner.workspace }}/hdf5/build/ci-StdShar-Intel/* -Destination ${{ runner.workspace }}/build/hdf5/ -Include *.zip
+          Copy-Item -Path ${{ runner.workspace }}/hdf5/build/${{ inputs.preset_name }}-Intel/* -Destination ${{ runner.workspace }}/build/hdf5/ -Include *.zip
           cd "${{ runner.workspace }}/build"
           7z a -tzip ${{ steps.set-file-base.outputs.FILE_BASE }}-win-vs2022_intel.zip hdf5
         shell: pwsh
@@ -424,7 +443,7 @@ jobs:
           CXX: ${{ steps.setup-fortran.outputs.cxx }}
         run: |
           cd "${{ runner.workspace }}/hdf5/hdfsrc"
-          cmake --workflow --preset=ci-StdShar-Intel --fresh
+          cmake --workflow --preset=${{ inputs.preset_name }}-Intel --fresh
         shell: bash
 
       - name: Publish binary (Linux_intel)
@@ -435,7 +454,7 @@ jobs:
           cp ${{ runner.workspace }}/hdf5/hdfsrc/COPYING ${{ runner.workspace }}/build/hdf5
           cp ${{ runner.workspace }}/hdf5/hdfsrc/COPYING_LBNL_HDF5 ${{ runner.workspace }}/build/hdf5
           cp ${{ runner.workspace }}/hdf5/hdfsrc/README.md ${{ runner.workspace }}/build/hdf5
-          cp ${{ runner.workspace }}/hdf5/build/ci-StdShar-Intel/*.tar.gz ${{ runner.workspace }}/build/hdf5
+          cp ${{ runner.workspace }}/hdf5/build/${{ inputs.preset_name }}-Intel/*.tar.gz ${{ runner.workspace }}/build/hdf5
           cd "${{ runner.workspace }}/build"
           tar -zcvf ${{ steps.set-file-base.outputs.FILE_BASE }}-ubuntu-2204_intel.tar.gz hdf5
         shell: bash

diff --git a/.github/workflows/daily-build.yml b/.github/workflows/daily-build.yml
@@ -23,6 +23,7 @@ jobs:
     uses: ./.github/workflows/cmake-ctest.yml
     with:
       file_base: ${{ needs.call-workflow-tarball.outputs.file_base }}
+      preset_name: ci-StdShar
       #use_tag: snapshot
       #use_environ: snapshots
     if: ${{ needs.call-workflow-tarball.outputs.has_changes == 'true' }}

diff --git a/.github/workflows/main-cmake.yml b/.github/workflows/main-cmake.yml
@@ -52,7 +52,7 @@ jobs:
             cpp: ON
             fortran: OFF
             java: ON
-            docs: OFF
+            docs: ON
             libaecfc: ON
             localaec: OFF
             zlibfc: ON
@@ -96,7 +96,7 @@ jobs:
             cpp: ON
             fortran: OFF
             java: ON
-            docs: OFF
+            docs: ON
             libaecfc: ON
             localaec: OFF
             zlibfc: ON
@@ -136,7 +136,7 @@ jobs:
       - name: Install Linux Dependencies
         run: |
            sudo apt update
-           sudo apt-get install ninja-build doxygen graphviz
+           sudo apt-get install ninja-build graphviz
            sudo apt install libssl3 libssl-dev libcurl4 libcurl4-openssl-dev
            sudo apt install gcc-12 g++-12 gfortran-12
            echo "CC=gcc-12" >> $GITHUB_ENV
@@ -151,9 +151,14 @@ jobs:
         if: matrix.os == 'windows-latest'
 
       - name: Install Dependencies (macOS)
-        run: brew install ninja doxygen
+        run: brew install ninja
         if: matrix.os == 'macos-13'
 
+      - name: Install Dependencies
+        uses: ssciwr/doxygen-install@v1
+        with:
+          version: "1.9.7"
+
       - name: Set environment for MSVC (Windows)
         run: |
           # Set these environment variables so CMake picks the correct compiler
@@ -179,6 +184,7 @@ jobs:
             -DCMAKE_TOOLCHAIN_FILE=${{ matrix.toolchain }} \
             -DBUILD_SHARED_LIBS=ON \
             -DHDF5_ENABLE_ALL_WARNINGS=ON \
+            -DHDF5_ENABLE_DOXY_WARNINGS=ON \
             -DHDF5_ENABLE_PARALLEL:BOOL=${{ matrix.parallel }} \
             -DHDF5_BUILD_CPP_LIB:BOOL=${{ matrix.cpp }} \
             -DHDF5_BUILD_FORTRAN=${{ matrix.fortran }} \

diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
@@ -84,6 +84,7 @@ jobs:
     uses: ./.github/workflows/cmake-ctest.yml
     with:
       file_base: ${{ needs.create-files-ctest.outputs.file_base }}
+      preset_name: ci-StdShar
 
   call-workflow-release:
     #needs: [call-workflow-tarball, call-workflow-ctest]

diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -961,7 +961,7 @@ if (HDF5_BUILD_DOC AND EXISTS "${HDF5_DOXYGEN_DIR}" AND IS_DIRECTORY "${HDF5_DOX
 # check if Doxygen is installed
   find_package(Doxygen)
   if (DOXYGEN_FOUND)
-    option (HDF5_ENABLE_DOXY_WARNINGS "Enable fail if doxygen parsing has warnings." ON)
+    option (HDF5_ENABLE_DOXY_WARNINGS "Enable fail if doxygen parsing has warnings." OFF)
     mark_as_advanced (HDF5_ENABLE_DOXY_WARNINGS)
     if (HDF5_ENABLE_DOXY_WARNINGS)
       set (HDF5_DOXY_WARNINGS "FAIL_ON_WARNINGS")

diff --git a/configure.ac b/configure.ac
@@ -1220,14 +1220,14 @@ AC_MSG_RESULT([$HDF5_DOXYGEN])
 ## This needs to be exposed for the library info file.
 AC_SUBST([HDF5_DOXY_WARNINGS])
 
-## Default is to consider doxygen warnings as errors
+## Default is not to consider doxygen warnings as errors
 DOXY_ERR=yes
 
 AC_MSG_CHECKING([if doxygen warnings as errors is enabled])
 
 AC_ARG_ENABLE([doxygen-errors],
               [AS_HELP_STRING([--enable-doxygen-errors],
-                              [Error on HDF5 doxygen warnings [default=yes]])],
+                              [Error on HDF5 doxygen warnings [default=no]])],
               [DOXY_ERR=$enableval])
 
 if test "X$DOXY_ERR" = "Xyes"; then

diff --git a/doxygen/dox/LearnBasics3.dox b/doxygen/dox/LearnBasics3.dox
@@ -288,7 +288,7 @@ is met, at a certain point in the future.)
 
 \section secLBContentsProg Programming Example
 
-\subsection subsecLBContentsProgUsing Using #H5Literate, #H5Lvisit and #H5Ovisit
+\subsection subsecLBContentsProgUsing Using H5Literate, H5Lvisit and H5Ovisit
 For example code, see the \ref HDF5Examples page.
 Specifically look at the \ref ExAPI.
 There are examples for different languages, where examples of using #H5Literate and #H5Ovisit/#H5Lvisit are included.

diff --git a/doxygen/dox/PredefinedDatatypeTables.dox b/doxygen/dox/PredefinedDatatypeTables.dox
@@ -1,22 +1,41 @@
 /** \page predefined_datatypes_tables HDF5 Predefined Datatypes
+  *
+ * \section sec_predefined_datatypes_tables HDF5 Predefined Datatypes
  *
  * The following datatypes are predefined in HDF5.
- *
+ * <div>
  * \snippet{doc} tables/predefinedDatatypes.dox predefined_ieee_datatypes_table
+ * </div>
  * 
+ * <div>
  * \snippet{doc} tables/predefinedDatatypes.dox predefined_std_datatypes_table
- *
+ * </div>
+ * 
+ * <div>
  * \snippet{doc} tables/predefinedDatatypes.dox predefined_unix_datatypes_table
- *
+ * </div>
+ * 
+ * <div>
  * \snippet{doc} tables/predefinedDatatypes.dox predefined_string_datatypes_table
- *
+ * </div>
+ * 
+ * <div>
  * \snippet{doc} tables/predefinedDatatypes.dox predefined_intel_datatypes_table
- *
+ * </div>
+ * 
+ * <div>
  * \snippet{doc} tables/predefinedDatatypes.dox predefined_dec_datatypes_table
- *
+ * </div>
+ * 
+ * <div>
  * \snippet{doc} tables/predefinedDatatypes.dox predefined_mips_datatypes_table
- *
+ * </div>
+ * 
+ * <div>
  * \snippet{doc} tables/predefinedDatatypes.dox predefined_native_datatypes_table
- *
+ * </div>
+ * 
+ * <div>
  * \snippet{doc} tables/predefinedDatatypes.dox predefined_c9x_datatypes_table
+ * </div>
  */
diff --git a/doxygen/examples/tables/fileDriverLists.dox b/doxygen/examples/tables/fileDriverLists.dox
@@ -1,5 +1,4 @@
 /** File Driver List
- *
 //! [file_driver_table]
 <table>
 <caption>I/O file drivers</caption>
@@ -70,7 +69,6 @@
 </table>
 //! [file_driver_table]
  *
- *
 //! [supported_file_driver_table]
 <table>
 <caption id="table_file_drivers">Supported file drivers</caption>

diff --git a/java/src/hdf/hdf5lib/CMakeLists.txt b/java/src/hdf/hdf5lib/CMakeLists.txt
@@ -10,6 +10,7 @@ SET_GLOBAL_VARIABLE (HDF5_JAVA_SOURCE_PACKAGES
 )
 
 set (HDF5_JAVA_HDF_HDF5_CALLBACKS_SOURCES
+    callbacks/Callbacks.java
     callbacks/H5A_iterate_cb.java
     callbacks/H5A_iterate_t.java
     callbacks/H5D_append_cb.java
@@ -37,7 +38,6 @@ set (HDF5_JAVA_HDF_HDF5_CALLBACKS_SOURCES
     callbacks/H5P_prp_set_func_cb.java
     callbacks/H5P_iterate_cb.java
     callbacks/H5P_iterate_t.java
-    callbacks/Callbacks.java
 )
 
 set (HDF5_JAVADOC_HDF_HDF5_CALLBACKS_SOURCES

diff --git a/java/src/hdf/hdf5lib/callbacks/Callbacks.java b/java/src/hdf/hdf5lib/callbacks/Callbacks.java
@@ -28,7 +28,7 @@
  * exceptions thrown will be passed to the default callback exception
  * handler.
  *
- * @defgroup JCALL HDF5 Library Java Callbacks
+ * @defgroup JCALLBK HDF5 Library Java Callbacks
  */
 public interface Callbacks {
 }
diff --git a/java/src/hdf/hdf5lib/callbacks/H5A_iterate_cb.java b/java/src/hdf/hdf5lib/callbacks/H5A_iterate_cb.java
@@ -20,7 +20,7 @@
  */
 public interface H5A_iterate_cb extends Callbacks {
     /**
-     * @ingroup JCALL
+     * @ingroup JCALLBK
      *
      *  application callback for each attribute
      *

diff --git a/java/src/hdf/hdf5lib/callbacks/H5D_append_cb.java b/java/src/hdf/hdf5lib/callbacks/H5D_append_cb.java
@@ -18,7 +18,7 @@
  */
 public interface H5D_append_cb extends Callbacks {
     /**
-     * @ingroup JCALL
+     * @ingroup JCALLBK
      *
      *  application callback for each dataset access property list
      *

diff --git a/java/src/hdf/hdf5lib/callbacks/H5D_iterate_cb.java b/java/src/hdf/hdf5lib/callbacks/H5D_iterate_cb.java
@@ -18,7 +18,7 @@
  */
 public interface H5D_iterate_cb extends Callbacks {
     /**
-     * @ingroup JCALL
+     * @ingroup JCALLBK
      *
      *  application callback for each dataset element
      *

diff --git a/java/src/hdf/hdf5lib/callbacks/H5E_walk_cb.java b/java/src/hdf/hdf5lib/callbacks/H5E_walk_cb.java
@@ -20,7 +20,7 @@
  */
 public interface H5E_walk_cb extends Callbacks {
     /**
-     * @ingroup JCALL
+     * @ingroup JCALLBK
      *
      *  application callback for each error stack element
      *