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, 126 insertions, 67 deletions

diff --git a/src/H5Apublic.h b/src/H5Apublic.h
index 68d8a8a..2d58cdf 100644
--- a/src/H5Apublic.h
+++ b/src/H5Apublic.h
@@ -22,19 +22,40 @@
 #include "H5Opublic.h" /* Object Headers			*/
 #include "H5Tpublic.h" /* Datatypes				*/
 
-/* Information struct for attribute (for H5Aget_info/H5Aget_info_by_idx) */
-//! [H5A_info_t_snip]
+//! <!-- [H5A_info_t_snip] -->
+/**
+ * Information struct for H5Aget_info() / H5Aget_info_by_idx()
+ */
 typedef struct {
-    hbool_t           corder_valid; /* Indicate if creation order is valid */
-    H5O_msg_crt_idx_t corder;       /* Creation order                 */
-    H5T_cset_t        cset;         /* Character set of attribute name */
-    hsize_t           data_size;    /* Size of raw data		  */
+    hbool_t           corder_valid; /**< Indicate if creation order is valid */
+    H5O_msg_crt_idx_t corder;       /**< Creation order                 */
+    H5T_cset_t        cset;         /**< Character set of attribute name */
+    hsize_t           data_size;    /**< Size of raw data		  */
 } H5A_info_t;
-//! [H5A_info_t_snip]
+//! <!-- [H5A_info_t_snip] -->
 
-/* Typedef for H5Aiterate2() callbacks */
+//! <!-- [H5A_operator2_t_snip] -->
+/**
+ * Typedef for H5Aiterate2() / H5Aiterate_by_name() callbacks
+ * \param[in] location_id The identifier for the group, dataset
+ *            or named datatype being iterated over
+ * \param[in] attr_name The name of the current object attribute
+ * \param[in] ainfo The attribute’s info struct
+ * \param[in,out] op_data A pointer to the operator data passed in to
+ *                H5Aiterate2() or H5Aiterate_by_name()
+ * \returns The return values from an operator are:
+ *          \li Zero causes the iterator to continue, returning zero when
+ *              all attributes have been processed.
+ *          \li Positive causes the iterator to immediately return that
+ *              positive value, indicating short-circuit success. The
+ *              iterator can be restarted at the next attribute.
+ *          \li Negative causes the iterator to immediately return that value,
+ *              indicating failure. The iterator can be restarted at the next
+ *              attribute.
+ */
 typedef herr_t (*H5A_operator2_t)(hid_t location_id /*in*/, const char *attr_name /*in*/,
                                   const H5A_info_t *ainfo /*in*/, void *op_data /*in,out*/);
+//! <!-- [H5A_operator2_t_snip] -->
 
 /********************/
 /* Public Variables */
@@ -105,8 +126,8 @@ H5_DLL herr_t H5Aclose(hid_t attr_id);
  *          The attribute identifier returned by this function must be released
  *          with H5Aclose() resource leaks will develop.
  *
- * \note The \p acpl and \p aapl parameters are currently not used; specify
- *       #H5P_DEFAULT.
+ * \note The \p aapl parameter is currently not used; specify #H5P_DEFAULT.
+ *
  * \note If \p loc_id is a file identifier, the attribute will be attached
  *       that file’s root group.
  *
@@ -117,6 +138,11 @@ H5_DLL herr_t H5Aclose(hid_t attr_id);
  */
 H5_DLL hid_t H5Acreate2(hid_t loc_id, const char *attr_name, hid_t type_id, hid_t space_id, hid_t acpl_id,
                         hid_t aapl_id);
+/*--------------------------------------------------------------------------*/
+/**
+ * \ingroup ASYNC
+ * \async_variant_of{H5Acreate}
+ */
 H5_DLL hid_t H5Acreate_async(const char *app_file, const char *app_func, unsigned app_line, hid_t loc_id,
                              const char *attr_name, hid_t type_id, hid_t space_id, hid_t acpl_id,
                              hid_t aapl_id, hid_t es_id);
@@ -659,30 +685,12 @@ H5_DLL hid_t H5Aget_type(hid_t attr_id);
  *          the value returned identifies the parameter to be operated on
  *          in the next step of the iteration.
  *
