develop Merge doxygen from 1.12 branch (#2095)

1 files changed, 87 insertions, 1 deletions

diff --git a/src/H5ESmodule.h b/src/H5ESmodule.h
index 205089a..b05b7f4 100644
--- a/src/H5ESmodule.h
+++ b/src/H5ESmodule.h
@@ -28,7 +28,93 @@
 #define H5_MY_PKG     H5ES
 #define H5_MY_PKG_ERR H5E_EVENTSET
 
-/**\defgroup H5ES H5ES
+/** \page H5ES_UG The HDF5 Event Set
+ * @todo Under Construction
+ *
+ * \section sec_async The HDF5 Event Set Interface
+ *
+ * \section subsec_async_intro Introduction
+ * HDF5 provides asynchronous APIs for the HDF5 VOL connectors that support asynchronous HDF5
+ * operations using the HDF5 Event Set (H5ES) API. This allows I/O to proceed in the background
+ * while the application is performing other tasks.
+ *
+ * To support AIO capabilities for the HDF5 VOL connectors, the AIO versions for the functions
+ * listed in the table below were added to HDF5 library version 1.13.0 and later. The async version
+ * of the function has “_async” suffix added to the function name. For example, the async version
+ * for H5Fcreate is H5Fcreate_async.
+ *
+ * <table>
+ * <tr>
+ * <th>Interface</th>
+ * <th>Functions</th>
+ * </tr>
+ * <tr>
+ * <th>H5F</th>
+ * <td>#H5Fcreate, #H5Fflush, #H5Fis_accessible, #H5Fopen, #H5Fclose
+ * </td>
+ * </tr>
+ * <tr>
+ * <th>H5G</th>
+ * <td>#H5Gcreate, #H5Gget_info, #H5Gget_info_by_idx, #H5Gget_info_by_name, #H5Gclose
+ * </td>
+ * </tr>
+ * <tr>
+ * <th>H5D</th>
+ * <td>#H5Dcreate, #H5Dopen, #H5Dset_extent, #H5Dwrite, #H5Dread, #H5Dget_space, #H5Dclose
+ * </td>
+ * </tr>
+ * <tr>
+ * <th>H5A</th>
+ * <td>#H5Acreate, #H5Acreate_by_name, #H5Aopen, #H5Aopen_by_name, #H5Aexists, #H5Awrite, #H5Aread,
+#H5Aclose, #H5Aopen_by_idx, #H5Arename, #H5Arename_by_name
+ * </td>
+ * </tr>
+ * <tr>
+ * <th>H5L</th>
+ * <td>#H5Lcreate_hard, #H5Lcreate_soft, #H5Ldelete, #H5Ldelete_by_idx, #H5Lexists
+ * </td>
+ * </tr>
+ * <tr>
+ * <th>H5O</th>
+ * <td>#H5Ocopy, #H5Orefresh, #H5Oflush, #H5Oclose, #H5Oopen, #H5Oopen_by_idx
+ * </td>
+ * </tr>
+ * <tr>
+ * <th>H5R</th>
+ * <td>#H5Ropen_attr, #H5Ropen_object #H5Ropen_region, #H5Rdereference
+ * </td>
+ * </tr>
+ * <tr>
+ * <th>H5M</th>
+ * <td>#H5Mcreate, #H5Mopen, #H5Mput, #H5Mget, #H5Mclose
+ * </td>
+ * </tr>
+ * <tr>
+ * <th>H5T</th>
+ * <td>#H5Tcommit, #H5Topen, #H5Tcopy, #H5Tclose
+ * </td>
+ * </tr>
+ * </table>
+ *
+ * Async versions of the functions have an extra parameter called the event set parameter or es_id.
+ * For example, compare the signatures of #H5Dclose and #H5Dclose_async:
+ * \code
+ * herr_t H5Dclose(hid_t dset_id);
+ * herr_t H5Dclose_async(hid_t dset_id, hid_t es_id);
+ * \endcode
+ *
+ * An event set is an in-memory object that is created by an application and used to track many
+ * asynchronous operations with a single object. They function like a "bag" -- holding request
+ * tokens from one or more asynchronous operations and provide a simple interface for inspecting
+ * the status of the entire set of operations.
+ *
+ * See the \ref H5ES APIs that were added to the HDF5 library to manage event sets.
+ *
+ * Previous Chapter \ref sec_vol - Next Chapter \ref sec_map
+ *
+ */
+
+/**\defgroup H5ES Event Set Interface (H5ES)
  *
  * \todo Add the event set life cycle.
  *