From b30a44973e97c56bf7772cdbf767b98f84122397 Mon Sep 17 00:00:00 2001 From: Allen Byrne <50328838+byrnHDF@users.noreply.github.com> Date: Fri, 10 Sep 2021 07:41:53 -0500 Subject: Merge Fix various warnings and issues in doxygen doc generation #994 (#996) --- CMakeLists.txt | 29 +++++++++++----------- MANIFEST | 1 + configure.ac | 4 ++- doxygen/CMakeLists.txt | 46 +++++++++++++++++++++++++++++++++++ doxygen/Doxyfile.in | 9 +------ doxygen/aliases | 4 +-- doxygen/dox/MetadataCachingInHDF5.dox | 4 +-- hl/src/CMakeLists.txt | 29 ++++++++++++++++++++++ src/CMakeLists.txt | 46 +++++++---------------------------- src/H5Dpublic.h | 2 +- src/H5Ppublic.h | 4 --- 11 files changed, 109 insertions(+), 69 deletions(-) create mode 100644 doxygen/CMakeLists.txt diff --git a/CMakeLists.txt b/CMakeLists.txt index b75fdd2..a0977b2 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -572,20 +572,6 @@ endif () # endif () #----------------------------------------------------------------------------- -# Option to build documentation -#----------------------------------------------------------------------------- -option (HDF5_BUILD_DOC "Build documentation" OFF) -if (HDF5_BUILD_DOC AND EXISTS "${HDF5_DOXYGEN_DIR}" AND IS_DIRECTORY "${HDF5_DOXYGEN_DIR}") -# check if Doxygen is installed - find_package(Doxygen) - if (DOXYGEN_FOUND) - message(STATUS "Doxygen version: ${DOXYGEN_VERSION}") - else () - message(STATUS "Doxygen needs to be installed to generate the doxygen documentation") - endif () -endif () - -#----------------------------------------------------------------------------- # Option to indicate using a memory checker #----------------------------------------------------------------------------- option (HDF5_ENABLE_USING_MEMCHECKER "Indicate that a memory checker is used" OFF) @@ -915,6 +901,21 @@ if (HDF5_ALLOW_EXTERNAL_SUPPORT MATCHES "GIT" OR HDF5_ALLOW_EXTERNAL_SUPPORT MAT endif () #----------------------------------------------------------------------------- +# Option to build documentation +#----------------------------------------------------------------------------- +option (HDF5_BUILD_DOC "Build documentation" OFF) +if (HDF5_BUILD_DOC AND EXISTS "${HDF5_DOXYGEN_DIR}" AND IS_DIRECTORY "${HDF5_DOXYGEN_DIR}") +# check if Doxygen is installed + find_package(Doxygen) + if (DOXYGEN_FOUND) + message(STATUS "Doxygen version: ${DOXYGEN_VERSION}") + add_subdirectory (doxygen) + else () + message(STATUS "Doxygen needs to be installed to generate the doxygen documentation") + endif () +endif () + +#----------------------------------------------------------------------------- # Dashboard and Testing Settings #----------------------------------------------------------------------------- option (BUILD_TESTING "Build HDF5 Unit Testing" ON) diff --git a/MANIFEST b/MANIFEST index d7c8bf3..dc813ca 100644 --- a/MANIFEST +++ b/MANIFEST @@ -213,6 +213,7 @@ ./doc/code-conventions.md ./doc/contributing.md ./doxygen/aliases +./doxygen/CMakeLists.txt ./doxygen/Doxyfile.in ./doxygen/dox/APIVersions.dox ./doxygen/dox/About.dox diff --git a/configure.ac b/configure.ac index c33b6fb..df0cec5 100644 --- a/configure.ac +++ b/configure.ac @@ -1126,6 +1126,7 @@ if test "X$HDF5_DOXYGEN" = "Xyes"; then AC_SUBST([DOXYGEN_SERVER_BASED_SEARCH]) AC_SUBST([DOXYGEN_EXTERNAL_SEARCH]) AC_SUBST([DOXYGEN_SEARCHENGINE_URL]) + AC_SUBST([DOXYGEN_STRIP_FROM_PATH]) AC_SUBST([DOXYGEN_PREDEFINED]) # SRCDIR Environment variables used inside doxygen macro for the source location: @@ -1133,7 +1134,7 @@ if test "X$HDF5_DOXYGEN" = "Xyes"; then DOXYGEN_VERSION_STRING=${PACKAGE_VERSION} DOXYGEN_INCLUDE_ALIASES='$(SRCDIR)/doxygen/aliases' DOXYGEN_PROJECT_LOGO='$(SRCDIR)/doxygen/img/HDFG-logo.png' - DOXYGEN_PROJECT_BRIEF= + DOXYGEN_PROJECT_BRIEF='C-API Reference' DOXYGEN_INPUT_DIRECTORY='$(SRCDIR) $(SRCDIR)/doxygen/dox' DOXYGEN_OPTIMIZE_OUTPUT_FOR_C=YES DOXYGEN_MACRO_EXPANSION=YES @@ -1148,6 +1149,7 @@ if test "X$HDF5_DOXYGEN" = "Xyes"; then DOXYGEN_SERVER_BASED_SEARCH=NO DOXYGEN_EXTERNAL_SEARCH=NO DOXYGEN_SEARCHENGINE_URL= + DOXYGEN_STRIP_FROM_PATH='$(SRCDIR)' DOXYGEN_PREDEFINED='H5_HAVE_DIRECT H5_HAVE_LIBHDFS H5_HAVE_MAP_API H5_HAVE_PARALLEL H5_HAVE_ROS3_VFD' DX_INIT_DOXYGEN([HDF5], [./doxygen/Doxyfile], [hdf5lib_docs]) diff --git a/doxygen/CMakeLists.txt b/doxygen/CMakeLists.txt new file mode 100644 index 0000000..36ce590 --- /dev/null +++ b/doxygen/CMakeLists.txt @@ -0,0 +1,46 @@ +cmake_minimum_required (VERSION 3.12) +project (HDF5_DOXYGEN C) + +#----------------------------------------------------------------------------- +# Option to build documentation +#----------------------------------------------------------------------------- +if (DOXYGEN_FOUND) + set (DOXYGEN_PACKAGE ${HDF5_PACKAGE_NAME}) + set (DOXYGEN_VERSION_STRING ${HDF5_PACKAGE_VERSION_STRING}) + set (DOXYGEN_INCLUDE_ALIASES_PATH ${HDF5_DOXYGEN_DIR}) + set (DOXYGEN_INCLUDE_ALIASES aliases) + set (DOXYGEN_VERBATIM_VARS DOXYGEN_INCLUDE_ALIASES) + set (DOXYGEN_PROJECT_LOGO ${HDF5_DOXYGEN_DIR}/img/HDFG-logo.png) + set (DOXYGEN_PROJECT_BRIEF "C-API Reference") + set (DOXYGEN_INPUT_DIRECTORY "${HDF5_SOURCE_DIR} ${HDF5_DOXYGEN_DIR}/dox ${HDF5_GENERATED_SOURCE_DIR}") + set (DOXYGEN_OPTIMIZE_OUTPUT_FOR_C YES) + set (DOXYGEN_MACRO_EXPANSION YES) + set (DOXYGEN_OUTPUT_DIRECTORY ${HDF5_BINARY_DIR}/hdf5lib_docs) + set (DOXYGEN_EXAMPLES_DIRECTORY "${HDF5_DOXYGEN_DIR}/dox/cookbook ${HDF5_DOXYGEN_DIR}/examples ${HDF5_SRC_DIR} ${HDF5_SOURCE_DIR}/examples ${HDF5_TEST_SRC_DIR}") + set (DOXYGEN_LAYOUT_FILE ${HDF5_DOXYGEN_DIR}/hdf5doxy_layout.xml) + set (DOXYGEN_HTML_HEADER ${HDF5_DOXYGEN_DIR}/hdf5_header.html) + set (DOXYGEN_HTML_FOOTER ${HDF5_DOXYGEN_DIR}/hdf5_footer.html) + set (DOXYGEN_HTML_EXTRA_STYLESHEET ${HDF5_DOXYGEN_DIR}/hdf5doxy.css) + set (DOXYGEN_HTML_EXTRA_FILES "${HDF5_DOXYGEN_DIR}/hdf5_navtree_hacks.js ${HDF5_DOXYGEN_DIR}/img/ftv2node.png ${HDF5_DOXYGEN_DIR}/img/ftv2pnode.png") + set (DOXYGEN_TAG_FILE ${HDF5_BINARY_DIR}/hdf5.tag) + set (DOXYGEN_SERVER_BASED_SEARCH NO) + set (DOXYGEN_EXTERNAL_SEARCH NO) + set (DOXYGEN_SEARCHENGINE_URL) + set (DOXYGEN_STRIP_FROM_PATH ${HDF5_SOURCE_DIR}) + set (DOXYGEN_PREDEFINED "H5_HAVE_DIRECT H5_HAVE_LIBHDFS H5_HAVE_MAP_API H5_HAVE_PARALLEL H5_HAVE_ROS3_VFD") + +# This configure and individual custom targets work together + # Replace variables inside @@ with the current values + configure_file (${HDF5_DOXYGEN_DIR}/Doxyfile.in ${HDF5_BINARY_DIR}/Doxyfile @ONLY) + + install ( + DIRECTORY ${HDF5_BINARY_DIR}/hdf5lib_docs/html + DESTINATION ${HDF5_INSTALL_DATA_DIR} + COMPONENT Documents + ) + + if (NOT TARGET doxygen) + add_custom_target (doxygen) + endif () + +endif () diff --git a/doxygen/Doxyfile.in b/doxygen/Doxyfile.in index 4af590b..44d9974 100644 --- a/doxygen/Doxyfile.in +++ b/doxygen/Doxyfile.in @@ -170,7 +170,7 @@ FULL_PATH_NAMES = YES # will be relative from the directory where doxygen is started. # This tag requires that the tag FULL_PATH_NAMES is set to YES. -STRIP_FROM_PATH = +STRIP_FROM_PATH = @DOXYGEN_STRIP_FROM_PATH@ # The STRIP_FROM_INC_PATH tag can be used to strip a user-defined part of the # path mentioned in the documentation of a class, which tells the reader which @@ -1126,13 +1126,6 @@ CLANG_DATABASE_PATH = ALPHABETICAL_INDEX = YES -# The COLS_IN_ALPHA_INDEX tag can be used to specify the number of columns in -# which the alphabetical index list will be split. -# Minimum value: 1, maximum value: 20, default value: 5. -# This tag requires that the tag ALPHABETICAL_INDEX is set to YES. - -COLS_IN_ALPHA_INDEX = 5 - # In case all classes in a project start with a common prefix, all classes will # be put under the same header in the alphabetical index. The IGNORE_PREFIX tag # can be used to specify a prefix (or a list of prefixes) that should be ignored diff --git a/doxygen/aliases b/doxygen/aliases index 8352294..df1f49b 100644 --- a/doxygen/aliases +++ b/doxygen/aliases @@ -300,7 +300,7 @@ ALIASES += ref_rfc20120305="h5repack: Improved Hyperslab selections for Large Chunked Datasets" ALIASES += ref_rfc20120120="A Maintainer’s Guide for the Datatype Module in HDF5 Library" ALIASES += ref_rfc20120104="Actual I/O Mode" -ALIASES += ref_rfc20111119="New public functions to handle comparison" +ALIASES += ref_rfc20111119="New public functions to handle comparison" ALIASES += ref_rfc20110825="Merging Named Datatypes in H5Ocopy()" ALIASES += ref_rfc20110811="Expanding the HDF5 Hyperslab Selection Interface" ALIASES += ref_rfc20110726="HDF5 File Space Allocation and Aggregation" @@ -329,7 +329,7 @@ ALIASES += ref_rfc20071111="NaN detection in HDF5" ALIASES += ref_rfc20070801="Metadata Journaling to Improve Crash Survivability" ALIASES += ref_rfc20070413="API Compatibility Strategies for HDF5" -ALIASES += ref_rfc20070115="A "Private" Heap for HDF5" +ALIASES += ref_rfc20070115="A 'Private' Heap for HDF5" ALIASES += ref_rfc20060623="Performance Comparison of Collective I/O and Independent I/O with Derived Datatypes" ALIASES += ref_rfc20060604="h5stat tool" ALIASES += ref_rfc20060505="Simple Performance Test on Fletcher32 Filter" diff --git a/doxygen/dox/MetadataCachingInHDF5.dox b/doxygen/dox/MetadataCachingInHDF5.dox index 9ba0fab..b84ddea 100644 --- a/doxygen/dox/MetadataCachingInHDF5.dox +++ b/doxygen/dox/MetadataCachingInHDF5.dox @@ -668,7 +668,7 @@ reduction. With the hit rate threshold cache size decrement algorithm, the remaining fields in the section are ignored. -\subsubsection acsr Ageout Cache Size Reduction +\subsubsection dacsr Ageout Cache Size Reduction If \ref H5AC_cache_config_t.decr_mode "decr_mode" is #H5C_decr__age_out the cache size is decreased by the ageout algorithm, and the remaining fields of the @@ -692,7 +692,7 @@ The \ref H5AC_cache_config_t.decrement "decrement" and \ref H5AC_cache_config_t.upper_hr_threshold "upper_hr_threshold" fields are ignored in this case. -\subsubsection awhrtcsr Ageout With Hit Rate Threshold Cache Size Reduction +\subsubsection dawhrtcsr Ageout With Hit Rate Threshold Cache Size Reduction If \ref H5AC_cache_config_t.decr_mode "decr_mode" is #H5C_decr__age_out_with_threshold, the cache size is decreased by the ageout diff --git a/hl/src/CMakeLists.txt b/hl/src/CMakeLists.txt index 7678de8..a97d6fa 100644 --- a/hl/src/CMakeLists.txt +++ b/hl/src/CMakeLists.txt @@ -169,3 +169,32 @@ if (NOT WIN32 AND NOT MINGW) COMPONENT hllibraries ) endif () + +#----------------------------------------------------------------------------- +# Option to build documentation +#----------------------------------------------------------------------------- +if (DOXYGEN_FOUND) +# This cmake function requires that the non-default doxyfile settings are provided with set (DOXYGEN_xxx) commands +# In addition the doxyfile aliases @INCLUDE option is not supported and would need to be provided in a set (DOXYGEN_ALIASES) command. +# doxygen_add_docs (hdf5lib_doc +## ${HL_SOURCES} ${HL_HEADERS} ${HDF5_DOXYGEN_DIR}/dox +# ${DOXYGEN_INPUT_DIRECTORY} +# ALL +# WORKING_DIRECTORY ${HDF5_HL_SRC_DIR} +# COMMENT "Generating HDF5 HL library Source Documentation" +# ) + +# This custom target and doxygen/configure work together + # Replace variables inside @@ with the current values + add_custom_target (hdf5hllib_doc ALL + COMMAND ${DOXYGEN_EXECUTABLE} ${HDF5_BINARY_DIR}/Doxyfile + WORKING_DIRECTORY ${HDF5_HL_SRC_DIR} + COMMENT "Generating HDF5 HL library Source API documentation with Doxygen" + VERBATIM ) + + if (NOT TARGET doxygen) + add_custom_target (doxygen) + endif () + + add_dependencies (doxygen hdf5hllib_doc) +endif () diff --git a/src/CMakeLists.txt b/src/CMakeLists.txt index 3fb3072..a81c4bb 100644 --- a/src/CMakeLists.txt +++ b/src/CMakeLists.txt @@ -1378,38 +1378,6 @@ endif () # Option to build documentation #----------------------------------------------------------------------------- if (DOXYGEN_FOUND) - set (DOXYGEN_PACKAGE ${HDF5_PACKAGE_NAME}) - set (DOXYGEN_VERSION_STRING ${HDF5_PACKAGE_VERSION_STRING}) - set (DOXYGEN_INCLUDE_ALIASES_PATH ${HDF5_DOXYGEN_DIR}) - set (DOXYGEN_INCLUDE_ALIASES aliases) - set (DOXYGEN_VERBATIM_VARS DOXYGEN_INCLUDE_ALIASES) - set (DOXYGEN_PROJECT_LOGO ${HDF5_DOXYGEN_DIR}/img/HDFG-logo.png) - set (DOXYGEN_PROJECT_BRIEF "C-API Reference") - set (DOXYGEN_INPUT_DIRECTORY "${HDF5_SRC_DIR} ${HDF5_DOXYGEN_DIR}/dox ${HDF5_GENERATED_SOURCE_DIR}") - set (DOXYGEN_OPTIMIZE_OUTPUT_FOR_C YES) - set (DOXYGEN_MACRO_EXPANSION YES) - set (DOXYGEN_OUTPUT_DIRECTORY ${HDF5_BINARY_DIR}/hdf5lib_docs) - set (DOXYGEN_EXAMPLES_DIRECTORY "${HDF5_DOXYGEN_DIR}/dox/cookbook ${HDF5_DOXYGEN_DIR}/examples ${HDF5_SRC_DIR} ${HDF5_SOURCE_DIR}/examples ${HDF5_TEST_SRC_DIR}") - set (DOXYGEN_LAYOUT_FILE ${HDF5_DOXYGEN_DIR}/hdf5doxy_layout.xml) - set (DOXYGEN_HTML_HEADER ${HDF5_DOXYGEN_DIR}/hdf5_header.html) - set (DOXYGEN_HTML_FOOTER ${HDF5_DOXYGEN_DIR}/hdf5_footer.html) - set (DOXYGEN_HTML_EXTRA_STYLESHEET ${HDF5_DOXYGEN_DIR}/hdf5doxy.css) - set (DOXYGEN_HTML_EXTRA_FILES "${HDF5_DOXYGEN_DIR}/hdf5_navtree_hacks.js ${HDF5_DOXYGEN_DIR}/img/ftv2node.png ${HDF5_DOXYGEN_DIR}/img/ftv2pnode.png") - set (DOXYGEN_TAG_FILE ${HDF5_BINARY_DIR}/hdf5.tag) - set (DOXYGEN_SERVER_BASED_SEARCH NO) - set (DOXYGEN_EXTERNAL_SEARCH NO) - set (DOXYGEN_SEARCHENGINE_URL) - set (DOXYGEN_PREDEFINED H5_HAVE_DIRECT H5_HAVE_LIBHDFS H5_HAVE_MAP_API H5_HAVE_PARALLEL H5_HAVE_ROS3_VFD) - -# This configure and custom target work together - # Replace variables inside @@ with the current values - configure_file (${HDF5_DOXYGEN_DIR}/Doxyfile.in ${HDF5_BINARY_DIR}/Doxyfile @ONLY) - add_custom_target (hdf5lib_doc ALL - COMMAND ${DOXYGEN_EXECUTABLE} ${HDF5_BINARY_DIR}/Doxyfile - DEPENDS ${HDF5_GENERATED_SOURCE_DIR}/H5Tinit.c ${HDF5_SRC_BINARY_DIR}/H5lib_settings.c - WORKING_DIRECTORY ${HDF5_SRC_DIR} - COMMENT "Generating HDF5 library Source API documentation with Doxygen" - VERBATIM ) # This cmake function requires that the non-default doxyfile settings are provided with set (DOXYGEN_xxx) commands # In addition the doxyfile aliases @INCLUDE option is not supported and would need to be provided in a set (DOXYGEN_ALIASES) command. # doxygen_add_docs (hdf5lib_doc @@ -1419,11 +1387,15 @@ if (DOXYGEN_FOUND) # WORKING_DIRECTORY ${HDF5_SRC_DIR} # COMMENT "Generating HDF5 library Source Documentation" # ) - install ( - DIRECTORY ${HDF5_BINARY_DIR}/hdf5lib_docs/html - DESTINATION ${HDF5_INSTALL_DATA_DIR} - COMPONENT Documents - ) + +# This custom target and doxygen/configure work together + # Replace variables inside @@ with the current values + add_custom_target (hdf5lib_doc ALL + COMMAND ${DOXYGEN_EXECUTABLE} ${HDF5_BINARY_DIR}/Doxyfile + DEPENDS ${HDF5_GENERATED_SOURCE_DIR}/H5Tinit.c ${HDF5_SRC_BINARY_DIR}/H5lib_settings.c + WORKING_DIRECTORY ${HDF5_SRC_DIR} + COMMENT "Generating HDF5 library Source API documentation with Doxygen" + VERBATIM ) if (NOT TARGET doxygen) add_custom_target (doxygen) diff --git a/src/H5Dpublic.h b/src/H5Dpublic.h index 26e54d4..f95d0dc 100644 --- a/src/H5Dpublic.h +++ b/src/H5Dpublic.h @@ -152,7 +152,7 @@ typedef herr_t (*H5D_append_cb_t)(hid_t dataset_id, hsize_t *cur_dims, void *op_ * * \param[in,out] elem Pointer to the memory buffer containing the current dataset * element - * \param[in] type_id Datatype identifier of the elements stored in \pelem + * \param[in] type_id Datatype identifier of the elements stored in \p elem * \param[in] ndim Number of dimensions for the \p point array * \param[in] point Array containing the location of the element within * the original dataspace diff --git a/src/H5Ppublic.h b/src/H5Ppublic.h index ee1ba04..65b346d 100644 --- a/src/H5Ppublic.h +++ b/src/H5Ppublic.h @@ -7458,10 +7458,6 @@ H5_DLL size_t H5Pget_buffer(hid_t plist_id, void **tconv /*out*/, void **bkg /*o * If an error occurs, the buffer pointed to by \p expression is * unchanged, and the function returns a negative value. * - * \par Example - * An example snippet from examples/h5_dtransform.c: - * \snippet h5_dtransform.c H5Pget_data_transform_snip - * * \since 1.8.0 * */ -- cgit v0.12