- *          The #H5A_operator2_t prototype for the \p op parameter is a
- *          user defined function where:
- *          The operation receives the location identifier for the group or
- *          dataset being iterated over, \p location_id; the name of the
- *          current object attribute, \p attr_name; the attribute’s info
- *          struct, \p ainfo; and a pointer to the operator data passed
- *          into H5Aiterate2(), \p op_data.
- *
- *          Valid return values from an operator and the resulting
- *          H5Aiterate2() and \p op behavior are as follows:
- *
- *          \li Zero causes the iterator to continue, returning zero when
- *              all attributes have been processed.
- *          \li A positive value causes the iterator to immediately return
- *              that positive value, indicating short-circuit success. The
- *              iterator can be restarted at the next attribute, as
- *              indicated by the return value of \p idx.
- *          \li A negative value causes the iterator to immediately return
- *              that value, indicating failure. The iterator can be
- *              restarted at the next attribute, as indicated by the return
- *              value of \p idx.
+ *          \p op is a user-defined function whose prototype is defined
+ *          as follows:
+ *          \snippet this H5A_operator2_t_snip
+ *          \click4more
  *
  * \note This function is also available through the H5Aiterate() macro.
- * \todo Add snippet for H5A_operator2_t
  *
  * \since 1.8.0
  *
