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, 136 insertions, 91 deletions

diff --git a/src/H5Opublic.h b/src/H5Opublic.h
index 04ef35b..7bc7784 100644
--- a/src/H5Opublic.h
+++ b/src/H5Opublic.h
@@ -86,17 +86,15 @@
 #define H5O_INFO_NUM_ATTRS 0x0004u /* Fill in the num_attrs field */
 #define H5O_INFO_ALL       (H5O_INFO_BASIC | H5O_INFO_TIME | H5O_INFO_NUM_ATTRS)
 
-/* Flags for H5Oget_native_info.
- * Theses flags determine which fields will be filled in in the H5O_native_info_t
- * struct.
+//! <!-- [H5O_native_info_fields_snip] -->
+/**
+ * Flags for H5Oget_native_info().  Theses flags determine which fields will be
+ * filled in in the \ref H5O_native_info_t struct.
  */
-//! [H5O_native_info_fields_snip]
-
 #define H5O_NATIVE_INFO_HDR       0x0008u /* Fill in the hdr field */
 #define H5O_NATIVE_INFO_META_SIZE 0x0010u /* Fill in the meta_size field */
 #define H5O_NATIVE_INFO_ALL       (H5O_NATIVE_INFO_HDR | H5O_NATIVE_INFO_META_SIZE)
-
-//! [H5O_native_info_fields_snip]
+//! <!-- [H5O_native_info_fields_snip] -->
 
 /* Convenience macro to check if the token is the 'undefined' token value */
 #define H5O_IS_TOKEN_UNDEF(token) (!HDmemcmp(&(token), &(H5O_TOKEN_UNDEF), sizeof(H5O_token_t)))
@@ -105,46 +103,48 @@
 /* Public Typedefs */
 /*******************/
 
-//! [H5O_type_t_snip]
-
-/* Types of objects in file */
+//! <!-- [H5O_type_t_snip] -->
+/**
+ * Types of objects in file
+ */
 typedef enum H5O_type_t {
-    H5O_TYPE_UNKNOWN = -1,   /* Unknown object type        */
-    H5O_TYPE_GROUP,          /* Object is a group          */
-    H5O_TYPE_DATASET,        /* Object is a dataset        */
-    H5O_TYPE_NAMED_DATATYPE, /* Object is a named data type    */
-    H5O_TYPE_MAP,            /* Object is a map */
-    H5O_TYPE_NTYPES          /* Number of different object types (must be last!) */
+    H5O_TYPE_UNKNOWN = -1,   /**< Unknown object type        */
+    H5O_TYPE_GROUP,          /**< Object is a group          */
+    H5O_TYPE_DATASET,        /**< Object is a dataset        */
+    H5O_TYPE_NAMED_DATATYPE, /**< Object is a named data type    */
+    H5O_TYPE_MAP,            /**< Object is a map */
+    H5O_TYPE_NTYPES          /**< Number of different object types (must be last!) */
 } H5O_type_t;
+//! <!-- [H5O_type_t_snip] -->
 
-//! [H5O_type_t_snip]
-
-/* Information struct for object header metadata (for H5Oget_info/H5Oget_info_by_name/H5Oget_info_by_idx) */
-//! [H5O_hdr_info_t_snip]
-
+//! <!-- [H5O_hdr_info_t_snip] -->
+/**
+ * Information struct for object header metadata (for
+ * H5Oget_info(), H5Oget_info_by_name(), H5Oget_info_by_idx())
+ */
 typedef struct H5O_hdr_info_t {
-    unsigned version; /* Version number of header format in file */
-    unsigned nmesgs;  /* Number of object header messages */
-    unsigned nchunks; /* Number of object header chunks */
-    unsigned flags;   /* Object header status flags */
+    unsigned version; /**< Version number of header format in file */
+    unsigned nmesgs;  /**< Number of object header messages */
+    unsigned nchunks; /**< Number of object header chunks */
+    unsigned flags;   /**< Object header status flags */
     struct {
-        hsize_t total; /* Total space for storing object header in file */
-        hsize_t meta;  /* Space within header for object header metadata information */
-        hsize_t mesg;  /* Space within header for actual message information */
-        hsize_t free;  /* Free space within object header */
+        hsize_t total; /**< Total space for storing object header in file */
+        hsize_t meta;  /**< Space within header for object header metadata information */
+        hsize_t mesg;  /**< Space within header for actual message information */
+        hsize_t free;  /**< Free space within object header */
     } space;
     struct {
-        uint64_t present; /* Flags to indicate presence of message type in header */
-        uint64_t shared;  /* Flags to indicate message type is shared in header */
+        uint64_t present; /**< Flags to indicate presence of message type in header */
+        uint64_t shared;  /**< Flags to indicate message type is shared in header */
     } mesg;
 } H5O_hdr_info_t;
