summaryrefslogtreecommitdiffstats
path: root/doxygen
diff options
context:
space:
mode:
authorAllen Byrne <50328838+byrnHDF@users.noreply.github.com>2021-09-10 12:40:27 (GMT)
committerGitHub <noreply@github.com>2021-09-10 12:40:27 (GMT)
commitb58f8540ac3c416e1d833aad243a0df35ec4a616 (patch)
treefb160575a2cc88c8341f9115c3f66a9286e00d7c /doxygen
parent8e06298ecfde5eb647b39cfe0dab70005f092199 (diff)
downloadhdf5-b58f8540ac3c416e1d833aad243a0df35ec4a616.zip
hdf5-b58f8540ac3c416e1d833aad243a0df35ec4a616.tar.gz
hdf5-b58f8540ac3c416e1d833aad243a0df35ec4a616.tar.bz2
Fix various warnings and issues in doxygen doc generation (#994)
* Fix various warnings and issues in doxygen doc generation * Add new file to list
Diffstat (limited to 'doxygen')
-rw-r--r--doxygen/CMakeLists.txt46
-rw-r--r--doxygen/Doxyfile.in9
-rw-r--r--doxygen/aliases4
-rw-r--r--doxygen/dox/MetadataCachingInHDF5.dox4
4 files changed, 51 insertions, 12 deletions
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 ab6d8ea..06c3445 100644
--- a/doxygen/aliases
+++ b/doxygen/aliases
@@ -298,7 +298,7 @@ ALIASES += ref_rfc20120305="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/RFC%20P
ALIASES += ref_rfc20120220="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/h5repack_improve_hyperslab_over_chunked_dataset_v1.pdf\"><tt>h5repack</tt>: Improved Hyperslab selections for Large Chunked Datasets</a>"
ALIASES += ref_rfc20120120="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/2012-1-25-Maintainers-guide-for-datatype.docx.pdf\">A Maintainer’s Guide for the Datatype Module in HDF5 Library</a>"
ALIASES += ref_rfc20120104="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/RFC_actual_io_v4-1_done.docx.pdf\">Actual I/O Mode</a>"
-ALIASES += ref_rfc20111119="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/RFC-H5Ocompare-review_v6.pdf\">New public functions to handle comparison</a>"
+ALIASES += ref_rfc20111119="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/RFC-H5Ocompare-review_v6.pdf\">New public functions to handle comparison</a>"
ALIASES += ref_rfc20110825="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/2011-08-31-RFC_H5Ocopy_Named_DT_v2.docx.pdf\">Merging Named Datatypes in H5Ocopy()</a>"
ALIASES += ref_rfc20110811="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/RFC_Enhancement_Hyperslab_Selection-1.4.docx.pdf\">Expanding the HDF5 Hyperslab Selection Interface</a>"
ALIASES += ref_rfc20110726="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/metadata_aggregation_RFC_v03.docx.pdf\">HDF5 File Space Allocation and Aggregation</a>"
@@ -327,7 +327,7 @@ ALIASES += ref_rfc20071111="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/AURA-co
ALIASES += ref_rfc20071018="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/RFC_NaNsHDF5.pdf\"><tt>NaN</tt> detection in HDF5</a>"
ALIASES += ref_rfc20070801="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/Metadata_Journaling_RFC.pdf\">Metadata Journaling to Improve Crash Survivability</a>"
ALIASES += ref_rfc20070413="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/API_Compatibility_RFC.txt.pdf\">API Compatibility Strategies for HDF5</a>"
-ALIASES += ref_rfc20070115="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/PrivateHeap.pdf\">A "Private" Heap for HDF5</a>"
+ALIASES += ref_rfc20070115="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/PrivateHeap.pdf\">A 'Private' Heap for HDF5</a>"
ALIASES += ref_rfc20060623="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/coll_ind_dd6.pdf\">Performance Comparison of Collective I/O and Independent I/O with Derived Datatypes</a>"
ALIASES += ref_rfc20060604="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/h5stat_spec_v3_2006-06-04.pdf\"><tt>h5stat</tt> tool</a>"
ALIASES += ref_rfc20060505="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/Simple%20Performance%20Test%20on%20Fletcher32%20Filter.pdf\">Simple Performance Test on Fletcher32 Filter</a>"
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