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, 157 insertions, 10 deletions

diff --git a/src/H5ESpublic.h b/src/H5ESpublic.h
index 752218b..a7c2e58 100644
--- a/src/H5ESpublic.h
+++ b/src/H5ESpublic.h
@@ -47,20 +47,24 @@ typedef enum H5ES_status_t {
     H5ES_STATUS_FAIL         /* An operation has completed, but failed                   */
 } H5ES_status_t;
 
-/* Information about failed operations in event set */
+//! <!-- [H5ES_err_info_t_snip] -->
+/**
+ * Information about failed operations in event set
+ */
 typedef struct H5ES_err_info_t {
     /* Operation info */
-    char *   api_name;      /* Name of HDF5 API routine called */
-    char *   api_args;      /* "Argument string" for arguments to HDF5 API routine called */
-    char *   app_file_name; /* Name of source file where the HDF5 API routine was called */
-    char *   app_func_name; /* Name of function where the HDF5 API routine was called */
-    unsigned app_line_num;  /* Line # of source file where the HDF5 API routine was called */
-    uint64_t op_ins_count;  /* Counter of operation's insertion into event set */
-    uint64_t op_ins_ts;     /* Timestamp for when the operation was inserted into the event set */
+    char *   api_name;      /**< Name of HDF5 API routine called */
+    char *   api_args;      /**< "Argument string" for arguments to HDF5 API routine called */
+    char *   app_file_name; /**< Name of source file where the HDF5 API routine was called */
+    char *   app_func_name; /**< Name of function where the HDF5 API routine was called */
+    unsigned app_line_num;  /**< Line # of source file where the HDF5 API routine was called */
+    uint64_t op_ins_count;  /**< Counter of operation's insertion into event set */
+    uint64_t op_ins_ts;     /**< Timestamp for when the operation was inserted into the event set */
 
     /* Error info */
-    hid_t err_stack_id; /* ID for error stack from failed operation */
+    hid_t err_stack_id; /**< ID for error stack from failed operation */
 } H5ES_err_info_t;
+//! <!-- [H5ES_err_info_t_snip] -->
 
 /*
 H5ES_op_info_t:
@@ -119,14 +123,157 @@ How to Trace Async Operations?
 extern "C" {
 #endif
 
-H5_DLL hid_t  H5EScreate(void);
+/**
+ * \ingroup H5ES
+ *
+ * \brief Creates an event set
+ *
+ * \returns \hid_ti{event set}
+ *
+ * \details H5EScreate() creates a new event set and returns a corresponding
+ *          event set identifier.
+ *
+ * \since 1.13.0
+ *
+ */
+H5_DLL hid_t H5EScreate(void);
+
+/**
+ * \ingroup H5ES
+ *
+ * \brief Waits for operations in event set to complete
+ *
+ * \es_id
+ * \param[in] timeout Total time in nanoseconds to wait for all operations in
+ *            the event set to complete
+ * \param[out] num_in_progress The number of operations still in progress
+ * \param[out] err_occurred Flag if an operation in the event set failed
+ * \returns \herr_t
+ *
+ * \details H5ESwait() waits for operations in an event set \p es_id to wait
+ *          with \p timeout.
+ *
+ *          Timeout value is in nanoseconds, and is for the H5ESwait() call and
+ *          not for each individual operation in the event set. For example, if
+ *          "10" is passed as a timeout value and the event set waited 4
+ *          nanoseconds for the first operation to complete, the remaining
+ *          operations would be allowed to wait for at most 6 nanoseconds more,
+ *          i.e., the timeout value used across all operations in the event set
+ *          until it reaches 0, then any remaining operations are only checked
+ *          for completion, not waited on.
+ *
+ *          This call will stop waiting on operations and will return
+ *          immediately if an operation fails. If a failure occurs, the value
+ *          returned for the number of operations in progress may be inaccurate.
+ *
+ * \since 1.13.0
+ *
+ */
 H5_DLL herr_t H5ESwait(hid_t es_id, uint64_t timeout, size_t *num_in_progress, hbool_t *err_occurred);
+
+/**
+ * \ingroup H5ES
+ *
+ * \brief Retrieves number of events in an event set
+ *
+ * \es_id
+ * \param[out] count The number of events in the event set
+ * \returns \herr_t
+ *
+ * \details H5ESget_count() retrieves number of events in an event set specified
+ *          by \p es_id.
+ *
+ * \since 1.13.0
+ *
+ */
 H5_DLL herr_t H5ESget_count(hid_t es_id, size_t *count);
+
+/**
+ * \ingroup H5ES
+ *
+ * \todo Fill in the blanks!
+ *
+ * \since 1.13.0
+ *
+ */
 H5_DLL herr_t H5ESget_op_counter(hid_t es_id, uint64_t *counter);
+
+/**
+ * \ingroup H5ES
+ *
+ * \brief Checks for failed operations
+ *
+ * \es_id
+ * \param[out] err_occurred Status indicating if error is present in the event
+ *             set
+ * \returns \herr_t
+ *
+ * \details H5ESget_err_status() checks if event set specified by es_id has
+ *          failed operations.
+ *
+ * \since 1.13.0
+ *
+ */
 H5_DLL herr_t H5ESget_err_status(hid_t es_id, hbool_t *err_occurred);
+
+/**
+ * \ingroup H5ES
+ *
+ * \brief Retrieves the number of failed operations
+ *
+ * \es_id
+ * \param[out] num_errs Number of errors
+ * \returns \herr_t
+ *
+ * \details H5ESget_err_count() retrieves the number of failed operations in an
+ *          event set specified by \p es_id.
+ *
+ *          The function does not wait for active operations to complete, so
+ *          count may not include all failures.
+ *
+ * \since 1.13.0
+ *
+ */
 H5_DLL herr_t H5ESget_err_count(hid_t es_id, size_t *num_errs);
+
+/**
+ * \ingroup H5ES
+ *
+ * \brief Retrieves information about failed operations
+ *
+ * \es_id
+ * \param[in] num_err_info The number of elements in \p err_info array
+ * \param[out] err_info Array of structures
+ * \param[out] err_cleared Number of cleared errors
+ * \returns \herr_t
+ *
+ * \details H5ESget_err_info() retrieves information about failed operations in
+ *          an event set specified by \p es_id.  The strings retrieved for each
+ *          error info must be released by calling H5free_memory().
+ *
+ *          Below is the description of the \ref H5ES_err_info_t structure:
+ *          \snippet this H5ES_err_info_t_snip
+ *          \click4more
+ *
+ * \since 1.13.0
+ *
+ */
 H5_DLL herr_t H5ESget_err_info(hid_t es_id, size_t num_err_info, H5ES_err_info_t err_info[],
                                size_t *err_cleared);
+
+/**
+ * \ingroup H5ES
+ *
+ * \brief Terminates access to an event set
+ *
+ * \es_id
+ * \returns \herr_t
+ *
+ * \details H5ESclose() terminates access to an event set specified by \p es_id.
+ *
+ * \since 1.13.0
+ *
+ */
 H5_DLL herr_t H5ESclose(hid_t es_id);
 
 #ifdef __cplusplus