+//! <!-- [H5O_hdr_info_t_snip] -->
 
-//! [H5O_hdr_info_t_snip]
-
-//! [H5O_info2_t_snip]
-
-/* Data model information struct for objects */
-/* (For H5Oget_info / H5Oget_info_by_name / H5Oget_info_by_idx version 3) */
+//! <!-- [H5O_info2_t_snip] -->
+/**
+ * Data model information struct for objects
+ * (For H5Oget_info(), H5Oget_info_by_name(), H5Oget_info_by_idx() version 3)
+ */
 typedef struct H5O_info2_t {
     unsigned long fileno;    /* File number that object is located in */
     H5O_token_t   token;     /* Token representing the object        */
@@ -156,44 +156,52 @@ typedef struct H5O_info2_t {
     time_t        btime;     /* Birth time                           */
     hsize_t       num_attrs; /* # of attributes attached to object   */
 } H5O_info2_t;
+//! <!-- [H5O_info2_t_snip] -->
 
-//! [H5O_info2_t_snip]
-
-//! [H5O_native_info_t_snip]
-
-/* Native file format information struct for objects */
-/* (For H5Oget_native_info / H5Oget_native_info_by_name / H5Oget_native_info_by_idx) */
+//! <!-- [H5O_native_info_t_snip] -->
+/**
+ * Native file format information struct for objects.
+ * (For H5Oget_native_info(), H5Oget_native_info_by_name(), H5Oget_native_info_by_idx())
+ */
 typedef struct H5O_native_info_t {
-    H5O_hdr_info_t hdr; /* Object header information */
+    H5O_hdr_info_t hdr; /**< Object header information */
     /* Extra metadata storage for obj & attributes */
     struct {
-        H5_ih_info_t obj;  /* v1/v2 B-tree & local/fractal heap for groups, B-tree for chunked datasets */
-        H5_ih_info_t attr; /* v2 B-tree & heap for attributes */
+        H5_ih_info_t obj;  /**< v1/v2 B-tree & local/fractal heap for groups, B-tree for chunked datasets */
+        H5_ih_info_t attr; /**< v2 B-tree & heap for attributes */
     } meta_size;
 } H5O_native_info_t;
+//! <!-- [H5O_native_info_t_snip] -->
 
-//! [H5O_native_info_t_snip]
-
-/* Typedef for message creation indexes */
+/**
+ * Typedef for message creation indexes
+ */
 typedef uint32_t H5O_msg_crt_idx_t;
 
-/* Prototype for H5Ovisit/H5Ovisit_by_name() operator (version 3) */
-//! [H5O_iterate2_t_snip]
-
+//! <!-- [H5O_iterate2_t_snip] -->
+/**
+ * Prototype for H5Ovisit(), H5Ovisit_by_name() operator (version 3)
+ */
 typedef herr_t (*H5O_iterate2_t)(hid_t obj, const char *name, const H5O_info2_t *info, void *op_data);
+//! <!-- [H5O_iterate2_t_snip] -->
 
-//! [H5O_iterate2_t_snip]
-
+//! <!-- [H5O_mcdt_search_ret_t_snip] -->
 typedef enum H5O_mcdt_search_ret_t {
-    H5O_MCDT_SEARCH_ERROR = -1, /* Abort H5Ocopy */
-    H5O_MCDT_SEARCH_CONT, /* Continue the global search of all committed datatypes in the destination file */
-    H5O_MCDT_SEARCH_STOP  /* Stop the search, but continue copying.  The committed datatype will be copied but
-                             not merged. */
+    H5O_MCDT_SEARCH_ERROR = -1, /**< Abort H5Ocopy */
+    H5O_MCDT_SEARCH_CONT, /**< Continue the global search of all committed datatypes in the destination file
+                           */
+    H5O_MCDT_SEARCH_STOP  /**< Stop the search, but continue copying.  The committed datatype will be copied
+                             but not merged. */
 } H5O_mcdt_search_ret_t;
+//! <!-- [H5O_mcdt_search_ret_t_snip] -->
 
-/* Callback to invoke when completing the search for a matching committed datatype from the committed dtype
- * list */
+//! <!-- [H5O_mcdt_search_cb_t_snip] -->
+/**
+ * Callback to invoke when completing the search for a matching committed
+ * datatype from the committed dtype list
+ */
 typedef H5O_mcdt_search_ret_t (*H5O_mcdt_search_cb_t)(void *op_data);
+//! <!-- [H5O_mcdt_search_cb_t_snip] -->
 
 /********************/
 /* Public Variables */
@@ -249,6 +257,11 @@ extern "C" {
  *
  */
 H5_DLL hid_t H5Oopen(hid_t loc_id, const char *name, hid_t lapl_id);
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup ASYNC
+ * \async_variant_of{H5Oopen}
+ */
 H5_DLL hid_t H5Oopen_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);
 
@@ -332,6 +345,11 @@ H5_DLL hid_t H5Oopen_by_token(hid_t loc_id, H5O_token_t token);
  */
 H5_DLL hid_t H5Oopen_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{H5Oopen_by_idx}
+ */
 H5_DLL hid_t H5Oopen_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);
