Merge doxygen2 into develop (#553)

* Fixed warnings and started H5Epublic.h.

* Include H5FD* headers to correctly resolve references.

* Doxygen2 (#330)

* H5Eauto_is_v2.

* Added a few more calls.

* Added a few more H5E calls.

* First cut of H5E v2.

* Added the deprecated v1 calls.

* Updated spacing.

* Once more.

* Taking some inspiration from Eigen3.

* Add doxygen for the assigned functions: H5Pregister1,H5Pinsert1,H5Pen… (#352)

* Add doxygen for the assigned functions: H5Pregister1,H5Pinsert1,H5Pencode1, H5Pget_filter_by_id1,H5Pget_version, H5Pset_file_space,H5Pget_file_space. Someone already adds H5Pget_filter1. Also fixs an extra parameter 'close' call back function for HPregister2.

* doxygen work. fixs format by using clang-format.

* doxgen work for H5Pregister1 etc. Addressed Barbara and Gerd's comments.
For Quincey's comments, since we are not supposed to change the source code.
I leave this to future improvements.

* added documentation for H5P APIs (#350)

* add documenation for H5Pget_buffer,H5Pget_data_transform,H5Pget_edc_check,H5Pget_hyper_vector_size,H5Pget_preserve,H5Pget_type_conv_cb,H5Pget_vlen_mem_manager,H5Pset_btree_ratios

* format corrections

* fixed grammer

* fixed herr_t

* Better name.

* A fresh look.

* add doxygen to H5Ppublic.h

* use attention instead of warning

* Add doxygen comments in H5Ppublic.h (#375)

* Add doxygen comments in H5Ppublic.h

* H5Pset_meta_block_size
* H5Pset_metadata_read_attempts
* H5Pset_multi_type
* H5Pset_object_flush_cb
* H5Pset_sieve_buf_size
* H5Pset_small_data_block_size
* H5Pset_all_coll_metadata_ops
* H5Pget_all_coll_metadata_ops

* Add DOXYGEN_EXAMPLES_DIR to src/CMakeLists.txt

* Fix clang-format errors

* Fix filenames in doxygen/examples

* add doxygen to H5Ppublic.h (#378)

* add doxygen to H5Ppublic.h

* use attention instead of warning

Co-authored-by: Kimmy Mu <kmu@hdfgroup.org>

* Revert "add doxygen to H5Ppublic.h (#378)"

This reverts commit 2ee1821b138a5c00b15ea57ce9e950367480f5f2.

* Updated Doxygen variables.

* I forgot to copy two images.

* Enable desktop search by default.

* Add my assigned Doxygen documentation.

* Remove whitespace at EOL.  Appease clang-format.

* Addressed Chris' comments.

* Added an alias for asynchronous functions.

* One space is enough for all of us.

* Slightly restructured RM page.

* address some issues

* reformatting

* Style external links.

* reformatting

* reformatting

* Added "Metadata Caching in HDF5" as a technical note example.

* Revise this soon!

* Added specification examples.

* Fixed references.

* Added H5AC cache image stuff and file format study.

* Added older FMT versions. Where did 1.0 go?

* Updated C/C++ note and replaced ambiguous labels.

* Reformat source with clang v10.0.1.

* Added the VFL technical note.

* Added what I believe might be called version 1.0 of the format.

* Added the remaining specs.

* Added H5Z callback documentation and fixed a few mistakes.

* Added dox for deprecated H5G calls and fixed a few snippet blockIDs.

* clang-format happy?

* Ok?

* Bonus track: Deprecated H5D functions.

* Carry over the more detailed group description.

* Added documentation for the missing and deprecated H5R calls.

* Life is easier and less repetitive w/ snippets. Use them!

* Eliminate the snippet block ID artifacts in the HTML rendering.

* Fixed snippet HTML artifacts and added a few missing calls.

* Under 20 H5Ps to go!

* Almost complete!

* "This is a form of pedantry up with which I will not put." (Churchill)

* Let's not waste as much space on bulleted lists!

* First complete (?) draft of the Doxygen-based RM.

* Completeness check and minor fixes along the way.

* Pedantry.

* Adding missing H5FD calls checkpoint.

* Pedantry.

* More pedantry.

* Added H5Pset_fapl_log.

* First draft of H5ES.

* Fixed warnings.

* Prep. for map module.

* First cut of the map module.

* Pedantry.

* Possible H5F introduction.

* Fix the indentation.

* Pedantry.

* Ditto.

* Thanks to the reviewers for their comments.

* Added missing images.

* Line numbers are a distraction here.

* More examples, references, and clean-up. Don't repeat yourself!

* Clang pedantry.

* Ditto.

* More reviewer comments...

* Templatized references and cleaned up \todos.

* Committing clang-format changes

* Fixed MANIFEST.

* Addressed Quincey's comments. (OCPLs)

* Fixed a few more \todo items.

* Fixed more \todo items.

* Added attribute life cycle.

* Forgot the examples file.

* Committing clang-format changes

* Pedantry.

* Live and learn!

* Added a sample H5D life cycle.

* Committing clang-format changes

* Pedantry.

Co-authored-by: kyang2014 <kyang2014@users.noreply.github.com>
Co-authored-by: Scot Breitenfeld <brtnfld@hdfgroup.org>
Co-authored-by: Kimmy Mu <kmu@hdfgroup.org>
Co-authored-by: Christopher Hogan <ChristopherHogan@users.noreply.github.com>
Co-authored-by: jya-kmu <53388330+jya-kmu@users.noreply.github.com>
Co-authored-by: David Young <dyoung@hdfgroup.org>
Co-authored-by: Larry Knox <lrknox@hdfgroup.org>
Co-authored-by: github-actions <41898282+github-actions[bot]@users.noreply.github.com>

1 files changed, 56 insertions, 58 deletions

diff --git a/src/H5Tpublic.h b/src/H5Tpublic.h
index 1457053..5301ea2 100644
--- a/src/H5Tpublic.h
+++ b/src/H5Tpublic.h
@@ -28,7 +28,7 @@
  * internal If this goes over 16 types (0-15), the file format will need to
  *          change.
  */
-//! [H5T_class_t_snip]
+//! <!-- [H5T_class_t_snip] -->
 typedef enum H5T_class_t {
     H5T_NO_CLASS  = -1, /**< error                                   */
     H5T_INTEGER   = 0,  /**< integer types                           */
@@ -45,12 +45,12 @@ typedef enum H5T_class_t {
 
     H5T_NCLASSES /**< sentinel: this must be last             */
 } H5T_class_t;
-//! [H5T_class_t_snip]
+//! <!-- [H5T_class_t_snip] -->
 
 /**
  * Byte orders
  */
-//! [H5T_order_t_snip]
+//! <!-- [H5T_order_t_snip] -->
 typedef enum H5T_order_t {
     H5T_ORDER_ERROR = -1, /**< error                                   */
     H5T_ORDER_LE    = 0,  /**< little endian                           */
@@ -60,12 +60,12 @@ typedef enum H5T_order_t {
     H5T_ORDER_NONE  = 4   /**< no particular order (strings, bits,..)  */
     /*H5T_ORDER_NONE must be last */
 } H5T_order_t;
-//! [H5T_order_t_snip]
+//! <!-- [H5T_order_t_snip] -->
 
 /**
  * Types of integer sign schemes
  */
-//! [H5T_sign_t_snip]
+//! <!-- [H5T_sign_t_snip] -->
 typedef enum H5T_sign_t {
     H5T_SGN_ERROR = -1, /**< error                                   */
     H5T_SGN_NONE  = 0,  /**< this is an unsigned type                */
@@ -73,12 +73,12 @@ typedef enum H5T_sign_t {
 
     H5T_NSGN = 2 /** sentinel: this must be last!             */
 } H5T_sign_t;
-//! [H5T_sign_t_snip]
+//! <!-- [H5T_sign_t_snip] -->
 
 /**
  * Floating-point normalization schemes
  */
-//! [H5T_norm_t_snip]
+//! <!-- [H5T_norm_t_snip] -->
 typedef enum H5T_norm_t {
     H5T_NORM_ERROR   = -1, /**< error                                   */
     H5T_NORM_IMPLIED = 0,  /**< msb of mantissa isn't stored, always 1  */
@@ -86,7 +86,7 @@ typedef enum H5T_norm_t {
     H5T_NORM_NONE    = 2   /**< not normalized                          */
     /*H5T_NORM_NONE must be last */
 } H5T_norm_t;
-//! [H5T_norm_t_snip]
+//! <!-- [H5T_norm_t_snip] -->
 
 /**
  * Character set to use for text strings.
@@ -141,7 +141,7 @@ typedef enum H5T_str_t {
 /**
  * Type of padding to use in other atomic types
  */
-//! [H5T_pad_t_snip]
+//! <!-- [H5T_pad_t_snip] -->
 typedef enum H5T_pad_t {
     H5T_PAD_ERROR      = -1, /**< error                           */
     H5T_PAD_ZERO       = 0,  /**< always set to zero              */
@@ -150,7 +150,7 @@ typedef enum H5T_pad_t {
 
     H5T_NPAD = 3 /**< sentinal: THIS MUST BE LAST     */
 } H5T_pad_t;
-//! [H5T_pad_t_snip]
+//! <!-- [H5T_pad_t_snip] -->
 
 /**
  * Commands sent to conversion functions
@@ -173,14 +173,14 @@ typedef enum H5T_bkg_t {
 /**
  * Type conversion client data
  */
-//! [H5T_cdata_t_snip]
+//! <!-- [H5T_cdata_t_snip] -->
 typedef struct H5T_cdata_t {
     H5T_cmd_t command;  /**< what should the conversion function do?    */
     H5T_bkg_t need_bkg; /**< is the background buffer needed?	     */
     hbool_t   recalc;   /**< recalculate private data		     */
     void *    priv;     /**< private data				     */
 } H5T_cdata_t;
-//! [H5T_cdata_t_snip]
+//! <!-- [H5T_cdata_t_snip] -->
 
 /**
  * Conversion function persistence
@@ -194,25 +194,32 @@ typedef enum H5T_pers_t {
 /**
  * The order to retrieve atomic native datatype
  */
-//! [H5T_direction_t_snip]
+//! <!-- [H5T_direction_t_snip] -->
 typedef enum H5T_direction_t {
     H5T_DIR_DEFAULT = 0, /**< default direction is inscendent        */
     H5T_DIR_ASCEND  = 1, /**< in inscendent order                    */
     H5T_DIR_DESCEND = 2  /**< in descendent order                    */
 } H5T_direction_t;
-//! [H5T_direction_t_snip]
+//! <!-- [H5T_direction_t_snip] -->
 
 /**
  * The exception type passed into the conversion callback function
  */
 typedef enum H5T_conv_except_t {
-    H5T_CONV_EXCEPT_RANGE_HI  = 0, /**< source value is greater than destination's range */
-    H5T_CONV_EXCEPT_RANGE_LOW = 1, /**< source value is less than destination's range    */
-    H5T_CONV_EXCEPT_PRECISION = 2, /**< source value loses precision in destination      */
-    H5T_CONV_EXCEPT_TRUNCATE  = 3, /**< source value is truncated in destination         */
-    H5T_CONV_EXCEPT_PINF      = 4, /**< source value is positive infinity(floating number) */
-    H5T_CONV_EXCEPT_NINF      = 5, /**< source value is negative infinity(floating number) */
-    H5T_CONV_EXCEPT_NAN       = 6  /**< source value is NaN(floating number)             */
+    H5T_CONV_EXCEPT_RANGE_HI = 0,
+    /**< Source value is greater than destination's range */
+    H5T_CONV_EXCEPT_RANGE_LOW = 1,
+    /**< Source value is less than destination's range */
+    H5T_CONV_EXCEPT_PRECISION = 2,
+    /**< Source value loses precision in destination */
+    H5T_CONV_EXCEPT_TRUNCATE = 3,
+    /**< Source value is truncated in destination */
+    H5T_CONV_EXCEPT_PINF = 4,
+    /**< Source value is positive infinity */
+    H5T_CONV_EXCEPT_NINF = 5,
+    /**< Source value is negative infinity */
+    H5T_CONV_EXCEPT_NAN = 6
+    /**< Source value is \c NaN (not a number, including \c QNaN and \c SNaN) */
 } H5T_conv_except_t;
 
 /**
@@ -254,17 +261,31 @@ extern "C" {
 /**
  * All datatype conversion functions are...
  */
-//! [H5T_conv_t_snip]
+//! <!-- [H5T_conv_t_snip] -->
 typedef herr_t (*H5T_conv_t)(hid_t src_id, hid_t dst_id, H5T_cdata_t *cdata, size_t nelmts, size_t buf_stride,
                              size_t bkg_stride, void *buf, void *bkg, hid_t dset_xfer_plist);
-//! [H5T_conv_t_snip]
+//! <!-- [H5T_conv_t_snip] -->
 
+//! <!-- [H5T_conv_except_func_t_snip] -->
 /**
- * Exception handler.  If an exception like overflow happenes during conversion,
- * this function is called if it's registered through H5Pset_type_conv_cb().
+ * \brief Exception handler.
+ *
+ * \param[in] except_type The kind of exception that occurred
+ * \param[in] src_id Source datatype identifier
+ * \param[in] dst_id Destination datatype identifier
+ * \param[in] src_buf Source data buffer
+ * \param[in,out] dst_buf Destination data buffer
+ * \param[in,out] user_data Callback context
+ * \returns Valid callback function return values are #H5T_CONV_ABORT,
+ *          #H5T_CONV_UNHANDLED and #H5T_CONV_HANDLED.
+ *
+ * \details If an exception like overflow happenes during conversion, this
+ *          function is called if it's registered through H5Pset_type_conv_cb().
+ *
  */
 typedef H5T_conv_ret_t (*H5T_conv_except_func_t)(H5T_conv_except_t except_type, hid_t src_id, hid_t dst_id,
                                                  void *src_buf, void *dst_buf, void *user_data);
+//! <!-- [H5T_conv_except_func_t_snip] -->
 
 /* When this header is included from a private header, don't make calls to H5open() */
 #undef H5OPEN
@@ -1061,7 +1082,7 @@ H5_DLLVAR hid_t H5T_NATIVE_UINT_FAST64_g;
  *          predefined datatype.
  *
  *          When creating a variable-length string datatype, \p size must
- *          be #H5T_VARIABLE.
+ *          be #H5T_VARIABLE; see \ref_vlen_strings.
  *
  *          When creating a fixed-length string datatype, \p size will
  *          be the length of the string in bytes. The length of the
@@ -1075,13 +1096,9 @@ H5_DLLVAR hid_t H5T_NATIVE_UINT_FAST64_g;
  *          The datatype identifier returned from this function should be
  *          released with H5Tclose or resource leaks will result.
  *
- * \since 1.2.0
- *
  * \see H5Tclose()
  *
- * \todo Original has a reference to “Creating variable-length string
- *       datatypes”.
- * \todo Create an example for H5Tcreate.
+ * \since 1.2.0
  *
  */
 H5_DLL hid_t H5Tcreate(H5T_class_t type, size_t size);
@@ -1106,8 +1123,6 @@ H5_DLL hid_t H5Tcreate(H5T_class_t type, size_t size);
  *          The returned datatype identifier should be released with H5Tclose()
  *          to prevent resource leak.
  *
- * \todo Create an example for H5Tcopy().
- *
  */
 H5_DLL hid_t H5Tcopy(hid_t type_id);
 /**
@@ -1130,8 +1145,6 @@ H5_DLL herr_t H5Tclose(hid_t type_id);
  *
  * \brief Asynchronous version of H5Tclose().
  *
- * \todo Create an example for H5Tclose_async().
- *
  */
 H5_DLL herr_t H5Tclose_async(const char *app_file, const char *app_func, unsigned app_line, hid_t type_id,
                              hid_t es_id);
@@ -1222,8 +1235,6 @@ H5_DLL herr_t H5Tcommit2(hid_t loc_id, const char *name, hid_t type_id, hid_t lc
  *
  * \brief Asynchronous version of H5Tcommit2().
  *
- * \todo Create an example for H5Tcommit_async().
- *
  */
 H5_DLL herr_t H5Tcommit_async(const char *app_file, const char *app_func, unsigned app_line, hid_t loc_id,
                               const char *name, hid_t type_id, hid_t lcpl_id, hid_t tcpl_id, hid_t tapl_id,
@@ -1257,8 +1268,6 @@ H5_DLL hid_t H5Topen2(hid_t loc_id, const char *name, hid_t tapl_id);
  *
  * \brief Asynchronous version of H5Topen2().
  *
- * \todo Create an example for H5Topen_async().
- *
  */
 H5_DLL hid_t H5Topen_async(const char *app_file, const char *app_func, unsigned app_line, hid_t loc_id,
                            const char *name, hid_t tapl_id, hid_t es_id);
@@ -1503,8 +1512,6 @@ H5_DLL herr_t H5Trefresh(hid_t type_id);
  *
  * \since 1.2.0
  *
- * \todo Create example for  H5Tinsert
- *
  */
 H5_DLL herr_t H5Tinsert(hid_t parent_id, const char *name, size_t offset, hid_t member_id);
 /**
@@ -1663,10 +1670,7 @@ H5_DLL herr_t H5Tenum_valueof(hid_t type, const char *name, void *value /*out*/)
  *            character base type creates a variable-length sequence of strings
  *            (a variable-length, 1-dimensional array), with each element of
  *            the array being of the string or character base type.\n
- *            To create a variable-length string datatype, see "Creating
- *            variable-length string datatypes."
- *
- * \todo Fix the reference.
+ *            To create a variable-length string datatype, see \ref_vlen_strings.
  *
  */
 H5_DLL hid_t H5Tvlen_create(hid_t base_id);
@@ -1870,13 +1874,9 @@ H5_DLL htri_t H5Tdetect_class(hid_t type_id, H5T_class_t cls);
  *          actual data and a size value.  This function does not return the
  *          size of actual variable-length sequence data.
  *
- * \since 1.2.0
- *
  * \see H5Tset_size()
  *
- * \todo Original has a reference to “Creating variable-length string datatypes”.
- * \todo Create an example for H5Tget_size().
- *
+ * \since 1.2.0
  */
 H5_DLL size_t H5Tget_size(hid_t type_id);
 /**
@@ -2090,7 +2090,7 @@ H5_DLL H5T_pad_t H5Tget_inpad(hid_t type_id);
  */
 H5_DLL H5T_str_t H5Tget_strpad(hid_t type_id);
 /**
- * \ingroup COMPOUND
+ * \ingroup COMPOUND ENUM
  *
  * \brief Retrieves the number of elements in a compound or enumeration datatype
  *
@@ -2107,7 +2107,7 @@ H5_DLL H5T_str_t H5Tget_strpad(hid_t type_id);
  */
 H5_DLL int H5Tget_nmembers(hid_t type_id);
 /**
- * \ingroup COMPOUND
+ * \ingroup COMPOUND ENUM
  *
  * \brief Retrieves the name of a compound or enumeration datatype member
  *
@@ -2134,7 +2134,7 @@ H5_DLL int H5Tget_nmembers(hid_t type_id);
  */
 H5_DLL char *H5Tget_member_name(hid_t type_id, unsigned membno);
 /**
- * \ingroup COMPOUND
+ * \ingroup COMPOUND ENUM
  *
  * \brief Retrieves the index of a compound or enumeration datatype member
  *
@@ -2406,6 +2406,7 @@ H5_DLL hid_t H5Tget_native_type(hid_t type_id, H5T_direction_t direction);
  *
  *          \li Variable-length string datatypes: If \p dtype_id is a
  *          variable-length string, size must normally be set to #H5T_VARIABLE.
+ *          See \ref_vlen_strings.
  *
  *          \li Compound datatypes: This function may be used to increase or
  *          decrease the size of a compound datatype, but the function will
@@ -2416,12 +2417,9 @@ H5_DLL hid_t H5Tget_native_type(hid_t type_id, H5T_direction_t direction);
  *          variable-length array datatypes (#H5T_VLEN), or reference datatypes
  *          (#H5T_REFERENCE).
  *
- * \since 1.2.0
- *
  * \see H5Tget_size()
  *
- *\todo Create an example for H5Tset_size().
- *\todo Original has a reference to “Creating variable-length string datatypes”.
+ * \since 1.2.0
  *
  */
 H5_DLL herr_t H5Tset_size(hid_t type_id, size_t size);
@@ -2873,7 +2871,7 @@ H5_DLL htri_t H5Tcompiler_conv(hid_t src_id, hid_t dst_id);
  *       enough to hold the larger of the input and output data.
  *
  * \version 1.6.3 \p nelmts parameter type changed to size_t.
- * \version 1.4.0 \p nelmts parameter type changed to \ref hsize_t.
+ * \version 1.4.0 \p nelmts parameter type changed to hsize_t.
  *
  */
 H5_DLL herr_t H5Tconvert(hid_t src_id, hid_t dst_id, size_t nelmts, void *buf, void *background,