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, 43 insertions, 33 deletions

diff --git a/src/H5Lpublic.h b/src/H5Lpublic.h
index d5ec346..4b5e9e4 100644
--- a/src/H5Lpublic.h
+++ b/src/H5Lpublic.h
@@ -92,7 +92,7 @@ typedef enum {
 /**
  * \brief Information struct for links
  */
-//! [H5L_info2_t_snip]
+//! <!-- [H5L_info2_t_snip] -->
 typedef struct {
     H5L_type_t type;         /**< Type of link                   */
     hbool_t    corder_valid; /**< Indicate if creation order is valid */
@@ -103,7 +103,7 @@ typedef struct {
         size_t      val_size; /**< Size of a soft link or user-defined link value */
     } u;
 } H5L_info2_t;
-//! [H5L_info2_t_snip]
+//! <!-- [H5L_info2_t_snip] -->
 
 /* The H5L_class_t struct can be used to override the behavior of a
  * "user-defined" link class. Users should populate the struct with callback
@@ -150,7 +150,7 @@ typedef ssize_t (*H5L_query_func_t)(const char *link_name, const void *lnkdata,
  * "user-defined" link class. Users should populate the struct with callback
  * functions defined elsewhere.
  */
-//! [H5L_class_t_snip]
+//! <!-- [H5L_class_t_snip] -->
 typedef struct {
     int                 version;     /**< Version number of this struct       */
     H5L_type_t          id;          /**< Link type ID                        */
@@ -162,16 +162,16 @@ typedef struct {
     H5L_delete_func_t   del_func;    /**< Callback for link deletion          */
     H5L_query_func_t    query_func;  /**< Callback for queries                */
 } H5L_class_t;
-//! [H5L_class_t_snip]
+//! <!-- [H5L_class_t_snip] -->
 
 /**
  * \brief Prototype for H5Literate2(), H5Literate_by_name2() operator
  *
  * The H5O_token_t version is used in the VOL layer and future public API calls.
  */
-//! [H5L_iterate2_t_snip]
+//! <!-- [H5L_iterate2_t_snip] -->
 typedef herr_t (*H5L_iterate2_t)(hid_t group, const char *name, const H5L_info2_t *info, void *op_data);
-//! [H5L_iterate2_t_snip]
+//! <!-- [H5L_iterate2_t_snip] -->
 
 /**
  * \brief Callback for external link traversal
@@ -201,8 +201,6 @@ typedef herr_t (*H5L_elink_traverse_t)(const char *parent_file_name, const char
  *
  * \return \herr_t
  *
- * \todo We need to get the location ID story straight!
- *
  * \details H5Lmove() moves a link within an HDF5 file. The original link,
  *          \p src_name, is removed from \p src_loc and the new link,
  *          \p dst_name, is inserted at dst_loc. This change is
@@ -321,8 +319,6 @@ H5_DLL herr_t H5Lcopy(hid_t src_loc, const char *src_name, hid_t dst_loc, const
  *
  * \return \herr_t
  *
- * \todo We need to get the location ID story straight!
- *
  * \details H5Lcreate_hard() creates a new hard link to a pre-existing object
  *          in an HDF5 file.
  *
@@ -357,6 +353,11 @@ H5_DLL herr_t H5Lcopy(hid_t src_loc, const char *src_name, hid_t dst_loc, const
  */
 H5_DLL herr_t H5Lcreate_hard(hid_t cur_loc, const char *cur_name, hid_t dst_loc, const char *dst_name,
                              hid_t lcpl_id, hid_t lapl_id);
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup ASYNC
+ * \async_variant_of{H5Lcreate_hard}
+ */
 H5_DLL herr_t H5Lcreate_hard_async(const char *app_file, const char *app_func, unsigned app_line,
                                    hid_t cur_loc_id, const char *cur_name, hid_t new_loc_id,
                                    const char *new_name, hid_t lcpl_id, hid_t lapl_id, hid_t es_id);
@@ -373,8 +374,6 @@ H5_DLL herr_t H5Lcreate_hard_async(const char *app_file, const char *app_func, u
  *
  * \return \herr_t
  *
- * \todo We need to get the location ID story straight!
- *
  * \details H5Lcreate_soft() creates a new soft link to an object in an HDF5
  *          file.
  *
@@ -426,6 +425,11 @@ H5_DLL herr_t H5Lcreate_hard_async(const char *app_file, const char *app_func, u
  */
 H5_DLL herr_t H5Lcreate_soft(const char *link_target, hid_t link_loc_id, const char *link_name, hid_t lcpl_id,
                              hid_t lapl_id);
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup ASYNC
+ * \async_variant_of{H5Lcreate_soft}
+ */
 H5_DLL herr_t H5Lcreate_soft_async(const char *app_file, const char *app_func, unsigned app_line,
                                    const char *link_target, hid_t link_loc_id, const char *link_name,
                                    hid_t lcpl_id, hid_t lapl_id, hid_t es_id);
@@ -440,8 +444,6 @@ H5_DLL herr_t H5Lcreate_soft_async(const char *app_file, const char *app_func, u
  *
  * \return \herr_t
  *
- * \todo We need to get the location ID story straight!
- *
  * \details H5Ldelete() removes the link specified by \p name from the location
  *          \p loc_id.
  *
@@ -468,6 +470,11 @@ H5_DLL herr_t H5Lcreate_soft_async(const char *app_file, const char *app_func, u
  *
  */
 H5_DLL herr_t H5Ldelete(hid_t loc_id, const char *name, hid_t lapl_id);
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup ASYNC
+ * \async_variant_of{H5Ldelete}
+ */
 H5_DLL herr_t H5Ldelete_async(const char *app_file, const char *app_func, unsigned app_line, hid_t loc_id,
                               const char *name, hid_t lapl_id, hid_t es_id);
 /**
@@ -484,8 +491,6 @@ H5_DLL herr_t H5Ldelete_async(const char *app_file, const char *app_func, unsign
  *
  * \return \herr_t
  *
- * \todo We need to get the location ID story straight!
- *
  * \details H5Ldelete_by_idx() removes the \Emph{n}-th link in a group
  *          according to the specified order, \p order, in the specified index,
  *          \p index.
@@ -500,6 +505,11 @@ H5_DLL herr_t H5Ldelete_async(const char *app_file, const char *app_func, unsign
  */
 H5_DLL herr_t H5Ldelete_by_idx(hid_t loc_id, const char *group_name, H5_index_t idx_type,
                                H5_iter_order_t order, hsize_t n, hid_t lapl_id);
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup ASYNC
+ * \async_variant_of{H5Ldelete_by_idx}
+ */
 H5_DLL herr_t H5Ldelete_by_idx_async(const char *app_file, const char *app_func, unsigned app_line,
                                      hid_t loc_id, const char *group_name, H5_index_t idx_type,
                                      H5_iter_order_t order, hsize_t n, hid_t lapl_id, hid_t es_id);
@@ -516,8 +526,6 @@ H5_DLL herr_t H5Ldelete_by_idx_async(const char *app_file, const char *app_func,
  *
  * \return \herr_t
  *
- * \todo We need to get the location ID story straight!
- *
  * \details H5Lget_val() returns tha value of link \p name. For smbolic links,
  *          this is the path to which the link points, including the null
  *          terminator. For external and user-defined links, it is the link
@@ -575,8 +583,6 @@ H5_DLL herr_t H5Lget_val(hid_t loc_id, const char *name, void *buf /*out*/, size
  *
  * \return \herr_t
  *
- * \todo We need to get the location ID story straight!
- *
  * \details H5Lget_val_by_idx() retrieves the value of the \Emph{n}-th link in
  *          a group, according to the specified order, \p order, within an
  *          index, \p index.
@@ -630,8 +636,6 @@ H5_DLL herr_t H5Lget_val_by_idx(hid_t loc_id, const char *group_name, H5_index_t
  *
  * \return \herr_t
  *
- * \todo We need to get the location ID story straight!
- *
  * \details H5Lexists() allows an application to determine whether the link \p
  *          name exists in the location specified by \p loc_id. The link may be
  *          of any type; only the presence of a link with that name is checked.
@@ -707,6 +711,11 @@ H5_DLL herr_t H5Lget_val_by_idx(hid_t loc_id, const char *group_name, H5_index_t
  *
  */
 H5_DLL htri_t H5Lexists(hid_t loc_id, const char *name, hid_t lapl_id);
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup ASYNC
+ * \async_variant_of{H5Lexists}
+ */
 H5_DLL herr_t H5Lexists_async(const char *app_file, const char *app_func, unsigned app_line, hid_t loc_id,
                               const char *name, hbool_t *exists, hid_t lapl_id, hid_t es_id);
 /**
@@ -721,8 +730,6 @@ H5_DLL herr_t H5Lexists_async(const char *app_file, const char *app_func, unsign
  *
  * \return \herr_t
  *
- * \todo We need to get the location ID story straight!
- *
  * \details H5Lget_info2() returns information about the specified link through
  *          the \p linfo argument.
  *
@@ -830,8 +837,6 @@ H5_DLL herr_t H5Lget_info2(hid_t loc_id, const char *name, H5L_info2_t *linfo, h
  *
  * \see H5Lget_info2()
  *
- * \todo Document H5Lget_info_by_idx()
- *
  */
 H5_DLL herr_t H5Lget_info_by_idx2(hid_t loc_id, const char *group_name, H5_index_t idx_type,
                                   H5_iter_order_t order, hsize_t n, H5L_info2_t *linfo, hid_t lapl_id);
@@ -957,6 +962,11 @@ H5_DLL ssize_t H5Lget_name_by_idx(hid_t loc_id, const char *group_name, H5_index
  */
 H5_DLL herr_t H5Literate2(hid_t grp_id, H5_index_t idx_type, H5_iter_order_t order, hsize_t *idx,
                           H5L_iterate2_t op, void *op_data);
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup ASYNC
+ * \async_variant_of{H5Literate}
+ */
 H5_DLL herr_t H5Literate_async(const char *app_file, const char *app_func, unsigned app_line, hid_t group_id,
                                H5_index_t idx_type, H5_iter_order_t order, hsize_t *idx_p, H5L_iterate2_t op,
                                void *op_data, hid_t es_id);
@@ -1642,8 +1652,10 @@ H5_DLL herr_t H5Lcreate_external(const char *file_name, const char *obj_name, hi
 
 /* Typedefs */
 
-/* Information struct for link (for H5Lget_info1/H5Lget_info_by_idx1) */
-//! [H5L_info1_t_snip]
+//! <!-- [H5L_info1_t_snip] -->
+/**
+ * Information struct for link (for H5Lget_info1() and H5Lget_info_by_idx1())
+ */
 typedef struct {
     H5L_type_t type;         /**< Type of link                   */
     hbool_t    corder_valid; /**< Indicate if creation order is valid */
@@ -1654,7 +1666,7 @@ typedef struct {
         size_t  val_size; /**< Size of a soft link or UD link value */
     } u;
 } H5L_info1_t;
-//! [H5L_info1_t_snip]
+//! <!-- [H5L_info1_t_snip] -->
 
 /** Callback during link traversal */
 typedef hid_t (*H5L_traverse_0_func_t)(const char *link_name, hid_t cur_group, const void *lnkdata,
@@ -1674,9 +1686,9 @@ typedef struct {
 } H5L_class_0_t;
 
 /** Prototype for H5Literate1() / H5Literate_by_name1() operator */
-//! [H5L_iterate1_t_snip]
+//! <!-- [H5L_iterate1_t_snip] -->
 typedef herr_t (*H5L_iterate1_t)(hid_t group, const char *name, const H5L_info1_t *info, void *op_data);
-//! [H5L_iterate1_t_snip]
+//! <!-- [H5L_iterate1_t_snip] -->
 
 /* Function prototypes */
 /**
@@ -1694,8 +1706,6 @@ typedef herr_t (*H5L_iterate1_t)(hid_t group, const char *name, const H5L_info1_
  * \deprecated As of HDF5-1.12 this function has been deprecated in favor of
  *             the function H5Lget_info2() or the macro H5Lget_info().
  *
- * \todo We need to get the location ID story straight!
- *
  * \details H5Lget_info1() returns information about the specified link through
  *          the \p linfo argument.
  *