@@ -553,6 +571,11 @@ H5_DLL herr_t H5Oget_info3(hid_t loc_id, H5O_info2_t *oinfo, unsigned fields);
  */
 H5_DLL herr_t H5Oget_info_by_name3(hid_t loc_id, const char *name, H5O_info2_t *oinfo, unsigned fields,
                                    hid_t lapl_id);
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup ASYNC
+ * \async_variant_of{H5Oget_info_by_name}
+ */
 H5_DLL herr_t H5Oget_info_by_name_async(const char *app_file, const char *app_func, unsigned app_line,
                                         hid_t loc_id, const char *name, H5O_info2_t *oinfo /*out*/,
                                         unsigned fields, hid_t lapl_id, hid_t es_id);
@@ -968,7 +991,6 @@ H5_DLL herr_t H5Odecr_refcount(hid_t object_id);
  *          - H5Pset_copy_object()
  *          - H5Pset_create_intermediate_group()
  *          - H5Pset_mcdt_search_cb()
- *          .
  *      - Copying Committed Datatypes with #H5Ocopy - A comprehensive
  *        discussion of copying committed datatypes (PDF) in
  *        Advanced Topics in HDF5
@@ -980,6 +1002,11 @@ H5_DLL herr_t H5Odecr_refcount(hid_t object_id);
  */
 H5_DLL herr_t H5Ocopy(hid_t src_loc_id, const char *src_name, hid_t dst_loc_id, const char *dst_name,
                       hid_t ocpypl_id, hid_t lcpl_id);
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup ASYNC
+ * \async_variant_of{H5Ocopy}
+ */
 H5_DLL herr_t H5Ocopy_async(const char *app_file, const char *app_func, unsigned app_line, hid_t src_loc_id,
                             const char *src_name, hid_t dst_loc_id, const char *dst_name, hid_t ocpypl_id,
                             hid_t lcpl_id, hid_t es_id);
