Fix various warnings and issues in doxygen doc generation (#994)

* Fix various warnings and issues in doxygen doc generation

* Add new file to list

3 files changed, 11 insertions, 43 deletions

diff --git a/src/CMakeLists.txt b/src/CMakeLists.txt
index d1d848d..cde36c9 100644
--- a/src/CMakeLists.txt
+++ b/src/CMakeLists.txt
@@ -1399,38 +1399,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
@@ -1440,11 +1408,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 8fe8020..c496414 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 5e9c4ab..a5c5c37 100644
--- a/src/H5Ppublic.h
+++ b/src/H5Ppublic.h
@@ -7486,10 +7486,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
  *
  */
@@ -8092,7 +8088,7 @@ H5_DLL herr_t H5Pget_mpio_no_collective_cause(hid_t plist_id, uint32_t *local_no
  *          the size of the \p start, \p stride, \p count, and \p block arrays.
  *          \p rank must be between 1 and #H5S_MAX_RANK, inclusive.
  *
- *          The \op, \p start, \p stride, \p count, and \p block parameters
+ *          The \p op, \p start, \p stride, \p count, and \p block parameters
  *          behave identically to their behavior for H5Sselect_hyperslab(),
  *          please see the documentation for that routine for details about
  *          their use.