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, 749 insertions, 39 deletions

diff --git a/src/H5Epublic.h b/src/H5Epublic.h
index a2554d5..20a2107 100644
--- a/src/H5Epublic.h
+++ b/src/H5Epublic.h
@@ -26,18 +26,29 @@
 /* Value for the default error stack */
 #define H5E_DEFAULT (hid_t)0
 
-/* Different kinds of error information */
+/**
+ * Different kinds of error information
+ */
 typedef enum H5E_type_t { H5E_MAJOR, H5E_MINOR } H5E_type_t;
 
-/* Information about an error; element of error stack */
+/**
+ * Information about an error; element of error stack
+ */
 typedef struct H5E_error2_t {
-    hid_t       cls_id;    /*class ID                           */
-    hid_t       maj_num;   /*major error ID             */
-    hid_t       min_num;   /*minor error number             */
-    unsigned    line;      /*line in file where error occurs    */
-    const char *func_name; /*function in which error occurred   */
-    const char *file_name; /*file in which error occurred       */
-    const char *desc;      /*optional supplied description      */
+    hid_t cls_id;
+    /**< Class ID                           */
+    hid_t maj_num;
+    /**< Major error ID		                */
+    hid_t min_num;
+    /**< Minor error number		            */
+    unsigned line;
+    /**< Line in file where error occurs    */
+    const char *func_name;
+    /**< Function in which error occurred   */
+    const char *file_name;
+    /**< File in which error occurred       */
+    const char *desc;
+    /**< Optional supplied description      */
 } H5E_error2_t;
 
 /* When this header is included from a private header, don't make calls to H5open() */
@@ -138,10 +149,12 @@ H5_DLLVAR hid_t H5E_ERR_CLS_g;
         goto label;                                                                                          \
     }
 
-/* Error stack traversal direction */
+/**
+ * Error stack traversal direction
+ */
 typedef enum H5E_direction_t {
-    H5E_WALK_UPWARD   = 0, /*begin deep, end at API function    */
-    H5E_WALK_DOWNWARD = 1  /*begin at API function, end deep    */
+    H5E_WALK_UPWARD   = 0, /**< begin w/ most specific error, end at API function */
+    H5E_WALK_DOWNWARD = 1  /**< begin at API function, end w/ most specific error */
 } H5E_direction_t;
 
 #ifdef __cplusplus