@@ -751,13 +759,10 @@ H5_DLL herr_t H5Aiterate2(hid_t loc_id, H5_index_t idx_type, H5_iter_order_t ord
  *          the value returned identifies the parameter to be operated on in
  *          the next step of the iteration.
  *
- *          The #H5A_operator2_t prototype for the \p op parameter is a
- *          user defined function where:
- *          The operation receives the location identifier for the group or
- *          dataset being iterated over, \p location_id; the name of the
- *          current object attribute, \p attr_name; the attribute’s info
- *          struct, \p ainfo; and a pointer to the operator data passed
- *          into H5Aiterate_by_name(), \p op_data.
+ *          \p op is a user-defined function whose prototype is defined
+ *          as follows:
+ *          \snippet this H5A_operator2_t_snip
+ *          \click4more
  *
  *          Valid return values from an operator and the resulting
  *          H5Aiterate_by_name() and \p op behavior are as follows:
@@ -777,17 +782,21 @@ H5_DLL herr_t H5Aiterate2(hid_t loc_id, H5_index_t idx_type, H5_iter_order_t ord
  *          information regarding the properties of links required to access
  *          the object, \p obj_name.
  *
- * \todo Add snippet to show H5Aoperator2_t.
  * \since 1.8.0
  *
  */
 H5_DLL herr_t H5Aiterate_by_name(hid_t loc_id, const char *obj_name, H5_index_t idx_type,
                                  H5_iter_order_t order, hsize_t *idx, H5A_operator2_t op, void *op_data,
                                  hid_t lapl_id);
-H5_DLL hid_t  H5Acreate_by_name_async(const char *app_file, const char *app_func, unsigned app_line,
-                                      hid_t loc_id, const char *obj_name, const char *attr_name, hid_t type_id,
-                                      hid_t space_id, hid_t acpl_id, hid_t aapl_id, hid_t lapl_id,
-                                      hid_t es_id);
+/*--------------------------------------------------------------------------*/
+/**
+ * \ingroup ASYNC
+ * \async_variant_of{H5Acreate_by_name}
+ */
+H5_DLL hid_t H5Acreate_by_name_async(const char *app_file, const char *app_func, unsigned app_line,
+                                     hid_t loc_id, const char *obj_name, const char *attr_name, hid_t type_id,
+                                     hid_t space_id, hid_t acpl_id, hid_t aapl_id, hid_t lapl_id,
+                                     hid_t es_id);
 /*--------------------------------------------------------------------------*/
 /**
  * \ingroup H5A
@@ -819,6 +828,11 @@ H5_DLL hid_t  H5Acreate_by_name_async(const char *app_file, const char *app_func
  * \see H5Aclose(), H5Acreate()
  */
 H5_DLL hid_t H5Aopen(hid_t obj_id, const char *attr_name, hid_t aapl_id);
+/*--------------------------------------------------------------------------*/
+/**
+ * \ingroup ASYNC
+ * \async_variant_of{H5Aopen}
+ */
 H5_DLL hid_t H5Aopen_async(const char *app_file, const char *app_func, unsigned app_line, hid_t obj_id,
                            const char *attr_name, hid_t aapl_id, hid_t es_id);
 /*--------------------------------------------------------------------------*/
@@ -868,6 +882,11 @@ H5_DLL hid_t H5Aopen_async(const char *app_file, const char *app_func, unsigned
  */
 H5_DLL hid_t H5Aopen_by_idx(hid_t loc_id, const char *obj_name, H5_index_t idx_type, H5_iter_order_t order,
                             hsize_t n, hid_t aapl_id, hid_t lapl_id);
+/*--------------------------------------------------------------------------*/
+/**
+ * \ingroup ASYNC
+ * \async_variant_of{H5Aopen_by_idx}
+ */
 H5_DLL hid_t H5Aopen_by_idx_async(const char *app_file, const char *app_func, unsigned app_line, hid_t loc_id,
                                   const char *obj_name, H5_index_t idx_type, H5_iter_order_t order, hsize_t n,
                                   hid_t aapl_id, hid_t lapl_id, hid_t es_id);
@@ -914,6 +933,11 @@ H5_DLL hid_t H5Aopen_by_idx_async(const char *app_file, const char *app_func, un
  */
 H5_DLL hid_t H5Aopen_by_name(hid_t loc_id, const char *obj_name, const char *attr_name, hid_t aapl_id,
                              hid_t lapl_id);
+/*--------------------------------------------------------------------------*/
+/**
+ * \ingroup ASYNC
+ * \async_variant_of{H5Aopen_by_name}
+ */
 H5_DLL hid_t H5Aopen_by_name_async(const char *app_file, const char *app_func, unsigned app_line,
                                    hid_t loc_id, const char *obj_name, const char *attr_name, hid_t aapl_id,
                                    hid_t lapl_id, hid_t es_id);
@@ -967,6 +991,11 @@ H5_DLL herr_t H5Aread(hid_t attr_id, hid_t type_id, void *buf);
  *
  */
 H5_DLL herr_t H5Arename(hid_t loc_id, const char *old_name, const char *new_name);
+/*--------------------------------------------------------------------------*/
+/**
+ * \ingroup ASYNC
+ * \async_variant_of{H5Aread}
+ */
 H5_DLL herr_t H5Aread_async(const char *app_file, const char *app_func, unsigned app_line, hid_t attr_id,
                             hid_t dtype_id, void *buf, hid_t es_id);
 /*--------------------------------------------------------------------------*/
@@ -1001,15 +1030,40 @@ H5_DLL herr_t H5Aread_async(const char *app_file, const char *app_func, unsigned
  *
  */
 H5_DLL herr_t H5Awrite(hid_t attr_id, hid_t type_id, const void *buf);
+/*--------------------------------------------------------------------------*/
+/**
+ * \ingroup ASYNC
+ * \async_variant_of{H5Awrite}
+ */
 H5_DLL herr_t H5Awrite_async(const char *app_file, const char *app_func, unsigned app_line, hid_t attr_id,
                              hid_t type_id, const void *buf, hid_t es_id);
+/*--------------------------------------------------------------------------*/
+/**
+ * \ingroup ASYNC
+ * \async_variant_of{H5Arename}
+ */
 H5_DLL herr_t H5Arename_async(const char *app_file, const char *app_func, unsigned app_line, hid_t loc_id,
                               const char *old_name, const char *new_name, hid_t es_id);
+/*--------------------------------------------------------------------------*/
+/**
+ * \ingroup ASYNC
+ * \async_variant_of{H5Arename_by_name}
+ */
 H5_DLL herr_t H5Arename_by_name_async(const char *app_file, const char *app_func, unsigned app_line,
                                       hid_t loc_id, const char *obj_name, const char *old_attr_name,
                                       const char *new_attr_name, hid_t lapl_id, hid_t es_id);
+/*--------------------------------------------------------------------------*/
+/**
+ * \ingroup ASYNC
+ * \async_variant_of{H5Aexists}
+ */
 H5_DLL herr_t H5Aexists_async(const char *app_file, const char *app_func, unsigned app_line, hid_t obj_id,
                               const char *attr_name, hbool_t *exists, hid_t es_id);
+/*--------------------------------------------------------------------------*/
+/**
+ * \ingroup ASYNC
+ * \async_variant_of{H5Aexists_by_name}
+ */
 H5_DLL herr_t H5Aexists_by_name_async(const char *app_file, const char *app_func, unsigned app_line,
                                       hid_t loc_id, const char *obj_name, const char *attr_name,
                                       hbool_t *exists, hid_t lapl_id, hid_t es_id);
@@ -1038,6 +1092,11 @@ H5_DLL herr_t H5Aexists_by_name_async(const char *app_file, const char *app_func
  */
 H5_DLL herr_t H5Arename_by_name(hid_t loc_id, const char *obj_name, const char *old_attr_name,
                                 const char *new_attr_name, hid_t lapl_id);
+/*--------------------------------------------------------------------------*/
+/**
+ * \ingroup ASYNC
+ * \async_variant_of{H5Aclose}
+ */
 H5_DLL herr_t H5Aclose_async(const char *app_file, const char *app_func, unsigned app_line, hid_t attr_id,
                              hid_t es_id);
 
@@ -1085,9 +1144,28 @@ H5_DLL herr_t H5Aclose_async(const char *app_file, const char *app_func, unsigne
 
 /* Typedefs */
 
-/* Typedef for H5Aiterate1() callbacks */
+//! <!-- [H5A_operator1_t_snip] -->
+/**
+ * \brief Typedef for H5Aiterate1() callbacks
+ *
+ * \param[in] location_id The identifier for the group, dataset
+ *            or named datatype being iterated over
+ * \param[in] attr_name The name of the current object attribute
+ * \param[in,out] operator_data A pointer to the operator data passed in to
+ *                H5Aiterate1()
+ * \returns The return values from an operator are:
+ *          \li Zero causes the iterator to continue, returning zero when
+ *              all attributes have been processed.
+ *          \li Positive causes the iterator to immediately return that
+ *              positive value, indicating short-circuit success. The
+ *              iterator can be restarted at the next attribute.
+ *          \li Negative causes the iterator to immediately return that value,
+ *              indicating failure. The iterator can be restarted at the next
+ *              attribute.
+ */
 typedef herr_t (*H5A_operator1_t)(hid_t location_id /*in*/, const char *attr_name /*in*/,
                                   void *operator_data /*in,out*/);
+//! <!-- [H5A_operator1_t_snip] -->
 
 /* Function prototypes */
 /* --------------------------------------------------------------------------*/
@@ -1163,8 +1241,6 @@ H5_DLL int H5Aget_num_attrs(hid_t loc_id);
  *
  * \brief Calls a user’s function for each attribute on an object
  *
- * \todo make prototype parameter match function (idx vs attr_num)
- *
  * \loc_id
  * \param[in,out] idx     Starting (in) and ending (out) attribute index
  * \param[in]     op      User's function to pass each attribute to
@@ -1186,29 +1262,12 @@ H5_DLL int H5Aget_num_attrs(hid_t loc_id);
  *          \p op, is returned in \p idx. If \p idx is the null pointer,
  *          then all attributes are processed.
  *
- *          The prototype for #H5A_operator1_t is a user defined function
- *          where:
- *          The operation receives the identifier for the group, dataset
- *          or named datatype being iterated over, \p loc_id, the name of
- *          the current object attribute, \p attr_name, and the pointer to
- *          the operator data passed in to H5Aiterate1(), \p op_data.
- *
- *          The return values from an operator are:
- *
- *          \li Zero causes the iterator to continue, returning zero when
- *              all attributes have been processed.
- *          \li Positive causes the iterator to immediately return that
- *              positive value, indicating short-circuit success. The
- *              iterator can be restarted at the next attribute.
- *          \li Negative causes the iterator to immediately return that value,
- *              indicating failure. The iterator can be restarted at the next
- *              attribute.
- *
- * \todo Add snippet to show H5A_operator1_t.
+ *          \p op is a user-defined function whose prototype is defined as follows:
+ *          \snippet this H5A_operator1_t_snip
+ *          \click4more
  *
  * \version 1.8.0 The function \p H5Aiterate was renamed to H5Aiterate1()
  *                and deprecated in this release.
- *
  * \since 1.0.0
  *
  */