@@ -1522,6 +1549,11 @@ H5_DLL herr_t H5Ovisit_by_name3(hid_t loc_id, const char *obj_name, H5_index_t i
  *
  */
 H5_DLL herr_t H5Oclose(hid_t object_id);
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup ASYNC
+ * \async_variant_of{H5Oclose}
+ */
 H5_DLL herr_t H5Oclose_async(const char *app_file, const char *app_func, unsigned app_line, hid_t object_id,
                              hid_t es_id);
 
@@ -1572,6 +1604,11 @@ H5_DLL herr_t H5Oclose_async(const char *app_file, const char *app_func, unsigne
  *
  */
 H5_DLL herr_t H5Oflush(hid_t obj_id);
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup ASYNC
+ * \async_variant_of{H5Oflush}
+ */
 H5_DLL herr_t H5Oflush_async(const char *app_file, const char *app_func, unsigned app_line, hid_t obj_id,
                              hid_t es_id);
 /**
@@ -1599,6 +1636,11 @@ H5_DLL herr_t H5Oflush_async(const char *app_file, const char *app_func, unsigne
  *
  */
 H5_DLL herr_t H5Orefresh(hid_t oid);
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup ASYNC
+ * \async_variant_of{H5Orefresh}
+ */
 H5_DLL herr_t H5Orefresh_async(const char *app_file, const char *app_func, unsigned app_line, hid_t oid,
                                hid_t es_id);
 
@@ -1873,46 +1915,49 @@ H5_DLLVAR const H5O_token_t H5O_TOKEN_UNDEF_g;
 
 /* Typedefs */
 
-/* A struct that's part of the H5G_stat_t structure (deprecated) */
-//! [H5O_stat_t_snip]
+//! <!-- [H5O_stat_t_snip] -->
+/**
+ * A struct that's part of the \ref H5G_stat_t structure
+ * \deprecated
+ */
 typedef struct H5O_stat_t {
-    hsize_t  size;    /* Total size of object header in file */
-    hsize_t  free;    /* Free space within object header */
-    unsigned nmesgs;  /* Number of object header messages */
-    unsigned nchunks; /* Number of object header chunks */
+    hsize_t  size;    /**< Total size of object header in file */
+    hsize_t  free;    /**< Free space within object header */
+    unsigned nmesgs;  /**< Number of object header messages */
+    unsigned nchunks; /**< Number of object header chunks */
 } H5O_stat_t;
-//! [H5O_stat_t_snip]
-
-//! [H5O_info1_t_snip]
+//! <!-- [H5O_stat_t_snip] -->
 
-/* Information struct for object */
-/* (For H5Oget_info/H5Oget_info_by_name/H5Oget_info_by_idx versions 1 & 2) */
+//! <!-- [H5O_info1_t_snip] -->
+/**
+ * Information struct for object (For H5Oget_info(), H5Oget_info_by_name(),
+ * H5Oget_info_by_idx() versions 1 & 2.)
+ */
 typedef struct H5O_info1_t {
-    unsigned long  fileno;    /* File number that object is located in */
-    haddr_t        addr;      /* Object address in file                */
-    H5O_type_t     type;      /* Basic object type (group, dataset, etc.) */
-    unsigned       rc;        /* Reference count of object    */
-    time_t         atime;     /* Access time                  */
-    time_t         mtime;     /* Modification time            */
-    time_t         ctime;     /* Change time                  */
-    time_t         btime;     /* Birth time                   */
-    hsize_t        num_attrs; /* # of attributes attached to object */
-    H5O_hdr_info_t hdr;       /* Object header information */
+    unsigned long  fileno;    /**< File number that object is located in */
+    haddr_t        addr;      /**< Object address in file                */
+    H5O_type_t     type;      /**< Basic object type (group, dataset, etc.) */
+    unsigned       rc;        /**< Reference count of object    */
+    time_t         atime;     /**< Access time                  */
+    time_t         mtime;     /**< Modification time            */
+    time_t         ctime;     /**< Change time                  */
+    time_t         btime;     /**< Birth time                   */
+    hsize_t        num_attrs; /**< # of attributes attached to object */
+    H5O_hdr_info_t hdr;       /**< Object header information */
     /* Extra metadata storage for obj & attributes */
     struct {
-        H5_ih_info_t obj;  /* v1/v2 B-tree & local/fractal heap for groups, B-tree for chunked datasets */
-        H5_ih_info_t attr; /* v2 B-tree & heap for attributes */
+        H5_ih_info_t obj;  /**< v1/v2 B-tree & local/fractal heap for groups, B-tree for chunked datasets */
+        H5_ih_info_t attr; /**< v2 B-tree & heap for attributes */
     } meta_size;
 } H5O_info1_t;
+//! <!-- [H5O_info1_t_snip] -->
 
-//! [H5O_info1_t_snip]
-
-/* Prototype for H5Ovisit/H5Ovisit_by_name() operator (versions 1 & 2) */
-//! [H5O_iterate1_t_snip]
-
+//! <!-- [H5O_iterate1_t_snip] -->
+/**
+ * Prototype for H5Ovisit(), H5Ovisit_by_name() operator (versions 1 & 2)
+ */
 typedef herr_t (*H5O_iterate1_t)(hid_t obj, const char *name, const H5O_info1_t *info, void *op_data);
-
-//! [H5O_iterate1_t_snip]
+//! <!-- [H5O_iterate1_t_snip] -->
 
 /* Function prototypes */