develop Merge doxygen from 1.12 branch (#2095)

7 files changed, 110 insertions, 82 deletions

diff --git a/hl/src/H5DOpublic.h b/hl/src/H5DOpublic.h
index 13b2422..20f4c98 100644
--- a/hl/src/H5DOpublic.h
+++ b/hl/src/H5DOpublic.h
@@ -18,7 +18,11 @@
 extern "C" {
 #endif
 
-/**\defgroup H5DO Optimizations
+/** \page H5DO_UG The HDF5 High Level Optimizations
+ * @todo Under Construction
+ */
+
+/**\defgroup H5DO HDF5 Optimizations APIs (H5DO)
  *
  * <em>Bypassing default HDF5 behavior in order to optimize for specific
  * use cases (H5DO)</em>
diff --git a/hl/src/H5DSpublic.h b/hl/src/H5DSpublic.h
index 77dd64b..4fcf681 100644
--- a/hl/src/H5DSpublic.h
+++ b/hl/src/H5DSpublic.h
@@ -31,7 +31,11 @@ typedef herr_t (*H5DS_iterate_t)(hid_t dset, unsigned dim, hid_t scale, void *vi
 extern "C" {
 #endif
 
-/**\defgroup H5DS Dimension Scales
+/** \page H5DS_UG The HDF5 High Level Dimension Scales
+ * @todo Under Construction
+ */
+
+/**\defgroup H5DS HDF5 Dimension Scales APIs (H5DS)
  *
  * <em>Creating and manipulating HDF5 datasets that are associated with
  * the dimension of another HDF5 dataset (H5DS)</em>
@@ -77,21 +81,21 @@ extern "C" {
 
 /* THIS IS A NEW ROUTINE NOT ON OLD PORTAL */
 /**
- * --------------------------------------------------------------------------
- * \ingroup H5DS
+ *  --------------------------------------------------------------------------
+ *  \ingroup H5DS
  *
- * \brief Determines if new references are used with dimension scales.
+ *  \brief Determines if new references are used with dimension scales.
  *
- * \param[in] obj_id        Object identifier
- * \param[out] with_new_ref New references are used or not
+ *  \param[in] obj_id        Object identifier
+ *  \param[out] with_new_ref New references are used or not
  *
- * \return \herr_t
+ *  \return \herr_t
  *
- * \details H5DSwith_new_ref() takes any object identifier and checks
- *          if new references are used for dimension scales. Currently,
- *          new references are used when non-native VOL connector is
- *          used or when H5_DIMENSION_SCALES_WITH_NEW_REF is set up
- *          via configure option.
+ *  \details H5DSwith_new_ref() takes any object identifier and checks
+ *           if new references are used for dimension scales. Currently,
+ *           new references are used when non-native VOL connector is
+ *           used or when H5_DIMENSION_SCALES_WITH_NEW_REF is set up
+ *           via configure option.
  *
  */
 H5_HLDLL herr_t H5DSwith_new_ref(hid_t obj_id, hbool_t *with_new_ref);
diff --git a/hl/src/H5IMpublic.h b/hl/src/H5IMpublic.h
index b5426d6..bccf3c4 100644
--- a/hl/src/H5IMpublic.h
+++ b/hl/src/H5IMpublic.h
@@ -18,7 +18,11 @@
 extern "C" {
 #endif
 
-/**\defgroup H5IM Images
+/** \page H5IM_UG The HDF5 High Level Images
+ * @todo Under Construction
+ */
+
+/**\defgroup H5IM HDF5 Images API (H5IM)
  *
  * <em>Creating and manipulating HDF5 datasets intended to be
  * interpreted as images (H5IM)</em>
@@ -27,7 +31,7 @@ extern "C" {
  * document: \ref IMG
  * This version of the API is primarily concerned with two dimensional raster
  * data similar to HDF4 Raster Images.
- * The HDF5 Images API uses the \ref H5LT HDF5 API.
+ * The HDF5 Images API uses the \ref H5LT.
  *
  * \note \Bold{Programming hints:}
  * \note To use any of these functions or subroutines,
diff --git a/hl/src/H5LDpublic.h b/hl/src/H5LDpublic.h
index fed0c1c..363b59c 100644
--- a/hl/src/H5LDpublic.h
+++ b/hl/src/H5LDpublic.h
@@ -34,7 +34,7 @@ extern "C" {
  *          It will return failure if \p cur_dims is NULL.
  *
  * \note See Also:
- * \note Dataset Watch functions (used with \ref h5watch):
+ * \note Dataset Watch functions (used with h5watch):
  *       - H5LDget_dset_dims()
  *       - H5LDget_dset_elmts()
  *       - H5LDget_dset_type_size()
@@ -71,7 +71,7 @@ H5_HLDLL herr_t H5LDget_dset_dims(hid_t did, hsize_t *cur_dims);
  *          conflict with these two separators.
  *
  * \note See Also:
- * \note Dataset Watch functions (used with \ref h5watch):
+ * \note Dataset Watch functions (used with h5watch):
  *       - H5LDget_dset_dims()
  *       - H5LDget_dset_elmts()
  *       - H5LDget_dset_type_size()
@@ -123,7 +123,7 @@ H5_HLDLL size_t H5LDget_dset_type_size(hid_t did, const char *fields);
  *          two separators.
  *
  * \note See Also:
- * \note Dataset Watch functions (used with \ref h5watch):
+ * \note Dataset Watch functions (used with h5watch):
  *       - H5LDget_dset_dims()
  *       - H5LDget_dset_elmts()
  *       - H5LDget_dset_type_size()
diff --git a/hl/src/H5LTpublic.h b/hl/src/H5LTpublic.h
index d1684fd..15cd845 100644
--- a/hl/src/H5LTpublic.h
+++ b/hl/src/H5LTpublic.h
@@ -35,7 +35,11 @@ typedef enum H5LT_lang_t {
 extern "C" {
 #endif
 
-/**\defgroup H5LT Lite
+/** \page H5LT_UG The HDF5 High Level Lite
+ * @todo Under Construction
+ */
+
+/**\defgroup H5LT HDF5 Lite APIs (H5LT,H5LD)
  * <em>Functions used to simplify creating and manipulating datasets,
  * attributes and other features (H5LT, H5LD)</em>
  *
@@ -57,87 +61,93 @@ extern "C" {
  *
  * <table>
  * <tr valign="top"><td style="border: none;">
+ *
  * - Dataset Functions
  *   - Make dataset functions
- *     - \ref H5LTmake_dataset
- *     - \ref H5LTmake_dataset_char
- *     - \ref H5LTmake_dataset_short
- *     - \ref H5LTmake_dataset_int
- *     - \ref H5LTmake_dataset_long
- *     - \ref H5LTmake_dataset_float
- *     - \ref H5LTmake_dataset_double
- *     - \ref H5LTmake_dataset_string
+ *      - \ref H5LTmake_dataset
+ *      - \ref H5LTmake_dataset_char
+ *      - \ref H5LTmake_dataset_short
+ *      - \ref H5LTmake_dataset_int
+ *      - \ref H5LTmake_dataset_long
+ *      - \ref H5LTmake_dataset_float
+ *      - \ref H5LTmake_dataset_double
+ *      - \ref H5LTmake_dataset_string
  *
  *   - Read dataset functions
- *     - \ref H5LTread_dataset
- *     - \ref H5LTread_dataset_char
- *     - \ref H5LTread_dataset_short
- *     - \ref H5LTread_dataset_int
- *     - \ref H5LTread_dataset_long
- *     - \ref H5LTread_dataset_float
- *     - \ref H5LTread_dataset_double
- *     - \ref H5LTread_dataset_string
+ *      - \ref H5LTread_dataset
+ *      - \ref H5LTread_dataset_char
+ *      - \ref H5LTread_dataset_short
+ *      - \ref H5LTread_dataset_int
+ *      - \ref H5LTread_dataset_long
+ *      - \ref H5LTread_dataset_float
+ *      - \ref H5LTread_dataset_double
+ *      - \ref H5LTread_dataset_string
  *
  *   - Query dataset functions
- *     - \ref H5LTfind_dataset
- *     - \ref H5LTget_dataset_ndims
- *     - \ref H5LTget_dataset_info
+ *      - \ref H5LTfind_dataset
+ *      - \ref H5LTget_dataset_ndims
+ *      - \ref H5LTget_dataset_info
  *
  *   - Dataset watch functions
- *     - \ref H5LDget_dset_dims
- *     - \ref H5LDget_dset_elmts
- *     - \ref H5LDget_dset_type_size
+ *      - \ref H5LDget_dset_dims
+ *      - \ref H5LDget_dset_elmts
+ *      - \ref H5LDget_dset_type_size
+ *
  * </td><td style="border: none;">
+ *
  * - Attribute Functions
  *   - Set attribute functions
- *     - \ref H5LTset_attribute_string
- *     - \ref H5LTset_attribute_char
- *     - \ref H5LTset_attribute_uchar
- *     - \ref H5LTset_attribute_short
- *     - \ref H5LTset_attribute_ushort
- *     - \ref H5LTset_attribute_int
- *     - \ref H5LTset_attribute_uint
- *     - \ref H5LTset_attribute_long
- *     - \ref H5LTset_attribute_long_long
- *     - \ref H5LTset_attribute_ulong
- *     - \ref H5LTset_attribute_ullong
- *     - \ref H5LTset_attribute_float
- *     - \ref H5LTset_attribute_double
- *     - <code>H5LTset_attribute_f</code> (fortran ONLY)
+ *      - \ref H5LTset_attribute_string
+ *      - \ref H5LTset_attribute_char
+ *      - \ref H5LTset_attribute_uchar
+ *      - \ref H5LTset_attribute_short
+ *      - \ref H5LTset_attribute_ushort
+ *      - \ref H5LTset_attribute_int
+ *      - \ref H5LTset_attribute_uint
+ *      - \ref H5LTset_attribute_long
+ *      - \ref H5LTset_attribute_long_long
+ *      - \ref H5LTset_attribute_ulong
+ *      - \ref H5LTset_attribute_ullong
+ *      - \ref H5LTset_attribute_float
+ *      - \ref H5LTset_attribute_double
+ *      - <code>H5LTset_attribute_f</code> (fortran ONLY)
  *
  *   - Get attribute functions
- *     - \ref H5LTget_attribute
- *     - \ref H5LTget_attribute_string
- *     - \ref H5LTget_attribute_char
- *     - \ref H5LTget_attribute_uchar
- *     - \ref H5LTget_attribute_short
- *     - \ref H5LTget_attribute_ushort
- *     - \ref H5LTget_attribute_int
- *     - \ref H5LTget_attribute_uint
- *     - \ref H5LTget_attribute_long
- *     - \ref H5LTget_attribute_long_long
- *     - \ref H5LTget_attribute_ulong
- *     - \ref H5LTget_attribute_ullong
- *     - \ref H5LTget_attribute_float
- *     - \ref H5LTget_attribute_double
+ *      - \ref H5LTget_attribute
+ *      - \ref H5LTget_attribute_string
+ *      - \ref H5LTget_attribute_char
+ *      - \ref H5LTget_attribute_uchar
+ *      - \ref H5LTget_attribute_short
+ *      - \ref H5LTget_attribute_ushort
+ *      - \ref H5LTget_attribute_int
+ *      - \ref H5LTget_attribute_uint
+ *      - \ref H5LTget_attribute_long
+ *      - \ref H5LTget_attribute_long_long
+ *      - \ref H5LTget_attribute_ulong
+ *      - \ref H5LTget_attribute_ullong
+ *      - \ref H5LTget_attribute_float
+ *      - \ref H5LTget_attribute_double
  *
  *   - Query attribute functions
- *     - \ref H5LTfind_attribute
- *     - \ref H5LTget_attribute_info
- *     - \ref H5LTget_attribute_ndims
+ *      - \ref H5LTfind_attribute
+ *      - \ref H5LTget_attribute_info
+ *      - \ref H5LTget_attribute_ndims
+ *
  * </td><td style="border: none;">
+ *
  * - Datatype Functions
  *   - Datatype translation functions
- *     - \ref H5LTtext_to_dtype
- *     - \ref H5LTdtype_to_text
+ *      - \ref H5LTtext_to_dtype
+ *      - \ref H5LTdtype_to_text
  *
  * - File image function
  *   - Open file image function
- *     - \ref H5LTopen_file_image
+ *      - \ref H5LTopen_file_image
  *
  * - Path and object function
  *   - Query path and object function
- *     - \ref H5LTpath_valid
+ *      - \ref H5LTpath_valid
+ *
  * </td></tr>
  * </table>
  *
@@ -1510,7 +1520,7 @@ H5_HLDLL herr_t H5LTfind_attribute(hid_t loc_id, const char *name);
  *            indicating the file’s root group, followed by the members
  *          - A relative path with respect to \p loc_id
  *          - A dot (\c .), if \p loc_id is the object identifier for
- *            the object itself
+ *            the object itself.
  *
  *          If \p path is an absolute path, then \p loc_id can be an
  *          identifier for any object in the file as it is used only to
diff --git a/hl/src/H5PTpublic.h b/hl/src/H5PTpublic.h
index 04741ac..6552aa9 100644
--- a/hl/src/H5PTpublic.h
+++ b/hl/src/H5PTpublic.h
@@ -18,7 +18,11 @@
 extern "C" {
 #endif
 
-/**\defgroup H5PT Packet Table
+/** \page H5PT_UG The HDF5 High Level Packet Table
+ * @todo Under Construction
+ */
+
+/**\defgroup H5PT HDF5 Packet Table APIs (H5PT)
  *
  * <em>Creating and manipulating HDF5 datasets to support append-
  * and read-only operations on table data (H5PT)</em>
@@ -210,7 +214,7 @@ H5_HLDLL herr_t H5PTclose(hid_t table_id);
  *          Level 0 is faster but offers the least compression;
  *          level 9 is slower but offers maximum compression.
  *          A setting of -1 indicates that no compression is desired.
-
+ *
  */
 /* This function may be removed from the packet table in release 1.8.19. */
 H5_HLDLL hid_t H5PTcreate_fl(hid_t loc_id, const char *dset_name, hid_t dtype_id, hsize_t chunk_size,
diff --git a/hl/src/H5TBpublic.h b/hl/src/H5TBpublic.h
index 9ad8e08..44b122c 100644
--- a/hl/src/H5TBpublic.h
+++ b/hl/src/H5TBpublic.h
@@ -18,7 +18,11 @@
 extern "C" {
 #endif
 
-/**\defgroup H5TB Table
+/** \page H5TB_UG The HDF5 High Level Table
+ * @todo Under Construction
+ */
+
+/**\defgroup H5TB HDF5 Table APIs (H5TB)
  *
  * <em>Creating and manipulating HDF5 datasets intended to be
  * interpreted as tables (H5TB)</em>
@@ -656,12 +660,10 @@ H5_HLDLL herr_t H5TBAget_title(hid_t loc_id, char *table_title);
  * \return A return value of 0 indicates a fill value is not present.
  * \return A return value <0 indicates an error.
  *
- *
  * \details H5TBget_fill() reads the table attribute fill values into
  *          the buffer \p dst_buf for the table specified by \p dset_id
  *          and \p dset_name located in \p loc_id.
  *
- *
  * \par Example
  * \include H5TBAget_fill.c
  *