Brings Doxygen changes from develop (#2366)

10 files changed, 104 insertions, 51 deletions

diff --git a/src/H5Dpublic.h b/src/H5Dpublic.h
index f7d208d..fbce3d6 100644
--- a/src/H5Dpublic.h
+++ b/src/H5Dpublic.h
@@ -694,7 +694,7 @@ H5_DLL herr_t H5Dget_chunk_info_by_coord(hid_t dset_id, const hsize_t *offset, u
  * Iterate over all chunked datasets and chunks in a file.
  * \snippet H5D_examples.c H5Ovisit_cb
  *
- * \since 1.13.0
+ * \since 1.14.0
  *
  */
 H5_DLL herr_t H5Dchunk_iter(hid_t dset_id, hid_t dxpl_id, H5D_chunk_iter_op_t cb, void *op_data);
@@ -900,7 +900,7 @@ H5_DLL herr_t H5Dread(hid_t dset_id, hid_t mem_type_id, hid_t mem_space_id, hid_
  *          parallel, each rank must pass exactly the same list of datasets in
  *          \p dset_id , though the other parameters may differ.
  *
- * \since 1.13.3
+ * \since 1.14.0
  *
  * \see H5Dread()
  *
@@ -1091,7 +1091,7 @@ H5_DLL herr_t H5Dwrite(hid_t dset_id, hid_t mem_type_id, hid_t mem_space_id, hid
  *          parallel, each rank must pass exactly the same list of datasets in
  *          \p dset_id , though the other parameters may differ.
  *
- * \since 1.13.3
+ * \since 1.14.0
  *
  * \see H5Dwrite()
  *
diff --git a/src/H5ESmodule.h b/src/H5ESmodule.h
index b05b7f4..1e333f7 100644
--- a/src/H5ESmodule.h
+++ b/src/H5ESmodule.h
@@ -39,7 +39,7 @@
  * 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
+ * listed in the table below were added to HDF5 library version 1.14.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.
  *
diff --git a/src/H5ESpublic.h b/src/H5ESpublic.h
index ecfd08f..f2c7cb5 100644
--- a/src/H5ESpublic.h
+++ b/src/H5ESpublic.h
@@ -40,30 +40,34 @@
 /* Public Typedefs */
 /*******************/
 
-/* Asynchronous operation status */
+/**
+ * Asynchronous operation status
+ */
 typedef enum H5ES_status_t {
-    H5ES_STATUS_IN_PROGRESS, /* Operation(s) have not yet completed         */
-    H5ES_STATUS_SUCCEED,     /* Operation(s) have completed, successfully   */
-    H5ES_STATUS_CANCELED,    /* Operation(s) has been canceled              */
-    H5ES_STATUS_FAIL         /* An operation has completed, but failed      */
+    H5ES_STATUS_IN_PROGRESS, /**< Operation(s) have not yet completed         */
+    H5ES_STATUS_SUCCEED,     /**< Operation(s) have completed, successfully   */
+    H5ES_STATUS_CANCELED,    /**< Operation(s) has been canceled              */
+    H5ES_STATUS_FAIL         /**< An operation has completed, but failed      */
 } H5ES_status_t;
 
-/* Information about operations in an event set */
+/**
+ * Information about operations in an event set
+ */
 typedef struct H5ES_op_info_t {
     /* API call info */
-    const char *api_name; /* Name of HDF5 API routine called */
-    char       *api_args; /* "Argument string" for arguments to HDF5 API routine called */
+    const char *api_name; /**< Name of HDF5 API routine called */
+    char       *api_args; /**< "Argument string" for arguments to HDF5 API routine called */
 
     /* Application info */
-    const char *app_file_name; /* Name of source file where the HDF5 API routine was called */
-    const 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 */
+    const char *app_file_name; /**< Name of source file where the HDF5 API routine was called */
+    const 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 */
 
     /* Operation info */
-    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 */
-    uint64_t op_exec_ts;   /* Timestamp for when the operation began execution */
-    uint64_t op_exec_time; /* Execution time for operation (in ns) */
+    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 */
+    uint64_t op_exec_ts;   /**< Timestamp for when the operation began execution */
+    uint64_t op_exec_time; /**< Execution time for operation (in ns) */
 } H5ES_op_info_t;
 
 //! <!-- [H5ES_err_info_t_snip] -->
@@ -115,7 +119,14 @@ How to Trace Async Operations?
 
 */
 
+/**
+ * Callback for H5ESregister_insert_func()
+ */
 typedef int (*H5ES_event_insert_func_t)(const H5ES_op_info_t *op_info, void *ctx);
+
+/**
+ * Callback for H5ESregister_complete_func()
+ */
 typedef int (*H5ES_event_complete_func_t)(const H5ES_op_info_t *op_info, H5ES_status_t status,
                                           hid_t err_stack, void *ctx);
 
@@ -136,12 +147,12 @@ extern "C" {
  *
  * \brief Creates an event set
  *
- * \returns \hid_ti{event set}
+ * \returns \hid_t{event set}
  *
  * \details H5EScreate() creates a new event set and returns a corresponding
  *          event set identifier.
  *
- * \since 1.13.0
+ * \since 1.14.0
  *
  */
 H5_DLL hid_t H5EScreate(void);
@@ -174,7 +185,7 @@ H5_DLL hid_t H5EScreate(void);
  *          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
+ * \since 1.14.0
  *
  */
 H5_DLL herr_t H5ESwait(hid_t es_id, uint64_t timeout, size_t *num_in_progress, hbool_t *err_occurred);
@@ -192,7 +203,7 @@ H5_DLL herr_t H5ESwait(hid_t es_id, uint64_t timeout, size_t *num_in_progress, h
  * \details H5EScancel() attempts to cancel operations in an event set specified
  *          by \p es_id. H5ES_NONE is a valid value for \p es_id, but functions as a no-op.
  *
- * \since 1.13.0
+ * \since 1.14.0
  *
  */
 H5_DLL herr_t H5EScancel(hid_t es_id, size_t *num_not_canceled, hbool_t *err_occurred);
@@ -209,7 +220,7 @@ H5_DLL herr_t H5EScancel(hid_t es_id, size_t *num_not_canceled, hbool_t *err_occ
  * \details H5ESget_count() retrieves number of events in an event set specified
  *          by \p es_id.
  *
- * \since 1.13.0
+ * \since 1.14.0
  *
  */
 H5_DLL herr_t H5ESget_count(hid_t es_id, size_t *count);
@@ -230,7 +241,7 @@ H5_DLL herr_t H5ESget_count(hid_t es_id, size_t *count);
  *       for matching operations inserted into the event set with possible
  *       errors that occur.
  *
- * \since 1.13.0
+ * \since 1.14.0
  *
  */
 H5_DLL herr_t H5ESget_op_counter(hid_t es_id, uint64_t *counter);
@@ -248,7 +259,7 @@ H5_DLL herr_t H5ESget_op_counter(hid_t es_id, uint64_t *counter);
  * \details H5ESget_err_status() checks if event set specified by es_id has
  *          failed operations.
  *
- * \since 1.13.0
+ * \since 1.14.0
  *
  */
 H5_DLL herr_t H5ESget_err_status(hid_t es_id, hbool_t *err_occurred);
@@ -268,7 +279,7 @@ H5_DLL herr_t H5ESget_err_status(hid_t es_id, hbool_t *err_occurred);
  *          The function does not wait for active operations to complete, so
  *          count may not include all failures.
  *
- * \since 1.13.0
+ * \since 1.14.0
  *
  */
 H5_DLL herr_t H5ESget_err_count(hid_t es_id, size_t *num_errs);
@@ -292,13 +303,63 @@ H5_DLL herr_t H5ESget_err_count(hid_t es_id, size_t *num_errs);
  *          \snippet this H5ES_err_info_t_snip
  *          \click4more
  *
- * \since 1.13.0
+ * \since 1.14.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 Convenience routine to free an array of H5ES_err_info_t structs
+ *
+ * \param[in] num_err_info The number of elements in \p err_info array
+ * \param[in] err_info Array of structures
+ * \returns \herr_t
+ *
+ * \since 1.14.0
+ *
+ */
 H5_DLL herr_t H5ESfree_err_info(size_t num_err_info, H5ES_err_info_t err_info[]);
+
+/**
+ * \ingroup H5ES
+ *
+ * \brief Registers a callback to invoke when a new operation is inserted into
+ *        an event set
+ *
+ * \es_id
+ * \param[in] func The insert function to register
+ * \param[in] ctx User-specified information (context) to pass to \p func
+ * \returns \herr_t
+ *
+ * \details Only one insert callback can be registered for each event set.
+ *          Registering a new callback will replace the existing one.
+ *          H5ES_NONE is a valid value for 'es_id', but functions as a no-op
+ *
+ * \since 1.14.0
+ *
+ */
 H5_DLL herr_t H5ESregister_insert_func(hid_t es_id, H5ES_event_insert_func_t func, void *ctx);
+
+/**
+ * \ingroup H5ES
+ *
+ * \brief Registers a callback to invoke when an operation completes within an
+ *        event set
+ *
+ * \es_id
+ * \param[in] func The completion function to register
+ * \param[in] ctx User-specified information (context) to pass to \p func
+ * \returns \herr_t
+ *
+ * \details Only one complete callback can be registered for each event set.
+ *          Registering a new callback will replace the existing one.
+ *          H5ES_NONE is a valid value for 'es_id', but functions as a no-op
+ *
+ * \since 1.14.0
+ *
+ */
 H5_DLL herr_t H5ESregister_complete_func(hid_t es_id, H5ES_event_complete_func_t func, void *ctx);
 
 /**
@@ -311,7 +372,7 @@ H5_DLL herr_t H5ESregister_complete_func(hid_t es_id, H5ES_event_complete_func_t
  *
  * \details H5ESclose() terminates access to an event set specified by \p es_id.
  *
- * \since 1.13.0
+ * \since 1.14.0
  *
  */
 H5_DLL herr_t H5ESclose(hid_t es_id);
diff --git a/src/H5Epublic.h b/src/H5Epublic.h
index c01fa2b..dbc3457 100644
--- a/src/H5Epublic.h
+++ b/src/H5Epublic.h
@@ -314,7 +314,7 @@ H5_DLL hid_t H5Eget_current_stack(void);
  *          If \p close_source_stack is \c TRUE, the source error stack
  *          will be closed.
  *
- * \since 1.13.0
+ * \since 1.14.0
  */
 H5_DLL herr_t H5Eappend_stack(hid_t dst_stack_id, hid_t src_stack_id, hbool_t close_source_stack);
 /**
diff --git a/src/H5FDsubfiling/H5FDioc.h b/src/H5FDsubfiling/H5FDioc.h
index 516f483..bcacd52 100644
--- a/src/H5FDsubfiling/H5FDioc.h
+++ b/src/H5FDsubfiling/H5FDioc.h
@@ -146,7 +146,7 @@ H5_DLL hid_t H5FD_ioc_init(void);
  *       If the two drivers differ in configuration settings, application behavior
  *       may not be as expected.
  *
- * \since 1.13.2
+ * \since 1.14.0
  *
  */
 H5_DLL herr_t H5Pset_fapl_ioc(hid_t fapl_id, H5FD_ioc_config_t *vfd_config);
@@ -170,7 +170,7 @@ H5_DLL herr_t H5Pset_fapl_ioc(hid_t fapl_id, H5FD_ioc_config_t *vfd_config);
  *          values and then calling H5Pset_fapl_ioc() with the configured
  *          H5FD_ioc_config_t structure.
  *
- * \since 1.13.2
+ * \since 1.14.0
  *
  */
 H5_DLL herr_t H5Pget_fapl_ioc(hid_t fapl_id, H5FD_ioc_config_t *config_out);
diff --git a/src/H5FDsubfiling/H5FDsubfiling.h b/src/H5FDsubfiling/H5FDsubfiling.h
index c2543fa..22dd906 100644
--- a/src/H5FDsubfiling/H5FDsubfiling.h
+++ b/src/H5FDsubfiling/H5FDsubfiling.h
@@ -336,7 +336,7 @@ H5_DLL hid_t H5FD_subfiling_init(void);
  *       H5FD_subfiling_config_t documentation for information about configuration
  *       for the #H5FD_SUBFILING driver.
  *
- * \since 1.13.2
+ * \since 1.14.0
  *
  */
 H5_DLL herr_t H5Pset_fapl_subfiling(hid_t fapl_id, const H5FD_subfiling_config_t *vfd_config);
@@ -370,7 +370,7 @@ H5_DLL herr_t H5Pset_fapl_subfiling(hid_t fapl_id, const H5FD_subfiling_config_t
  *       environment variables to get accurate values for the #H5FD_SUBFILING driver
  *       properties.
  *
- * \since 1.13.2
+ * \since 1.14.0
  *
  */
 H5_DLL herr_t H5Pget_fapl_subfiling(hid_t fapl_id, H5FD_subfiling_config_t *config_out);
diff --git a/src/H5Ppublic.h b/src/H5Ppublic.h
index a4993ab..5d3774b 100644
--- a/src/H5Ppublic.h
+++ b/src/H5Ppublic.h
@@ -5329,7 +5329,7 @@ H5_DLL herr_t H5Pset_vol(hid_t plist_id, hid_t new_vol_id, const void *new_vol_i
  * \note The H5VL_CAP_FLAG_ASYNC flag can be checked to see if asynchronous
  *              operations are supported by the VOL connector stack.
  *
- * \since 1.13.0
+ * \since 1.14.0
  *
  */
 H5_DLL herr_t H5Pget_vol_cap_flags(hid_t plist_id, uint64_t *cap_flags);
@@ -8194,7 +8194,7 @@ H5_DLL herr_t H5Pget_mpio_no_collective_cause(hid_t plist_id, uint32_t *local_no
  *          please see the documentation for that routine for details about
  *          their use.
  *
- * \since 1.13.0
+ * \since 1.14.0
  *
  */
 H5_DLL herr_t H5Pset_dataset_io_hyperslab_selection(hid_t plist_id, unsigned rank, H5S_seloper_t op,
diff --git a/src/H5VLmodule.h b/src/H5VLmodule.h
index d6e65db..169134a 100644
--- a/src/H5VLmodule.h
+++ b/src/H5VLmodule.h
@@ -122,22 +122,14 @@
  * specifying a name in the VOL plugin environment variable.
  *
  * \subsubsection subsubsec_vol_quick_use Use A VOL-Enabled HDF5 Library
- * The virtual object layer was introduced in HDF5 1.12.0, however that version of the VOL is deprecated.
- * VOL users should target HDF5 1.13.X, which is currently under development. The 1.13.X releases are
- * considered ”unstable” in the sense that API calls, interfaces, and the file format may change in the
- * 1.13.X release branches and we do not guarantee binary compatibility (”unstable” does NOT mean buggy).
- * The next stable version of the library will be HDF5 1.14.0 which will release in 2023. The particular
- * configuration of the library (serial vs parallel, thread-safe, debug vs production/release) does not
- * matter. The VOL is a fundamental part of the library and cannot be disabled, so any build will do.
+ * The virtual object layer was introduced in HDF5 1.12.0, however that version of the VOL is deprecated
+ * due to inadequate support for pass-through connectors. These deficiencies have been addressed
+ * in HDF5 1.14.0, so VOL users and connector authors should target the 1.14.0 VOL API.
  *
  * On Windows, it’s probably best to use the same debug vs release configuration for the application and
  * all libraries in order to avoid C runtime (CRT) issues. Pre-2015 versions of Visual Studio are not
  * supported.
  *
- * When working with a debug HDF5 library, it’s probably also wise to build with the ”memory sanity checking”
- * feature disabled to avoid accidentally clobbering our memory tracking infrastructure when dealing with
- * buffers obtained from the HDF5 library. This feature should be disabled by default in HDF5 1.13.X.
- *
  * \subsubsection subsubsec_vol_quick_set Determine How You Will Set The VOL Connector
  * Fundamentally, setting a VOL connector involves modifying the file access property list (fapl) that will
  * be used to open or create the file.
@@ -505,7 +497,7 @@
  * \endcode
  *
  * \subsubsection subsubsec_vol_adapt_native Protect Native-Only API Calls
- * In HDF5 1.13.0, a way to determine support for optional calls has been added.
+ * In HDF5 1.14.0, a way to determine support for optional calls has been added.
  * \code
  *     herr_t H5VLquery_optional(hid_t obj_id, H5VL_subclass_t subcls, int opt_type, uint64_t *flags)
  * \endcode
diff --git a/src/H5VLpublic.h b/src/H5VLpublic.h
index 2683e0a..f32abda 100644
--- a/src/H5VLpublic.h
+++ b/src/H5VLpublic.h
@@ -414,7 +414,7 @@ H5_DLL herr_t H5VLquery_optional(hid_t obj_id, H5VL_subclass_t subcls, int opt_t
  *            VOL connector object
  * \return \herr_t
  *
- * \since 1.13.0
+ * \since 1.14.0
  */
 H5_DLL herr_t H5VLobject_is_native(hid_t obj_id, hbool_t *is_native);
 
diff --git a/src/H5public.h b/src/H5public.h
index 2b4d62b..8e5646d 100644
--- a/src/H5public.h
+++ b/src/H5public.h
@@ -449,7 +449,7 @@ H5_DLL herr_t H5open(void);
  *          If the HDF5 library is initialized and closed more than once, the
  *          \p func callback must be registered within each open/close cycle.
  *
- * \since 1.13.0
+ * \since 1.14.0
  */
 H5_DLL herr_t H5atclose(H5_atclose_func_t func, void *ctx);
 /**
@@ -652,7 +652,7 @@ H5_DLL herr_t H5check_version(unsigned majnum, unsigned minnum, unsigned relnum)
  *          after it has been closed.  The value of \p is_terminating is
  *          undefined if this routine fails.
  *
- * \since 1.13.0
+ * \since 1.14.0
  */
 H5_DLL herr_t H5is_library_terminating(hbool_t *is_terminating);
 /**