From 365e23340cd001ee751da366235ae420156ad728 Mon Sep 17 00:00:00 2001 From: Allen Byrne <50328838+byrnHDF@users.noreply.github.com> Date: Mon, 29 Jan 2024 07:38:54 -0600 Subject: 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 --- .github/workflows/cmake-ctest.yml | 49 +++++++++----- .github/workflows/daily-build.yml | 1 + .github/workflows/main-cmake.yml | 14 ++-- .github/workflows/release.yml | 1 + CMakeLists.txt | 2 +- configure.ac | 4 +- doxygen/dox/LearnBasics3.dox | 2 +- doxygen/dox/PredefinedDatatypeTables.dox | 35 +++++++--- doxygen/examples/tables/fileDriverLists.dox | 2 - java/src/hdf/hdf5lib/CMakeLists.txt | 2 +- java/src/hdf/hdf5lib/callbacks/Callbacks.java | 2 +- java/src/hdf/hdf5lib/callbacks/H5A_iterate_cb.java | 2 +- java/src/hdf/hdf5lib/callbacks/H5D_append_cb.java | 2 +- java/src/hdf/hdf5lib/callbacks/H5D_iterate_cb.java | 2 +- java/src/hdf/hdf5lib/callbacks/H5E_walk_cb.java | 2 +- java/src/hdf/hdf5lib/callbacks/H5L_iterate_t.java | 2 +- java/src/hdf/hdf5lib/callbacks/H5O_iterate_t.java | 2 +- .../hdf5lib/callbacks/H5P_cls_close_func_cb.java | 2 +- .../hdf5lib/callbacks/H5P_cls_copy_func_cb.java | 2 +- .../hdf5lib/callbacks/H5P_cls_create_func_cb.java | 2 +- java/src/hdf/hdf5lib/callbacks/H5P_iterate_cb.java | 2 +- .../hdf5lib/callbacks/H5P_prp_close_func_cb.java | 2 +- .../hdf5lib/callbacks/H5P_prp_compare_func_cb.java | 2 +- .../hdf5lib/callbacks/H5P_prp_copy_func_cb.java | 2 +- .../hdf5lib/callbacks/H5P_prp_create_func_cb.java | 2 +- .../hdf5lib/callbacks/H5P_prp_delete_func_cb.java | 2 +- .../hdf/hdf5lib/callbacks/H5P_prp_get_func_cb.java | 2 +- .../hdf/hdf5lib/callbacks/H5P_prp_set_func_cb.java | 2 +- release_docs/INSTALL_CMake.txt | 2 +- release_docs/RELEASE.txt | 9 +++ src/H5Dmodule.h | 9 +++ src/H5Fmodule.h | 9 ++- src/H5Gmodule.h | 2 + src/H5Pmodule.h | 75 +++++++++++++++++----- src/H5Ppublic.h | 3 +- src/H5Tmodule.h | 18 ++++++ src/H5VLmodule.h | 6 ++ 37 files changed, 209 insertions(+), 72 deletions(-) diff --git a/.github/workflows/cmake-ctest.yml b/.github/workflows/cmake-ctest.yml index aa13922..00fb7b4 100644 --- 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/msvc-dev-cmd@v1.13.0 @@ -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 index 5633b3c..952b9db 100644 --- 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 index 7669bd9..3294fb1 100644 --- 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 index 28f2425..3bf79f4 100644 --- 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 index 9fe0b49..f536a4a 100644 --- 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 index 92eff58..9fd0fa5 100644 --- 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 index abfb7b1..1955f1f 100644 --- 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 index fbafa94..0b40516 100644 --- 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. - * + *
* \snippet{doc} tables/predefinedDatatypes.dox predefined_ieee_datatypes_table + *
* + *
* \snippet{doc} tables/predefinedDatatypes.dox predefined_std_datatypes_table - * + *
+ * + *
* \snippet{doc} tables/predefinedDatatypes.dox predefined_unix_datatypes_table - * + *
+ * + *
* \snippet{doc} tables/predefinedDatatypes.dox predefined_string_datatypes_table - * + *
+ * + *
* \snippet{doc} tables/predefinedDatatypes.dox predefined_intel_datatypes_table - * + *
+ * + *
* \snippet{doc} tables/predefinedDatatypes.dox predefined_dec_datatypes_table - * + *
+ * + *
* \snippet{doc} tables/predefinedDatatypes.dox predefined_mips_datatypes_table - * + *
+ * + *
* \snippet{doc} tables/predefinedDatatypes.dox predefined_native_datatypes_table - * + *
+ * + *
* \snippet{doc} tables/predefinedDatatypes.dox predefined_c9x_datatypes_table + *
*/ diff --git a/doxygen/examples/tables/fileDriverLists.dox b/doxygen/examples/tables/fileDriverLists.dox index b1f873f..437d32a 100644 --- a/doxygen/examples/tables/fileDriverLists.dox +++ b/doxygen/examples/tables/fileDriverLists.dox @@ -1,5 +1,4 @@ /** File Driver List - * //! [file_driver_table] @@ -70,7 +69,6 @@
I/O file drivers
//! [file_driver_table] * - * //! [supported_file_driver_table] diff --git a/java/src/hdf/hdf5lib/CMakeLists.txt b/java/src/hdf/hdf5lib/CMakeLists.txt index 41cf4e9..69b5a93 100644 --- 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 index 3d5fbd1..013e0ec 100644 --- a/java/src/hdf/hdf5lib/callbacks/Callbacks.java +++ b/java/src/hdf/hdf5lib/callbacks/Callbacks.java @@ -28,7 +28,7 @@ package hdf.hdf5lib.callbacks; * 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 index 9958b3b..2d37044 100644 --- a/java/src/hdf/hdf5lib/callbacks/H5A_iterate_cb.java +++ b/java/src/hdf/hdf5lib/callbacks/H5A_iterate_cb.java @@ -20,7 +20,7 @@ import hdf.hdf5lib.structs.H5A_info_t; */ 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 index 49323a2..92024f8 100644 --- a/java/src/hdf/hdf5lib/callbacks/H5D_append_cb.java +++ b/java/src/hdf/hdf5lib/callbacks/H5D_append_cb.java @@ -18,7 +18,7 @@ package hdf.hdf5lib.callbacks; */ 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 index 5f77998..f9ea6a9 100644 --- a/java/src/hdf/hdf5lib/callbacks/H5D_iterate_cb.java +++ b/java/src/hdf/hdf5lib/callbacks/H5D_iterate_cb.java @@ -18,7 +18,7 @@ package hdf.hdf5lib.callbacks; */ 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 index a8ef5df..a9690a5 100644 --- a/java/src/hdf/hdf5lib/callbacks/H5E_walk_cb.java +++ b/java/src/hdf/hdf5lib/callbacks/H5E_walk_cb.java @@ -20,7 +20,7 @@ import hdf.hdf5lib.structs.H5E_error2_t; */ public interface H5E_walk_cb extends Callbacks { /** - * @ingroup JCALL + * @ingroup JCALLBK * * application callback for each error stack element * diff --git a/java/src/hdf/hdf5lib/callbacks/H5L_iterate_t.java b/java/src/hdf/hdf5lib/callbacks/H5L_iterate_t.java index 7342e58..cf0ac0e 100644 --- a/java/src/hdf/hdf5lib/callbacks/H5L_iterate_t.java +++ b/java/src/hdf/hdf5lib/callbacks/H5L_iterate_t.java @@ -20,7 +20,7 @@ import hdf.hdf5lib.structs.H5L_info_t; */ public interface H5L_iterate_t extends Callbacks { /** - * @ingroup JCALL + * @ingroup JCALLBK * * application callback for each group * diff --git a/java/src/hdf/hdf5lib/callbacks/H5O_iterate_t.java b/java/src/hdf/hdf5lib/callbacks/H5O_iterate_t.java index bfe8c67..f0dd587 100644 --- a/java/src/hdf/hdf5lib/callbacks/H5O_iterate_t.java +++ b/java/src/hdf/hdf5lib/callbacks/H5O_iterate_t.java @@ -20,7 +20,7 @@ import hdf.hdf5lib.structs.H5O_info_t; */ public interface H5O_iterate_t extends Callbacks { /** - * @ingroup JCALL + * @ingroup JCALLBK * * application callback for each group * diff --git a/java/src/hdf/hdf5lib/callbacks/H5P_cls_close_func_cb.java b/java/src/hdf/hdf5lib/callbacks/H5P_cls_close_func_cb.java index a235861..e4f10cc 100644 --- a/java/src/hdf/hdf5lib/callbacks/H5P_cls_close_func_cb.java +++ b/java/src/hdf/hdf5lib/callbacks/H5P_cls_close_func_cb.java @@ -18,7 +18,7 @@ package hdf.hdf5lib.callbacks; */ public interface H5P_cls_close_func_cb extends Callbacks { /** - * @ingroup JCALL + * @ingroup JCALLBK * * application callback for each property list * diff --git a/java/src/hdf/hdf5lib/callbacks/H5P_cls_copy_func_cb.java b/java/src/hdf/hdf5lib/callbacks/H5P_cls_copy_func_cb.java index b218e0c..bdaad5f 100644 --- a/java/src/hdf/hdf5lib/callbacks/H5P_cls_copy_func_cb.java +++ b/java/src/hdf/hdf5lib/callbacks/H5P_cls_copy_func_cb.java @@ -18,7 +18,7 @@ package hdf.hdf5lib.callbacks; */ public interface H5P_cls_copy_func_cb extends Callbacks { /** - * @ingroup JCALL + * @ingroup JCALLBK * * application callback for each property list * diff --git a/java/src/hdf/hdf5lib/callbacks/H5P_cls_create_func_cb.java b/java/src/hdf/hdf5lib/callbacks/H5P_cls_create_func_cb.java index 3d407d0..0b9ced2 100644 --- a/java/src/hdf/hdf5lib/callbacks/H5P_cls_create_func_cb.java +++ b/java/src/hdf/hdf5lib/callbacks/H5P_cls_create_func_cb.java @@ -18,7 +18,7 @@ package hdf.hdf5lib.callbacks; */ public interface H5P_cls_create_func_cb extends Callbacks { /** - * @ingroup JCALL + * @ingroup JCALLBK * * application callback for each property list * diff --git a/java/src/hdf/hdf5lib/callbacks/H5P_iterate_cb.java b/java/src/hdf/hdf5lib/callbacks/H5P_iterate_cb.java index 51a5768..941fd15 100644 --- a/java/src/hdf/hdf5lib/callbacks/H5P_iterate_cb.java +++ b/java/src/hdf/hdf5lib/callbacks/H5P_iterate_cb.java @@ -18,7 +18,7 @@ package hdf.hdf5lib.callbacks; */ public interface H5P_iterate_cb extends Callbacks { /** - * @ingroup JCALL + * @ingroup JCALLBK * * application callback for each property list * diff --git a/java/src/hdf/hdf5lib/callbacks/H5P_prp_close_func_cb.java b/java/src/hdf/hdf5lib/callbacks/H5P_prp_close_func_cb.java index 2ddc980..33bde76 100644 --- a/java/src/hdf/hdf5lib/callbacks/H5P_prp_close_func_cb.java +++ b/java/src/hdf/hdf5lib/callbacks/H5P_prp_close_func_cb.java @@ -18,7 +18,7 @@ package hdf.hdf5lib.callbacks; */ public interface H5P_prp_close_func_cb extends Callbacks { /** - * @ingroup JCALL + * @ingroup JCALLBK * * application callback for each property list * diff --git a/java/src/hdf/hdf5lib/callbacks/H5P_prp_compare_func_cb.java b/java/src/hdf/hdf5lib/callbacks/H5P_prp_compare_func_cb.java index 53caa94..3149d17 100644 --- a/java/src/hdf/hdf5lib/callbacks/H5P_prp_compare_func_cb.java +++ b/java/src/hdf/hdf5lib/callbacks/H5P_prp_compare_func_cb.java @@ -18,7 +18,7 @@ package hdf.hdf5lib.callbacks; */ public interface H5P_prp_compare_func_cb extends Callbacks { /** - * @ingroup JCALL + * @ingroup JCALLBK * * application callback for each property list * diff --git a/java/src/hdf/hdf5lib/callbacks/H5P_prp_copy_func_cb.java b/java/src/hdf/hdf5lib/callbacks/H5P_prp_copy_func_cb.java index 0b2349e..d3d6b37 100644 --- a/java/src/hdf/hdf5lib/callbacks/H5P_prp_copy_func_cb.java +++ b/java/src/hdf/hdf5lib/callbacks/H5P_prp_copy_func_cb.java @@ -18,7 +18,7 @@ package hdf.hdf5lib.callbacks; */ public interface H5P_prp_copy_func_cb extends Callbacks { /** - * @ingroup JCALL + * @ingroup JCALLBK * * application callback for each property list * diff --git a/java/src/hdf/hdf5lib/callbacks/H5P_prp_create_func_cb.java b/java/src/hdf/hdf5lib/callbacks/H5P_prp_create_func_cb.java index 6065ce0..2fe3338 100644 --- a/java/src/hdf/hdf5lib/callbacks/H5P_prp_create_func_cb.java +++ b/java/src/hdf/hdf5lib/callbacks/H5P_prp_create_func_cb.java @@ -18,7 +18,7 @@ package hdf.hdf5lib.callbacks; */ public interface H5P_prp_create_func_cb extends Callbacks { /** - * @ingroup JCALL + * @ingroup JCALLBK * * application callback for each property list * diff --git a/java/src/hdf/hdf5lib/callbacks/H5P_prp_delete_func_cb.java b/java/src/hdf/hdf5lib/callbacks/H5P_prp_delete_func_cb.java index 4384ca7..3019284 100644 --- a/java/src/hdf/hdf5lib/callbacks/H5P_prp_delete_func_cb.java +++ b/java/src/hdf/hdf5lib/callbacks/H5P_prp_delete_func_cb.java @@ -18,7 +18,7 @@ package hdf.hdf5lib.callbacks; */ public interface H5P_prp_delete_func_cb extends Callbacks { /** - * @ingroup JCALL + * @ingroup JCALLBK * * application callback for each property list * diff --git a/java/src/hdf/hdf5lib/callbacks/H5P_prp_get_func_cb.java b/java/src/hdf/hdf5lib/callbacks/H5P_prp_get_func_cb.java index 999c7b0..cfc8e31 100644 --- a/java/src/hdf/hdf5lib/callbacks/H5P_prp_get_func_cb.java +++ b/java/src/hdf/hdf5lib/callbacks/H5P_prp_get_func_cb.java @@ -18,7 +18,7 @@ package hdf.hdf5lib.callbacks; */ public interface H5P_prp_get_func_cb extends Callbacks { /** - * @ingroup JCALL + * @ingroup JCALLBK * * application callback for each property list * diff --git a/java/src/hdf/hdf5lib/callbacks/H5P_prp_set_func_cb.java b/java/src/hdf/hdf5lib/callbacks/H5P_prp_set_func_cb.java index 893344b..2272869 100644 --- a/java/src/hdf/hdf5lib/callbacks/H5P_prp_set_func_cb.java +++ b/java/src/hdf/hdf5lib/callbacks/H5P_prp_set_func_cb.java @@ -18,7 +18,7 @@ package hdf.hdf5lib.callbacks; */ public interface H5P_prp_set_func_cb extends Callbacks { /** - * @ingroup JCALL + * @ingroup JCALLBK * * application callback for each property list * diff --git a/release_docs/INSTALL_CMake.txt b/release_docs/INSTALL_CMake.txt index f9184cf..6adba9f 100644 --- a/release_docs/INSTALL_CMake.txt +++ b/release_docs/INSTALL_CMake.txt @@ -872,7 +872,7 @@ HDF5_ENABLE_ANALYZER_TOOLS "enable the use of Clang tools" HDF5_ENABLE_SANITIZERS "execute the Clang sanitizer" OFF HDF5_ENABLE_FORMATTERS "format source files" OFF HDF5_BUILD_DOC "Build documentation" OFF -HDF5_ENABLE_DOXY_WARNINGS "Enable fail if doxygen parsing has warnings." ON +HDF5_ENABLE_DOXY_WARNINGS "Enable fail if doxygen parsing has warnings." OFF ---------------- HDF5 VFD Options --------------------- HDF5_ENABLE_DIRECT_VFD "Build the Direct I/O Virtual File Driver" OFF diff --git a/release_docs/RELEASE.txt b/release_docs/RELEASE.txt index 19c309b..de02a66 100644 --- a/release_docs/RELEASE.txt +++ b/release_docs/RELEASE.txt @@ -931,6 +931,15 @@ Bug Fixes since HDF5-1.14.0 release Configuration ------------- + - Changed default of 'Error on HDF5 doxygen warnings' DOXYGEN_WARN_AS_ERROR option. + + The default setting of DOXYGEN_WARN_AS_ERROR to 'FAIL_ON_WARNINGS' has been changed + to 'NO'. It was decided that the setting was too aggressive and should be a user choice. + The github actions and scripts have been updated to reflect this. + + * HDF5_ENABLE_DOXY_WARNINGS: ON/OFF (Default: OFF) + * --enable-doxygen-errors: enable/disable (Default: disable) + - Removed an Autotools configure hack that causes problems on MacOS A sed line in configure.ac was added in the past to paper over some diff --git a/src/H5Dmodule.h b/src/H5Dmodule.h index 84d00e8..81f197d 100644 --- a/src/H5Dmodule.h +++ b/src/H5Dmodule.h @@ -179,10 +179,15 @@ *
Supported file drivers
* * \anchor dcpl_table_tag Dataset creation property list functions (H5P) + *
* \snippet{doc} tables/propertyLists.dox dcpl_table + *
* * \anchor dapl_table_tag Dataset access property list functions (H5P) + * + *
* \snippet{doc} tables/propertyLists.dox dapl_table + *
* * \subsection subsec_dataset_program Programming Model for Datasets * This section explains the programming model for datasets. @@ -863,7 +868,9 @@ * the pipeline processing: the pipeline and filter operations are identical no matter what data access * mechanism is used. * + *
* \snippet{doc} tables/propertyLists.dox lcpl_table + *
* * Each file driver writes/reads contiguous blocks of bytes from a logically contiguous address * space. The file driver is responsible for managing the details of the different physical storage @@ -880,7 +887,9 @@ * Data transfer properties set optional parameters that control parts of the data pipeline. The * function listing below shows transfer properties that control the behavior of the library. * + *
* \snippet{doc} tables/fileDriverLists.dox file_driver_table + *
* * Some filters and file drivers require or use additional parameters from the application program. * These can be passed in the data transfer property list. The table below shows file driver property diff --git a/src/H5Fmodule.h b/src/H5Fmodule.h index b7bb7a0..bf54976 100644 --- a/src/H5Fmodule.h +++ b/src/H5Fmodule.h @@ -408,14 +408,19 @@ * * * \anchor fcpl_table_tag File creation property list functions (H5P) + *
* \snippet{doc} tables/propertyLists.dox fcpl_table + *
* * \anchor fapl_table_tag File access property list functions (H5P) + *
* \snippet{doc} tables/propertyLists.dox fapl_table + *
* * \anchor fd_pl_table_tag File driver property list functions (H5P) + *
* \snippet{doc} tables/propertyLists.dox fd_pl_table - * + *
* * \subsection subsec_file_create Creating or Opening an HDF5 File * This section describes in more detail how to create and how to open files. @@ -672,7 +677,9 @@ * #H5FD_SEC2. Alternative layouts and drivers are designed to suit the needs of a variety of * systems, environments, and applications. The drivers are listed in the table below. * + *
* \snippet{doc} tables/fileDriverLists.dox supported_file_driver_table + *
* * For more information, see the HDF5 Reference Manual entries for the function calls shown in * the column on the right in the table above. diff --git a/src/H5Gmodule.h b/src/H5Gmodule.h index 4c435eb..c330fcd 100644 --- a/src/H5Gmodule.h +++ b/src/H5Gmodule.h @@ -477,7 +477,9 @@ * * * + *
* \snippet{doc} tables/propertyLists.dox gcpl_table + *
* * * diff --git a/src/H5Pmodule.h b/src/H5Pmodule.h index ea0b2de..ef300f9 100644 --- a/src/H5Pmodule.h +++ b/src/H5Pmodule.h @@ -891,48 +891,75 @@ * properties. Property lists are deleted by closing the associated handles. * * \ref PLCR + *
* \snippet{doc} tables/propertyLists.dox plcr_table + *
* * \ref PLCR + *
* \snippet{doc} tables/propertyLists.dox plcra_table + *
* * \ref PLCR / \ref OCPL / \ref GCPL + *
* \snippet{doc} tables/propertyLists.dox fcpl_table + *
* * \ref PLCR + *
* \snippet{doc} tables/propertyLists.dox fapl_table * \snippet{doc} tables/propertyLists.dox fd_pl_table + *
* * \ref PLCR + *
* \snippet{doc} tables/propertyLists.dox lapl_table + *
* * \ref PLCR / \ref OCPL + *
* \snippet{doc} tables/propertyLists.dox dcpl_table + *
* * \ref PLCR / \ref LAPL + *
* \snippet{doc} tables/propertyLists.dox dapl_table + *
* * \ref PLCR / \ref OCPL + *
* \snippet{doc} tables/propertyLists.dox gcpl_table + *
* * \ref PLCR / \ref LAPL + *
* \snippet{doc} tables/propertyLists.dox gapl_table + *
* * \ref PLCR + *
* \snippet{doc} tables/propertyLists.dox ocpl_table + *
* * \ref PLCR + *
* \snippet{doc} tables/propertyLists.dox ocpypl_table + *
* * \ref PLCR + *
* \snippet{doc} tables/propertyLists.dox strcpl_table + *
* * \ref PLCR / \ref STRCPL + *
* \snippet{doc} tables/propertyLists.dox lcpl_table + *
* * \ref PLCR / \ref STRCPL + *
* \snippet{doc} tables/propertyLists.dox acpl_table - * + *
* * \defgroup STRCPL String Creation Properties * \ingroup H5P @@ -941,30 +968,33 @@ * choice of a character encoding, applies to both attributes and links. * The second creation property applies to links only, and advises the library * to automatically create missing intermediate groups when creating new objects. - * + *
* \snippet{doc} tables/propertyLists.dox strcpl_table + *
* * \defgroup LCPL Link Creation Properties * \ingroup STRCPL * This creation property applies to links only, and advises the library * to automatically create missing intermediate groups when creating new objects. - * + *
* \snippet{doc} tables/propertyLists.dox lcpl_table - * + *
* @see STRCPL * * \defgroup ACPL Attribute Creation Properties * \ingroup STRCPL * The creation property, the choice of a character encoding, applies to attributes. - * + *
* \snippet{doc} tables/propertyLists.dox acpl_table + *
* * @see STRCPL * * \defgroup LAPL Link Access Properties * \ingroup H5P - * + *
* \snippet{doc} tables/propertyLists.dox lapl_table + *
* * \defgroup DAPL Dataset Access Properties * \ingroup LAPL @@ -974,8 +1004,9 @@ * dataset file paths, and controlling flush behavior, etc. These properties * are \Emph{not} persisted with datasets, and can be adjusted at runtime before * a dataset is created or opened. - * + *
* \snippet{doc} tables/propertyLists.dox dapl_table + *
* * \defgroup DCPL Dataset Creation Properties * \ingroup OCPL @@ -984,8 +1015,9 @@ * Unlike dataset access and transfer properties, creation properties \Emph{are} * stored with the dataset, and cannot be changed once a dataset has been * created. - * + *
* \snippet{doc} tables/propertyLists.dox dcpl_table + *
* * \defgroup DXPL Dataset Transfer Properties * \ingroup H5P @@ -993,8 +1025,9 @@ * and writing datasets such as transformations, MPI-IO I/O mode, error * detection, etc. These properties are \Emph{not} persisted with datasets, * and can be adjusted at runtime before a dataset is read or written. - * + *
* \snippet{doc} tables/propertyLists.dox dxpl_table + *
* * \defgroup FAPL File Access Properties * \ingroup H5P @@ -1003,9 +1036,10 @@ * file driver (VFD), configuring the metadata cache (MDC), control * file locking, etc. These properties are \Emph{not} persisted with files, and * can be adjusted at runtime before a file is created or opened. - * + *
* \snippet{doc} tables/propertyLists.dox fapl_table * \snippet{doc} tables/propertyLists.dox fd_pl_table + *
* * \defgroup FCPL File Creation Properties * \ingroup GCPL @@ -1014,14 +1048,16 @@ * Unlike file access properties, creation properties \Emph{are} * stored with the file, and cannot be changed once a file has been * created. - * + *
* \snippet{doc} tables/propertyLists.dox fcpl_table + *
* * \defgroup GAPL Group Access Properties * \ingroup LAPL * The functions in this section can be applied to group property lists. - * + *
* \snippet{doc} tables/propertyLists.dox gapl_table + *
* * \defgroup GCPL Group Creation Properties * \ingroup OCPL @@ -1030,32 +1066,37 @@ * Unlike file access properties, creation properties \Emph{are} * stored with the group, and cannot be changed once a group has been * created. - * + *
* \snippet{doc} tables/propertyLists.dox gcpl_table + *
* * \defgroup PLCR Property List Class Root * \ingroup H5P * Use the functions in this module to manage HDF5 property lists. - * + *
* \snippet{doc} tables/propertyLists.dox plcr_table + *
* * \defgroup PLCRA Property List Class Root (Advanced) * \ingroup H5P * You can create and customize user-defined property list classes using the * functions described below. Arbitrary user-defined properties can also * be inserted into existing property lists as so-called temporary properties. - * + *
* \snippet{doc} tables/propertyLists.dox plcra_table + *
* * \defgroup OCPL Object Creation Properties * \ingroup H5P - * + *
* \snippet{doc} tables/propertyLists.dox ocpl_table + *
* * \defgroup OCPYPL Object Copy Properties * \ingroup H5P - * + *
* \snippet{doc} tables/propertyLists.dox ocpypl_table + *
* * \defgroup FMPL File Mount Properties * \ingroup H5P diff --git a/src/H5Ppublic.h b/src/H5Ppublic.h index 98b7c2f..721f3d7 100644 --- a/src/H5Ppublic.h +++ b/src/H5Ppublic.h @@ -3360,8 +3360,9 @@ H5_DLL herr_t H5Pget_core_write_tracking(hid_t fapl_id, hbool_t *is_enabled, siz * * Valid driver identifiers distributed with HDF5 are listed and * described in the following table. - * + *
* \snippet{doc} tables/fileDriverLists.dox supported_file_driver_table + *
* * This list does not include custom drivers that might be * defined and registered by a user. diff --git a/src/H5Tmodule.h b/src/H5Tmodule.h index b4f9289..f1b7b17 100644 --- a/src/H5Tmodule.h +++ b/src/H5Tmodule.h @@ -3892,30 +3892,42 @@ filled according to the value of this property. The padding can be: * \details CPU-specific datatypes * \defgroup PDTALPHA DEC Alpha * \ingroup PDTCPU + *
* \snippet{doc} tables/predefinedDatatypes.dox predefined_dec_datatypes_table + *
* \defgroup PDTX86 AMD & INTEL * \ingroup PDTCPU + *
* \snippet{doc} tables/predefinedDatatypes.dox predefined_intel_datatypes_table + *
* \defgroup PDTMIPS SGI MIPS * \ingroup PDTCPU + *
* \snippet{doc} tables/predefinedDatatypes.dox predefined_mips_datatypes_table + *
* * \defgroup PDTIEEE IEEE * \ingroup PDT * \details The IEEE floating point types in big- and little-endian byte orders. + *
* \snippet{doc} tables/predefinedDatatypes.dox predefined_ieee_datatypes_table + *
* * \defgroup PDTSTD Standard Datatypes * \ingroup PDT * \details These are "standard" types. For instance, signed (2's complement) * and unsigned integers of various sizes in big- and little-endian * byte orders. + *
* \snippet{doc} tables/predefinedDatatypes.dox predefined_std_datatypes_table + *
* * \defgroup PDTUNIX UNIX-specific Datatypes * \ingroup PDT * \details Types which are particular to Unix. + *
* \snippet{doc} tables/predefinedDatatypes.dox predefined_unix_datatypes_table + *
* * \defgroup PDTNAT Native Datatypes * \ingroup PDT @@ -3928,16 +3940,22 @@ filled according to the value of this property. The padding can be: * \li The datatype \c LLONG corresponds C's \Code{long long} and * \c LDOUBLE is \Code{long double}. These types might be the same * as \c LONG and \c DOUBLE, respectively. + *
* \snippet{doc} tables/predefinedDatatypes.dox predefined_native_datatypes_table + *
* * \defgroup PDTC9x C9x Integer Datatypes * \ingroup PDTNAT * \details C9x integer types + *
* \snippet{doc} tables/predefinedDatatypes.dox predefined_c9x_datatypes_table + *
* * \defgroup PDTS Strings * \ingroup PDT + *
* \snippet{doc} tables/predefinedDatatypes.dox predefined_string_datatypes_table + *
* */ diff --git a/src/H5VLmodule.h b/src/H5VLmodule.h index 546b31e..19baf34 100644 --- a/src/H5VLmodule.h +++ b/src/H5VLmodule.h @@ -606,15 +606,21 @@ * fact, implement some of this functionality as it is possible to mimic the native * HDF5 connector, however this will probably not be true for most non-native * VOL connectors. + *
* \snippet{doc} tables/volAPIs.dox vol_native_table + *
* * \subsubsection subsubsec_vol_compat_indep List of HDF5 VOL-Independent API Calls * These HDF5 API calls do not depend on a particular VOL connector being loaded. + *
* \snippet{doc} tables/volAPIs.dox vol_independent_table + *
* * \subsubsection subsubsec_vol_compat_opt List of Native VOL Optional Operation Values By Subclass * These values can be passed to the opt type parameter of H5VLquery optional(). + *
* \snippet{doc} tables/volAPIs.dox vol_optional_table + *
* * * -- cgit v0.12
Other external link functions