@@ -149,30 +162,498 @@ extern "C" {
 #endif
 
 /* Error stack traversal callback function pointers */
+//! <!-- [H5E_walk2_t_snip] -->
+/**
+ * \brief Callback function for H5Ewalk2()
+ *
+ * \param[in] n Indexed error position in the stack
+ * \param[in] err_desc Pointer to a data structure describing the error
+ * \param[in] client_data Pointer to client data in the format expected by the
+ *                        user-defined function
+ * \return \herr_t
+ */
 typedef herr_t (*H5E_walk2_t)(unsigned n, const H5E_error2_t *err_desc, void *client_data);
+//! <!-- [H5E_walk2_t_snip] -->
+
+//! <!-- [H5E_auto2_t_snip] -->
+/**
+ * \brief Callback function for H5Eset_auto2()
+ *
+ * \estack_id{estack}
+ * \param[in] client_data Pointer to client data in the format expected by the
+ *                        user-defined function
+ * \return \herr_t
+ */
 typedef herr_t (*H5E_auto2_t)(hid_t estack, void *client_data);
+//! <!-- [H5E_auto2_t_snip] -->
 
 /* Public API functions */
-H5_DLL hid_t   H5Eregister_class(const char *cls_name, const char *lib_name, const char *version);
-H5_DLL herr_t  H5Eunregister_class(hid_t class_id);
-H5_DLL herr_t  H5Eclose_msg(hid_t err_id);
-H5_DLL hid_t   H5Ecreate_msg(hid_t cls, H5E_type_t msg_type, const char *msg);
-H5_DLL hid_t   H5Ecreate_stack(void);
-H5_DLL hid_t   H5Eget_current_stack(void);
-H5_DLL herr_t  H5Eappend_stack(hid_t dst_stack_id, hid_t src_stack_id, hbool_t close_source_stack);
-H5_DLL herr_t  H5Eclose_stack(hid_t stack_id);
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5E
+ *
+ * \brief Registers a client library or application program to the HDF5 error API
+ *
+ * \param[in] cls_name Name of the error class
+ * \param[in] lib_name Name of the client library or application to which the error class belongs
+ * \param[in] version Version of the client library or application to which the
+              error class belongs. Can be \c NULL.
+ * \return Returns a class identifier on success; otherwise returns H5I_INVALID_ID.
+ *
+ * \details H5Eregister_class() registers a client library or application
+ *          program to the HDF5 error API so that the client library or
+ *          application program can report errors together with the HDF5
+ *          library. It receives an identifier for this error class for further
+ *          error operations. The library name and version number will be
+ *          printed out in the error message as a preamble.
+ *
+ * \since 1.8.0
+ */
+H5_DLL hid_t H5Eregister_class(const char *cls_name, const char *lib_name, const char *version);
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5E
+ *
+ * \brief Removes an error class
+ *
+ * \param[in] class_id Error class identifier.
+ * \return \herr_t
+ *
+ * \details H5Eunregister_class() removes the error class specified by \p
+ *          class_id. All the major and minor errors in this class will also be
+ *          closed.
+ *
+ * \since 1.8.0
+ */
+H5_DLL herr_t H5Eunregister_class(hid_t class_id);
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5E
+ *
+ * \brief Closes an error message
+ *
+ * \param[in] err_id An error message identifier
+ * \return \herr_t
+ *
+ * \details H5Eclose_msg() closes an error message identifier, which can be
+ *          either a major or minor message.
+ *
+ * \since 1.8.0
+ */
+H5_DLL herr_t H5Eclose_msg(hid_t err_id);
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5E
+ *
+ * \brief Adds a major error message to an error class
+ *
+ * \param[in] cls An error class identifier
+ * \param[in] msg_type The type of the error message
+ * \param[in] msg Major error message
+ * \return \herr_t
+ *
+ * \details H5Ecreate_msg() adds an error message to an error class defined by
+ *          client library or application program. The error message can be
+ *          either major or minor as indicated by the parameter \p msg_type.
+ *
+ *          Use H5Eclose_msg() to close the message identifier returned by this
+ *          function.
+ *
+ * \since 1.8.0
+ */
+H5_DLL hid_t H5Ecreate_msg(hid_t cls, H5E_type_t msg_type, const char *msg);
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5E
+ *
+ * \brief Creates a new, empty error stack
+ *
+ * \return \hid_ti{error stack}
+ *
+ * \details H5Ecreate_stack() creates a new empty error stack and returns the
+ *          new stack’s identifier. Use H5Eclose_stack() to close the error stack
+ *          identifier returned by this function.
+ *
+ * \since 1.8.0
+ */
+H5_DLL hid_t H5Ecreate_stack(void);
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5E
+ *
+ * \brief Returns a copy of the current error stack
+ *
+ * \return \hid_ti{error stack}
+ *
+ * \details H5Eget_current_stack() copies the current error stack and returns an
+ *          error stack identifier for the new copy.
+ *
+ * \since 1.8.0
+ */
+H5_DLL hid_t H5Eget_current_stack(void);
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5E
+ *
+ * \brief Appends one error stack to another, optionally closing the source
+ *        stack.
+ *
+ * \estack_id{dst_stack_id}
+ * \estack_id{src_stack_id}
+ * \param[in] close_source_stack Flag to indicate whether to close the source stack
+ * \return \herr_t
+ *
+ * \details H5Eappend_stack() appends the messages from error stack
+ *          \p src_stack_id to the error stack \p dst_stack_id.
+ *          If \p close_source_stack is \c TRUE, the source error stack
+ *          will be closed.
+ *
+ * \since 1.8.0
+ */
+H5_DLL herr_t H5Eappend_stack(hid_t dst_stack_id, hid_t src_stack_id, hbool_t close_source_stack);
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5E
+ *
+ * \brief Closes an error stack handle
+ *
+ * \estack_id{stack_id}
+ *
+ * \return \herr_t
+ *
+ * \details H5Eclose_stack() closes the error stack handle \p stack_id
+ *          and releases its resources. #H5E_DEFAULT cannot be closed.
+ *
+ * \since 1.8.0
+ */
+H5_DLL herr_t H5Eclose_stack(hid_t stack_id);
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5E
+ *
+ * \brief Retrieves error class name
+ *
+ * \param[in] class_id Error class identifier
+ * \param[out] name Buffer for the error class name
+ * \param[in] size The maximum number of characters the class name to be returned
+ *            by this function in\p name.
+ * \return Returns non-negative value as on success; otherwise returns negative value.
+ *
+ * \details H5Eget_class_name() retrieves the name of the error class specified
+ *          by the class identifier. If non-NULL pointer is passed in for \p
+ *          name and \p size is greater than zero, the class name of \p size
+ *          long is returned. The length of the error class name is also
+ *          returned. If NULL is passed in as \p name, only the length of class
+ *          name is returned. If zero is returned, it means no name. The user is
+ *          responsible for allocating sufficient buffer space for the name.
+ *
+ * \since 1.8.0
+ */
 H5_DLL ssize_t H5Eget_class_name(hid_t class_id, char *name, size_t size);
-H5_DLL herr_t  H5Eset_current_stack(hid_t err_stack_id);
-H5_DLL herr_t  H5Epush2(hid_t err_stack, const char *file, const char *func, unsigned line, hid_t cls_id,
-                        hid_t maj_id, hid_t min_id, const char *msg, ...);
-H5_DLL herr_t  H5Epop(hid_t err_stack, size_t count);
-H5_DLL herr_t  H5Eprint2(hid_t err_stack, FILE *stream);
-H5_DLL herr_t  H5Ewalk2(hid_t err_stack, H5E_direction_t direction, H5E_walk2_t func, void *client_data);
-H5_DLL herr_t  H5Eget_auto2(hid_t estack_id, H5E_auto2_t *func, void **client_data);
-H5_DLL herr_t  H5Eset_auto2(hid_t estack_id, H5E_auto2_t func, void *client_data);
-H5_DLL herr_t  H5Eclear2(hid_t err_stack);
-H5_DLL herr_t  H5Eauto_is_v2(hid_t err_stack, unsigned *is_stack);
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5E
+ *
+ * \brief Replaces the current error stack
+ *
+ * \estack_id{err_stack_id}
+ *
+ * \return \herr_t
+ *
+ * \details H5Eset_current_stack() replaces the content of the current error
+ *          stack with a copy of the content of the error stack specified by
+ *          \p err_stack_id, and it closes the error stack specified by
+ *          \p err_stack_id.
+ *
+ * \since 1.8.0
+ */
+H5_DLL herr_t H5Eset_current_stack(hid_t err_stack_id);
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5E
+ *
+ * \brief Pushes a new error record onto an error stack
+ *
+ * \estack_id{err_stack}. If the identifier is #H5E_DEFAULT, the error record
+ *                        will be pushed to the current stack.
+ * \param[in] file Name of the file in which the error was detected
+ * \param[in] func Name of the function in which the error was detected
+ * \param[in] line Line number in the file where the error was detected
+ * \param[in] cls_id Error class identifier
+ * \param[in] maj_id Major error identifier
+ * \param[in] min_id Minor error identifier
+ * \param[in] msg Error description string
+ * \return \herr_t
+ *
+ * \details H5Epush2() pushes a new error record onto the error stack specified
+ *          by \p err_stack.\n
+ *          The error record contains the error class identifier \p cls_id, the
+ *          major and minor message identifiers \p maj_id and \p min_id, the
+ *          function name \p func where the error was detected, the file name \p
+ *          file and line number \p line in the file where the error was
+ *          detected, and an error description \p msg.\n
+ *          The major and minor errors must be in the same error class.\n
+ *          The function name, filename, and error description strings must be
+ *          statically allocated.\n
+ *          \p msg can be a format control string with additional
+ *          arguments. This design of appending additional arguments is similar
+ *          to the system and C functions printf() and fprintf().
+ *
+ * \since 1.8.0
+ */
+H5_DLL herr_t H5Epush2(hid_t err_stack, const char *file, const char *func, unsigned line, hid_t cls_id,
+                       hid_t maj_id, hid_t min_id, const char *msg, ...);
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5E
+ *
+ * \brief Deletes specified number of error messages from the error stack
+ *
+ * \estack_id{err_stack}
+ * \param[in] count The number of error messages to be deleted from the top
+ *                  of error stack
+ * \return \herr_t
+ *
+ * \details H5Epop() deletes the number of error records specified in \p count
+ *          from the top of the error stack specified by \p err_stack (including
+ *          major, minor messages and description). The number of error messages
+ *          to be deleted is specified by \p count.
+ *
+ * \since 1.8.0
+ */
+H5_DLL herr_t H5Epop(hid_t err_stack, size_t count);
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5E
+ *
+ * \brief Prints the specified error stack in a default manner
+ *
+ * \estack_id{err_stack}
+ * \param[in] stream File pointer, or \c NULL for \c stderr
+ * \return \herr_t
+ *
+ * \details H5Eprint2() prints the error stack specified by \p err_stack on the
+ *          specified stream, \p stream. Even if the error stack is empty, a
+ *          one-line message of the following form will be printed:
+ *          \code{.unparsed}
+ *          HDF5-DIAG: Error detected in HDF5 library version: 1.5.62 thread 0.
+ *          \endcode
+ *
+ *          A similar line will appear before the error messages of each error
+ *          class stating the library name, library version number, and thread
+ *          identifier.
+ *
+ *          If \p err_stack is #H5E_DEFAULT, the current error stack will be
+ *          printed.
+ *
+ *          H5Eprint2() is a convenience function for H5Ewalk2() with a function
+ *          that prints error messages. Users are encouraged to write their own
+ *          more specific error handlers.
+ *
+ * \since 1.8.0
+ */
+H5_DLL herr_t H5Eprint2(hid_t err_stack, FILE *stream);
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5E
+ *
+ * \brief Walks the specified error stack, calling the specified function
+ *
+ * \estack_id{err_stack}
+ * \param[in] direction Direction in which the error stack is to be walked
+ * \param[in] func Function to be called for each error encountered
+ * \param[in] client_data Data to be passed to \p func
+ * \return \herr_t
+ *
+ * \details H5Ewalk2() walks the error stack specified by err_stack for the
+ *          current thread and calls the function specified in \p func for each
+ *          error along the way.
+ *
+ *          If the value of \p err_stack is #H5E_DEFAULT, then H5Ewalk2() walks
+ *          the current error stack.
+ *
+ *          \p direction specifies whether the stack is walked from the inside
+ *          out or the outside in. A value of #H5E_WALK_UPWARD means to begin
+ *          with the most specific error and end at the API; a value of
+ *          #H5E_WALK_DOWNWARD means to start at the API and end at the
+ *          innermost function where the error was first detected.
+ *
+ *          \p func, a function conforming to the #H5E_walk2_t prototype, will
+ *          be called for each error in the error stack. Its arguments will
+ *          include an index number \c n (beginning at zero regardless of stack
+ *          traversal direction), an error stack entry \c err_desc, and the \c
+ *          client_data pointer passed to H5Eprint(). The #H5E_walk2_t prototype
+ *          is as follows:
+ *          \snippet this H5E_walk2_t_snip
+ *
+ * \since 1.8.0
+ */
+H5_DLL herr_t H5Ewalk2(hid_t err_stack, H5E_direction_t direction, H5E_walk2_t func, void *client_data);
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5E
+ *
+ * \brief Returns the settings for the automatic error stack traversal
+ *        function and its data
+ *
+ * \estack_id
+ * \param[out] func The function currently set to be called upon an error condition
+ * \param[out] client_data Data currently set to be passed to the error function
+ * \return \herr_t
+ *
+ * \details H5Eget_auto2() returns the settings for the automatic error stack
+ *          traversal function, \p func, and its data, \p client_data, that are
+ *          associated with the error stack specified by \p estack_id.
+ *
+ *          Either or both of the \p func and \p client_data arguments may be
+ *          \c NULL, in which case the value is not returned.
+ *
+ *          The library initializes its default error stack traversal functions
+ *          to H5Eprint1() and H5Eprint2(). A call to H5Eget_auto2() returns
+ *          H5Eprint2() or the user-defined function passed in through
+ *          H5Eset_auto2(). A call to H5Eget_auto1() returns H5Eprint1() or the
+ *          user-defined function passed in through H5Eset_auto1(). However, if
+ *          the application passes in a user-defined function through
+ *          H5Eset_auto1(), it should call H5Eget_auto1() to query the traversal
+ *          function. If the application passes in a user-defined function
+ *          through H5Eset_auto2(), it should call H5Eget_auto2() to query the
+ *          traversal function.
+ *
+ *          Mixing the new style and the old style functions will cause a
+ *          failure. For example, if the application sets a user-defined
+ *          old-style traversal function through H5Eset_auto1(), a call to
+ *          H5Eget_auto2() will fail and will indicate that the application has
+ *          mixed H5Eset_auto1() and H5Eget_auto2(). On the other hand, mixing
+ *          H5Eset_auto2() and H5Eget_auto1() will also cause a failure. But if
+ *          the traversal functions are the library’s default H5Eprint1() or
+ *          H5Eprint2(), mixing H5Eset_auto1() and H5Eget_auto2() or mixing
+ *          H5Eset_auto2() and H5Eget_auto1() does not fail.
+ *
+ * \since 1.8.0
+ */
+H5_DLL herr_t H5Eget_auto2(hid_t estack_id, H5E_auto2_t *func, void **client_data);
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5E
+ *
+ * \brief Turns automatic error printing on or off
+ *
+ * \estack_id
+ * \param[in] func Function to be called upon an error condition
+ * \param[in] client_data Data passed to the error function
+ * \return \herr_t
+ *
+ * \details H5Eset_auto2() turns on or off automatic printing of errors for the
+ *          error stack specified with \p estack_id. An \p estack_id value of
+ *          #H5E_DEFAULT indicates the current stack.
+ *
+ *          When automatic printing is turned on, by the use of a non-null \p func
+ *          pointer, any API function which returns an error indication will
+ *          first call \p func, passing it \p client_data as an argument.
+ *
+ *          \p func, a function compliant with the #H5E_auto2_t prototype, is
+ *          defined in the H5Epublic.h source code file as:
+ *          \snippet this H5E_auto2_t_snip
+ *
+ *          When the library is first initialized, the auto printing function is
+ *          set to H5Eprint2() (cast appropriately) and \p client_data is the
+ *          standard error stream pointer, \c stderr.
+ *
+ *          Automatic stack traversal is always in the #H5E_WALK_DOWNWARD
+ *          direction.
+ *
+ *          Automatic error printing is turned off with a H5Eset_auto2() call
+ *          with a \c NULL \p func pointer.
+ *
+ * \since 1.8.0
+ */
+H5_DLL herr_t H5Eset_auto2(hid_t estack_id, H5E_auto2_t func, void *client_data);
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5E
+ *
+ * \brief Clears the specified error stack or the error stack for the current thread
+ *
+ * \estack_id{err_stack}
+ * \return \herr_t
+ *
+ * \details H5Eclear2() clears the error stack specified by \p err_stack, or, if
+ *          \p err_stack is set to #H5E_DEFAULT, the error stack for the current
+ *          thread.
+ *
+ *          \p err_stack is an error stack identifier, such as that returned by
+ *          H5Eget_current_stack().
+ *
+ *          The current error stack is also cleared whenever an API function is
+ *          called, with certain exceptions (for instance, H5Eprint1() or
+ *          H5Eprint2()).
+ *
+ * \since 1.8.0
+ */
+H5_DLL herr_t H5Eclear2(hid_t err_stack);
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5E
+ *
+ * \brief Determines the type of error stack
+ *
+ * \estack_id{err_stack}
+ * \param[out] is_stack A flag indicating which error stack \c typedef the
+ *                      specified error stack conforms to
+ *
+ * \return \herr_t
+ *
+ * \details H5Eauto_is_v2() determines whether the error auto reporting function
+ *          for an error stack conforms to the #H5E_auto2_t \c typedef or the
+ *          #H5E_auto1_t \c typedef.
+ *
+ *          The \p is_stack parameter is set to 1 if the error stack conforms to
+ *          #H5E_auto2_t and 0 if it conforms to #H5E_auto1_t.
+ *
+ * \since 1.8.0
+ */
+H5_DLL herr_t H5Eauto_is_v2(hid_t err_stack, unsigned *is_stack);
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5E
+ *
+ * \brief Retrieves an error message
+ *
+ * \param[in] msg_id Error message identifier
+ * \param[out] type The type of the error message Valid values are #H5E_MAJOR
+ *                  and #H5E_MINOR.
+ * \param[out] msg Error message buffer
+ * \param[in] size The length of error message to be returned by this function
+ * \return Returns the size of the error message in bytes on success; otherwise
+ *         returns a negative value.
+ *
+ * \details H5Eget_msg() retrieves the error message including its length and
+ *          type. The error message is specified by \p msg_id. The user is
+ *          responsible for passing in sufficient buffer space for the
+ *          message. If \p msg is not NULL and \p size is greater than zero, the
+ *          error message of \p size long is returned. The length of the message
+ *          is also returned. If NULL is passed in as \p msg, only the length
+ *          and type of the message is returned. If the return value is zero, it
+ *          means there is no message.
+ *
+ * \since 1.8.0
+ */
 H5_DLL ssize_t H5Eget_msg(hid_t msg_id, H5E_type_t *type, char *msg, size_t size);
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5E
+ *
+ * \brief Retrieves the number of error messages in an error stack
+ *
+ * \estack_id{error_stack_id}
+ * \return Returns a non-negative value on success; otherwise returns a negative value.
+ *
+ * \details H5Eget_num() retrieves the number of error records in the error
+ *          stack specified by \p error_stack_id (including major, minor
+ *          messages and description).
+ *
+ * \since 1.8.0
+ */
 H5_DLL ssize_t H5Eget_num(hid_t error_stack_id);
 
 /* Symbols defined for compatibility with previous versions of the HDF5 API.
@@ -189,30 +670,259 @@ H5_DLL ssize_t H5Eget_num(hid_t error_stack_id);
 typedef hid_t H5E_major_t;
 typedef hid_t H5E_minor_t;
 
-/* Information about an error element of error stack. */
+/**
+ * Information about an error element of error stack.
+ */
 typedef struct H5E_error1_t {
-    H5E_major_t maj_num;   /*major error number                 */
-    H5E_minor_t min_num;   /*minor error number                 */
-    const char *func_name; /*function in which error occurred   */
-    const char *file_name; /*file in which error occurred       */
-    unsigned    line;      /*line in file where error occurs    */
-    const char *desc;      /*optional supplied description      */
+    H5E_major_t maj_num;   /**< major error number                 */
+    H5E_minor_t min_num;   /**< minor error number                 */
+    const char *func_name; /**< function in which error occurred   */
+    const char *file_name; /**< file in which error occurred       */
+    unsigned    line;      /**< line in file where error occurs    */
+    const char *desc;      /**< optional supplied description      */
 } H5E_error1_t;
 
 /* Error stack traversal callback function pointers */
+//! <!-- [H5E_walk1_t_snip] -->
+/**
+ * \brief Callback function for H5Ewalk1()
+ *
+ * \param[in] n Indexed error position in the stack
+ * \param[in] err_desc Pointer to a data structure describing the error
+ * \param[in] client_data Pointer to client data in the format expected by the
+ *                        user-defined function
+ * \return \herr_t
+ */
 typedef herr_t (*H5E_walk1_t)(int n, H5E_error1_t *err_desc, void *client_data);
+//! <!-- [H5E_walk1_t_snip] -->
+
+//! <!-- [H5E_auto1_t_snip] -->
+/**
+ * \brief Callback function for H5Eset_auto1()
+ *
+ * \param[in] client_data Pointer to client data in the format expected by the
+ *                        user-defined function
+ * \return \herr_t
+ */
 typedef herr_t (*H5E_auto1_t)(void *client_data);
+//! <!-- [H5E_auto1_t_snip] -->
 
 /* Function prototypes */
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5E
+ *
+ * \brief Clears the error stack for the current thread
+ *
+ * \return \herr_t
+ *
+ * \details H5Eclear1() clears the error stack for the current thread.\n
+ *          The stack is also cleared whenever an API function is called, with
+ *          certain exceptions (for instance, H5Eprint1()).
+ *
+ * \deprecated 1.8.0 Function H5Eclear() renamed to H5Eclear1() and deprecated
+ *                   in this release.
+ */
 H5_DLL herr_t H5Eclear1(void);
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5E
+ *
+ * \brief Returns the current settings for the automatic error stack traversal
+ *        function and its data
+ *
+ * \param[out] func Current setting for the function to be called upon an error
+ *                  condition
+ * \param[out] client_data Current setting for the data passed to the error
+ *                         function
+ * \return \herr_t
+ *
+ * \details H5Eget_auto1() returns the current settings for the automatic error
+ *          stack traversal function, \p func, and its data,
+ *          \p client_data. Either or both arguments may be \c NULL, in which case the
+ *          value is not returned.
+ *
+ *          The library initializes its default error stack traversal functions
+ *          to H5Eprint1() and H5Eprint2(). A call to H5Eget_auto2() returns
+ *          H5Eprint2() or the user-defined function passed in through
+ *          H5Eset_auto2(). A call to H5Eget_auto1() returns H5Eprint1() or the
+ *          user-defined function passed in through H5Eset_auto1(). However, if
+ *          the application passes in a user-defined function through
+ *          H5Eset_auto1(), it should call H5Eget_auto1() to query the traversal
+ *          function. If the application passes in a user-defined function
+ *          through H5Eset_auto2(), it should call H5Eget_auto2() to query the
+ *          traversal function.
+ *
+ *          Mixing the new style and the old style functions will cause a
+ *          failure. For example, if the application sets a user-defined
+ *          old-style traversal function through H5Eset_auto1(), a call to
+ *          H5Eget_auto2() will fail and will indicate that the application has
+ *          mixed H5Eset_auto1() and H5Eget_auto2(). On the other hand, mixing
+ *          H5Eset_auto2() and H5Eget_auto1() will also cause a failure. But if
+ *          the traversal functions are the library’s default H5Eprint1() or
+ *          H5Eprint2(), mixing H5Eset_auto1() and H5Eget_auto2() or mixing
+ *          H5Eset_auto2() and H5Eget_auto1() does not fail.
+ *
+ * \deprecated 1.8.0 Function H5Eget_auto() renamed to H5Eget_auto1() and
+ *                   deprecated in this release.
+ */
 H5_DLL herr_t H5Eget_auto1(H5E_auto1_t *func, void **client_data);
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5E
+ *
+ * \brief Pushes a new error record onto the error stack
+ *
+ * \param[in] file Name of the file in which the error was detected
+ * \param[in] func Name of the function in which the error was detected
+ * \param[in] line Line number in the file where the error was detected
+ * \param[in] maj Major error identifier
+ * \param[in] min Minor error identifier
+ * \param[in] str Error description string
+ * \return \herr_t
+ *
+ * \details H5Epush1() pushes a new error record onto the error stack for the
+ *          current thread.\n
+ *          The error has major and minor numbers \p maj_num
+ *          and \p min_num, the function \p func where the error was detected, the
+ *          name of the file \p file where the error was detected, the line \p line
+ *          within that file, and an error description string \p str.\n
+ *          The function name, filename, and error description strings must be statically
+ *          allocated.
+ *
+ * \since 1.4.0
+ * \deprecated 1.8.0 Function H5Epush() renamed to H5Epush1() and
+ *                   deprecated in this release.
+ */
 H5_DLL herr_t H5Epush1(const char *file, const char *func, unsigned line, H5E_major_t maj, H5E_minor_t min,
                        const char *str);
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5E
+ *
+ * \brief Prints the current error stack in a default manner
+ *
+ * \param[in] stream File pointer, or \c NULL for \c stderr
+ * \return \herr_t
+ *
+ * \details H5Eprint1() prints prints the error stack for the current thread
+ *          on the specified stream, \p stream. Even if the error stack is empty, a
+ *          one-line message of the following form will be printed:
+ *          \code{.unparsed}
+ *          HDF5-DIAG: Error detected in thread 0.
+ *          \endcode
+ *          H5Eprint1() is a convenience function for H5Ewalk1() with a function
+ *          that prints error messages. Users are encouraged to write their own
+ *          more specific error handlers.
+ *
+ * \deprecated 1.8.0 Function H5Eprint() renamed to H5Eprint1() and
+ *                   deprecated in this release.
+ */
 H5_DLL herr_t H5Eprint1(FILE *stream);
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5E
+ *
+ * \brief Turns automatic error printing on or off
+ *
+ * \param[in] func Function to be called upon an error condition
+ * \param[in] client_data Data passed to the error function
+ * \return \herr_t
+ *
+ * \details H5Eset_auto1() turns on or off automatic printing of errors. When
+ *          turned on (non-null \p func pointer), any API function which returns
+ *          an error indication will first call \p func, passing it \p
+ *          client_data as an argument.
+ *
+ *          \p func, a function conforming to the #H5E_auto1_t prototype, is
+ *          defined in the H5Epublic.h source code file as:
+ *          \snippet this H5E_auto1_t_snip
+ *
+ *          When the library is first initialized, the auto printing function is
+ *          set to H5Eprint1() (cast appropriately) and \p client_data is the
+ *          standard error stream pointer, \c stderr.
+ *
+ *          Automatic stack traversal is always in the #H5E_WALK_DOWNWARD
+ *          direction.
+ *
+ * \deprecated 1.8.0 Function H5Eset_auto() renamed to H5Eset_auto1() and
+ *                   deprecated in this release.
+ */
 H5_DLL herr_t H5Eset_auto1(H5E_auto1_t func, void *client_data);
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5E
+ *
+ * \brief Walks the current error stack, calling the specified function
+ *
+ * \param[in] direction Direction in which the error stack is to be walked
+ * \param[in] func Function to be called for each error encountered
+ * \param[in] client_data Data to be passed to \p func
+ * \return \herr_t
+ *
+ * \details H5Ewalk1() walks the error stack for the current thread and calls
+ *          the function specified in \p func for each error along the way.
+ *
+ *          \p direction specifies whether the stack is walked from the inside
+ *          out or the outside in. A value of #H5E_WALK_UPWARD means to begin
+ *          with the most specific error and end at the API; a value of
+ *          #H5E_WALK_DOWNWARD means to start at the API and end at the
+ *          innermost function where the error was first detected.
+ *
+ *          \p func, a function conforming to the #H5E_walk1_t prototype, will
+ *          be called for each error in the error stack. Its arguments will
+ *          include an index number \c n (beginning at zero regardless of stack
+ *          traversal direction), an error stack entry \c err_desc, and the \c
+ *          client_data pointer passed to H5Eprint(). The #H5E_walk1_t prototype
+ *          is as follows:
+ *          \snippet this H5E_walk1_t_snip
+ *
+ * \deprecated 1.8.0 Function H5Ewalk() renamed to H5Ewalk1() and
+ *                   deprecated in this release.
+ */
 H5_DLL herr_t H5Ewalk1(H5E_direction_t direction, H5E_walk1_t func, void *client_data);
-H5_DLL char * H5Eget_major(H5E_major_t maj);
-H5_DLL char * H5Eget_minor(H5E_minor_t min);
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5E
+ *
+ * \brief Returns a character string describing an error specified by a major
+ *        error number
+ *
+ * \param[in] maj Major error number
+ * \return \herr_t
+ *
+ * \details Given a major error number, H5Eget_major() returns a constant
+ *          character string that describes the error.
+ *
+ * \attention This function returns a dynamically allocated string (\c char
+ *            array). An application calling this function must free the memory
+ *            associated with the return value to prevent a memory leak.
+ *
+ * \deprecated 1.8.0 Function deprecated in this release.
+ */
+H5_DLL char *H5Eget_major(H5E_major_t maj);
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5E
+ *
+ * \brief Returns a character string describing an error specified by a minor
+ *        error number
+ *
+ * \param[in] min Minor error number
+ * \return \herr_t
+ *
+ * \details Given a minor error number, H5Eget_minor() returns a constant
+ *          character string that describes the error.
+ *
+ * \attention In the Release 1.8.x series, H5Eget_minor() returns a string of
+ *            dynamic allocated \c char array. An application calling this
+ *            function from an HDF5 library of Release 1.8.0 or later must free
+ *            the memory associated with the return value to prevent a memory
+ *            leak. This is a change from the 1.6.x release series.
+ *
+ * \deprecated 1.8.0 Function deprecated and return type changed in this release.
+ */
+H5_DLL char *H5Eget_minor(H5E_minor_t min);
 #endif /* H5_NO_DEPRECATED_SYMBOLS */
 
 #ifdef __cplusplus