From a25cd9a248ae5f0f92f0f696fa4d873fbbbd9903 Mon Sep 17 00:00:00 2001
From: Gerd Heber <gheber@hdfgroup.org>
Date: Wed, 11 Nov 2020 10:43:05 -0600
Subject: [PATCH 01/16] First cut of the H5 public API documentation.

---
 src/H5module.h |  34 ++++
 src/H5public.h | 459 ++++++++++++++++++++++++++++++++++++++++++++++---
 2 files changed, 469 insertions(+), 24 deletions(-)
 create mode 100644 src/H5module.h

diff --git a/src/H5module.h b/src/H5module.h
new file mode 100644
index 00000000000..f6884b1e771
--- /dev/null
+++ b/src/H5module.h
@@ -0,0 +1,34 @@
+/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
+ * Copyright by The HDF Group.                                               *
+ * All rights reserved.                                                      *
+ *                                                                           *
+ * This file is part of HDF5.  The full HDF5 copyright notice, including     *
+ * terms governing use, modification, and redistribution, is contained in    *
+ * the COPYING file, which can be found at the root of the source code       *
+ * distribution tree, or in https://support.hdfgroup.org/ftp/HDF5/releases.  *
+ * If you do not have access to either file, you may request a copy from     *
+ * help@hdfgroup.org.                                                        *
+ * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
+
+/*
+ * Purpose:	This file contains declarations which define macros for the
+ *		H5 package.  Including this header means that the source file
+ *		is part of the H5 package.
+ */
+#ifndef _H5module_H
+#define _H5module_H
+
+/* Define the proper control macros for the generic FUNC_ENTER/LEAVE and error
+ *      reporting macros.
+ */
+#define H5_MODULE
+#define H5_MY_PKG       H5
+#define H5_MY_PKG_ERR   H5E_LIB
+#define H5_MY_PKG_INIT  YES
+
+/**\defgroup H5 H5
+ * \brief General Library Functions
+ * \todo Describe concisely what the functions in this module are about.
+ */
+
+#endif /* _H5module_H */
diff --git a/src/H5public.h b/src/H5public.h
index 1784a118729..eb1f5739062 100644
--- a/src/H5public.h
+++ b/src/H5public.h
@@ -304,15 +304,21 @@ typedef unsigned long      uint32_t;
 #error "nothing appropriate for uint32_t"
 #endif
 
-/* Common iteration orders */
+//! [H5_iter_order_t_snip]
+
+/**
+ * Common iteration orders
+ */
 typedef enum {
-    H5_ITER_UNKNOWN = -1, /* Unknown order */
-    H5_ITER_INC,          /* Increasing order */
-    H5_ITER_DEC,          /* Decreasing order */
-    H5_ITER_NATIVE,       /* No particular order, whatever is fastest */
-    H5_ITER_N             /* Number of iteration orders */
+    H5_ITER_UNKNOWN = -1, /**< Unknown order */
+    H5_ITER_INC,          /**< Increasing order */
+    H5_ITER_DEC,          /**< Decreasing order */
+    H5_ITER_NATIVE,       /**< No particular order, whatever is fastest */
+    H5_ITER_N             /**< Number of iteration orders */
 } H5_iter_order_t;
 
+//! [H5_iter_order_t_snip]
+
 /* Iteration callback values */
 /* (Actually, any positive value will cause the iterator to stop and pass back
  *      that positive value to the function that called the iterator)
@@ -321,18 +327,22 @@ typedef enum {
 #define H5_ITER_CONT  (0)
 #define H5_ITER_STOP  (1)
 
-/*
+//! [H5_index_t_snip]
+
+/**
  * The types of indices on links in groups/attributes on objects.
  * Primarily used for "<do> <foo> by index" routines and for iterating over
  * links in groups/attributes on objects.
  */
 typedef enum H5_index_t {
-    H5_INDEX_UNKNOWN = -1, /* Unknown index type                   */
-    H5_INDEX_NAME,         /* Index on names                       */
-    H5_INDEX_CRT_ORDER,    /* Index on creation order              */
-    H5_INDEX_N             /* Number of indices defined            */
+    H5_INDEX_UNKNOWN = -1, /**< Unknown index type                   */
+    H5_INDEX_NAME,         /**< Index on names                       */
+    H5_INDEX_CRT_ORDER,    /**< Index on creation order              */
+    H5_INDEX_N             /**< Number of indices defined            */
 } H5_index_t;
 
+//! [H5_index_t_snip]
+
 /**
  * Storage info struct used by H5O_info_t and H5F_info_t
  */
@@ -343,45 +353,446 @@ typedef struct H5_ih_info_t {
 } H5_ih_info_t;
 //! [H5_ih_info_t_snip]
 
-/* Tokens are unique and permanent identifiers that are
- * used to reference HDF5 objects in a container. */
+/**
+ * The maximum size allowed for tokens
+ * \details Tokens are unique and permanent identifiers that are
+ *          used to reference HDF5 objects in a container. This allows
+ *          for 128-bit tokens
+ */
+#define H5O_MAX_TOKEN_SIZE (16)
 
-/* The maximum size allowed for tokens */
-#define H5O_MAX_TOKEN_SIZE (16) /* Allows for 128-bit tokens */
+//! [H5O_token_t_snip]
 
+/**
+ * \internal (Hoisted here, since it's used by both the
+ *            H5Lpublic.h and H5Opublic.h headers) */
 /* Type for object tokens */
-/* (Hoisted here, since it's used by both the H5Lpublic.h and H5Opublic.h headers) */
 typedef struct H5O_token_t {
     uint8_t __data[H5O_MAX_TOKEN_SIZE];
 } H5O_token_t;
 
-/*
+//! [H5O_token_t_snip]
+
+/**
  * Allocation statistics info struct
  */
 typedef struct H5_alloc_stats_t {
-    unsigned long long total_alloc_bytes;        /* Running count of total # of bytes allocated */
-    size_t             curr_alloc_bytes;         /* Current # of bytes allocated */
-    size_t             peak_alloc_bytes;         /* Peak # of bytes allocated */
-    size_t             max_block_size;           /* Largest block allocated */
-    size_t             total_alloc_blocks_count; /* Running count of total # of blocks allocated */
-    size_t             curr_alloc_blocks_count;  /* Current # of blocks allocated */
-    size_t             peak_alloc_blocks_count;  /* Peak # of blocks allocated */
+    unsigned long long total_alloc_bytes;        /**< Running count of total # of bytes allocated */
+    size_t             curr_alloc_bytes;         /**< Current # of bytes allocated */
+    size_t             peak_alloc_bytes;         /**< Peak # of bytes allocated */
+    size_t             max_block_size;           /**< Largest block allocated */
+    size_t             total_alloc_blocks_count; /**< Running count of total # of blocks allocated */
+    size_t             curr_alloc_blocks_count;  /**< Current # of blocks allocated */
+    size_t             peak_alloc_blocks_count;  /**< Peak # of blocks allocated */
 } H5_alloc_stats_t;
 
 /* Functions in H5.c */
+/**
+ * \ingroup H5
+ * \brief Initializes the HDF5 library
+ * \return \herr_t
+ *
+ * \details H5open() initializes the HDF5 library.
+ *
+ * \details When the HDF5 library is used in a C application, the library is
+ *          automatically initialized when the first HDf5 function call is
+ *          issued. If one finds that an HDF5 library function is failing
+ *          inexplicably, H5open() can be called first. It is safe to call
+ *          H5open() before an application issues any other function calls to
+ *          the HDF5 library as there are no damaging side effects in calling
+ *          it more than once.
+ */
 H5_DLL herr_t H5open(void);
+/**
+ * \ingroup H5
+ * \brief Flushes all data to disk, closes all open objects, and releases memory
+ * \return \herr_t
+ *
+ * \details H5close() flushes all data to disk, closes all open HDF5 objects,
+ *          and cleans up all memory used by the HDF5 library. This function is
+ *          generally called when the application calls exit(), but may be
+ *          called earlier in the event of an emergency shutdown or out of a
+ *          desire to free all resources used by the HDF5 library.
+ */
 H5_DLL herr_t H5close(void);
+/**
+ * \ingroup H5
+ * \brief Instructs library not to install atexit() cleanup routine
+ * \return \herr_t
+ *
+ * \details H5dont_atexit() indicates to the library that an atexit() cleanup
+ *          routine should not be installed. The major purpose for using this
+ *          function is in situations where the library is dynamically linked
+ *          into an application and is un-linked from the application before
+ *          exit() gets called. In those situations, a routine installed with
+ *          atexit() would jump to a routine which was no longer in memory,
+ *          causing errors.
+ *
+ * \attention In order to be effective, this routine \Emph{must} be called
+ *            before any other HDF5 function calls, and must be called each
+ *            time the library is loaded/linked into the application (the first
+ *            time and after it's been un-loaded).
+ */
 H5_DLL herr_t H5dont_atexit(void);
+/**
+ * \ingroup H5
+ * \brief Garbage collects on all free-lists of all types
+ * \return \herr_t
+ *
+ * \details H5garbage_collect() walks through all garbage collection routines
+ *          of the library, freeing any unused memory.
+ *
+ *          It is not required that H5garbage_collect() be called at any
+ *          particular time; it is only necessary in certain situations where
+ *          the application has performed actions that cause the library to
+ *          allocate many objects. The application should call
+ *          H5garbage_collect() if it eventually releases those objects and
+ *          wants to reduce the memory used by the library from the peak usage
+ *          required.
+ *
+ * \note The library automatically garbage collects all the free lists when the
+ *       application ends.
+ */
 H5_DLL herr_t H5garbage_collect(void);
+/**
+ * \ingroup H5
+ * \brief Sets free-list size limits
+ *
+ * \param[in] reg_global_lim The cumulative limit, in bytes, on memory used for
+ *                           all regular free lists (Default: 1MB)
+ * \param[in] reg_list_lim The limit, in bytes, on memory used for each regular
+ *                         free list (Default: 64KB)
+ * \param[in] arr_global_lim The cumulative limit, in bytes, on memory used for
+ *                           all array free lists (Default: 4MB)
+ * \param[in] arr_list_lim The limit, in bytes, on memory used for each array
+ *                         free list (Default: 256KB)
+ * \param[in] blk_global_lim The cumulative limit, in bytes, on memory used for
+ *                           all block free lists and, separately, for all
+ *                           factory free lists (Default: 16MB)
+ * \param[in] blk_list_lim The limit, in bytes, on memory used for each block
+ *                         or factory free list (Default: 1MB)
+ * \return \herr_t
+ *
+ * \details H5set_free_list_limits() sets size limits on all types of free
+ *          lists. The HDF5 library uses free lists internally to manage
+ *          memory. The types of free lists used are as follows:
+ *          \li Regular free lists manage memory for single internal data
+ *              structures.
+ *          \li Array free lists manage memory for arrays of internal
+ *              data structures.
+ *          \li Block free lists manage memory for arbitrarily-sized blocks
+ *              of bytes.
+ *          \li Factory free lists manage memory for fixed-size blocks of
+ *              bytes.
+ *
+ *          The parameters specify global and per-list limits; for example, \p
+ *          reg_global_limit and \p reg_list_limit limit the accumulated size
+ *          of all regular free lists and the size of each individual regular
+ *          free list, respectively. Therefore, if an application sets a 1Mb
+ *          limit on each of the global lists, up to 4Mb of total storage might
+ *          be allocated, 1Mb for each of the regular, array, block, and
+ *          factory type lists.
+ *
+ *          The settings specified for block free lists are duplicated for
+ *          factory free lists. Therefore, increasing the global limit on block
+ *          free lists by x bytes will increase the potential free list memory
+ *          usage by 2x bytes.
+ *
+ *          Using a value of -1 for a limit means that no limit is set for the
+ *          specified type of free list.
+ *
+ * \version 1.8.3 Function changed in this release to set factory free list
+ *                memory limits.
+ *
+ * \since 1.6.0
+ */
 H5_DLL herr_t H5set_free_list_limits(int reg_global_lim, int reg_list_lim, int arr_global_lim,
                                      int arr_list_lim, int blk_global_lim, int blk_list_lim);
+/**
+ * \ingroup H5
+ * \brief Gets the current size of the free lists used to manage memory
+ *
+ * \param[out] reg_size The current size of all "regular" free list memory used
+ * \param[out] arr_size The current size of all "array" free list memory used
+ * \param[out] blk_size The current size of all "block" free list memory used
+ * \param[out] fac_size The current size of all "factory" free list memory used
+ * \return \herr_t
+ *
+ * \details H5get_free_list_sizes() obtains the current size of the different
+ *          kinds of free lists that the library uses to manage memory. The
+ *          free list sizes can be set with H5set_free_list_limits() and
+ *          garbage collected with H5garbage_collect(). These lists are global
+ *          for the entire library.
+ *
+ * \since 1.12.1
+ */
 H5_DLL herr_t H5get_free_list_sizes(size_t *reg_size, size_t *arr_size, size_t *blk_size, size_t *fac_size);
+/**
+ * \ingroup H5
+ * \brief Gets the memory allocation statistics for the library
+ *
+ * \param[out] stats Memory allocation statistics
+ * \return \herr_t
+ *
+ * \details H5get_alloc_stats() gets the memory allocation statistics for the
+ *          library, if the \c --enable-memory-alloc-sanity-check option was
+ *          given when building the library. Applications can check whether
+ *          this option was enabled detecting if the
+ *          \c H5_MEMORY_ALLOC_SANITY_CHECK macro is defined. This option is
+ *          enabled by default for debug builds of the library and disabled by
+ *          default for non-debug builds. If the option is not enabled, all the
+ *          values returned with be 0. These statistics are global for the
+ *          entire library, but do not include allocations from chunked dataset
+ *          I/O filters or non-native VOL connectors.
+ *
+ * \since 1.12.1
+ */
 H5_DLL herr_t H5get_alloc_stats(H5_alloc_stats_t *stats);
+/**
+ * \ingroup H5
+ * \brief Returns the HDF library release number
+ *
+ * \param[out] majnum The major version number of the library
+ * \param[out] minnum The minor version number of the library
+ * \param[out] relnum The release version number of the library
+ * \return \herr_t
+ *
+ * \details H5get_libversion() retrieves the major, minor, and release numbers
+ *          of the version of the HDF5 library which is linked to the
+ *          application.
+ *
+ */
 H5_DLL herr_t H5get_libversion(unsigned *majnum, unsigned *minnum, unsigned *relnum);
+/**
+ * \ingroup H5
+ * \brief Verifies that HDF5 library versions are consistent
+ *
+ * \param[in] majnum HDF5 library major version number
+ * \param[in] minnum HDF5 library minor version number
+ * \param[in] relnum HDF5 library release number
+ * \return \herr_t
+ *
+ * \details H5check_version() verifies that the version of the HDF5 library
+ *          with which an application was compiled, as indicated by the passed
+ *          parameters, matches the version of the HDF5 library against which
+ *          the application is currently linked.
+ *
+ *          \p majnum is the major version number of the HDF library with which
+ *          the application was compiled, \p minnum is the minor version
+ *          number, and \p relnum is the release number. Consider the following
+ *          example:
+ *
+ *          An official HDF5 release is labelled as follows:
+ *          HDF5 Release \Code{\<majnum\>.\<minnum\>.\<relnum\>}\n
+ *          For example, in HDF5 Release 1.8.5:
+ *          \li 1 is the major version number, \p majnum.
+ *          \li 8 is the minor version number, \p minnum.
+ *          \li 5 is the release number, \p relnum.
+ *
+ *          As stated above, H5check_version() first verifies that the version
+ *          of the HDF5 library with which an application was compiled matches
+ *          the version of the HDF5 library against which the application is
+ *          currently linked. If this check fails, H5check_version() causes the
+ *          application to abort (by means of a standard C abort() call) and
+ *          prints information that is usually useful for debugging. This
+ *          precaution is is taken to avoid the risks of data corruption or
+ *          segmentation faults.
+ *
+ *          The most common cause of this failure is that an application was
+ *          compiled with one version of HDF5 and is dynamically linked with a
+ *          different version different version.
+ *
+ *          If the above test passes, H5check_version() proceeds to verify the
+ *          consistency of additional library version information. This is
+ *          designed to catch source code inconsistencies that do not normally
+ *          cause failures; if this check reveals an inconsistency, an
+ *          informational warning is printed but the application is allowed to
+ *          run.
+ *
+ */
 H5_DLL herr_t H5check_version(unsigned majnum, unsigned minnum, unsigned relnum);
+/**
+ * \ingroup H5
+ * \brief Determines whether the HDF5 library was built with the thread-safety
+ *        feature enabled
+ *
+ * \param[out] is_ts Boolean value indicating whether the library was built
+ *                   with thread-safety enabled
+ * \return \herr_t
+ *
+ * \details The HDF5 library, although not internally multi-threaded, can be
+ *          built with a thread-safety feature enabled that protects internal
+ *          data structures with a mutex. In certain circumstances, it may be
+ *          useful to determine, at run-time, whether the linked HDF5 library
+ *          was built with the thread-safety feature enabled.
+ */
 H5_DLL herr_t H5is_library_threadsafe(hbool_t *is_ts);
+/**
+ * \ingroup H5
+ * \brief Frees memory allocated by the HDF5 library
+ *
+ * \param[in] mem Buffer to be freed. Can be NULL
+ * \return \herr_t
+ *
+ * \details H5free_memory() frees memory that has been allocated by the caller
+ *          with H5allocate_memory() or by the HDF5 library on behalf of the
+ *          caller.
+ *
+ *          H5Tget_member_name() provides an example of memory allocation on
+ *          behalf of the caller: The function returns a buffer containing the
+ *          name of a compound datatype member. It is the caller’s
+ *          responsibility to eventually free that buffer with H5free_memory().
+ *
+ * \attention It is especially important to use this function to free memory
+ *            allocated by the library on Windows. The C standard library is
+ *            implemented in dynamic link libraries (DLLs) known as the C
+ *            run-time (CRT). Each version of Visual Studio comes with two CRT
+ *            DLLs (debug and release) and allocating and freeing across DLL
+ *            boundaries can cause resource leaks and subtle bugs due to heap
+ *            corruption.\n
+ *            Only use this function to free memory allocated by the HDF5
+ *            Library. It will generally not be safe to use this function to
+ *            free memory allocated by any other means.\n
+ *            Even when using this function, it is still best to ensure that
+ *            all components of a C application are built with the same version
+ *            of Visual Studio and build (debug or release) and thus linked
+ *            against the same CRT.
+ *
+ * \see H5allocate_memory(), H5resize_memory()
+ *
+ * \since 1.8.13
+ *
+ */
 H5_DLL herr_t H5free_memory(void *mem);
+/**
+ * \ingroup H5
+ * \brief Frees memory allocated by the HDF5 library
+ *
+ * \param[in] size The size in bytes of the buffer to be allocated
+ * \param[in] clear Flag whether the new buffer is to be initialized with 0
+ *
+ * \return On success, returns pointer to newly allocated buffer or returns
+ *         NULL if size is 0 (zero).\n
+ *         Returns NULL on failure.
+ *
+ * \details H5allocate_memory() allocates a memory buffer of size bytes that
+ *          will later be freed internally by the HDF5 library.
+ *
+ *          The boolean \p clear parameter specifies whether the buffer should
+ *          be initialized. If clear is \c TRUE, all bits in the buffer are to be
+ *          set to 0 (zero); if clear is \c FALSE, the buffer will not be
+ *          initialized.
+ *
+ *          This function is intended to have the semantics of malloc() and
+ *          calloc(). However, unlike malloc() and calloc() which allow for a
+ *          "special" pointer to be returned instead of NULL, this function
+ *          always returns NULL on failure or when size is set to 0 (zero).
+ *
+ * \note At this time, the only intended use for this function is to allocate
+ *       memory that will be returned to the library as a data buffer from a
+ *       third-party filter.
+ *
+ * \attention To avoid heap corruption, allocated memory should be freed using
+ *            the same library that initially allocated it. In most cases, the
+ *            HDF5 API uses resources that are allocated and freed either
+ *            entirely by the user or entirely by the library, so this is not a
+ *            problem. In rare cases, however, HDF5 API calls will free memory
+ *            that the user allocated. This function allows the user to safely
+ *            allocate this memory.\n
+ *            It is particularly important to use this function to allocate
+ *            memory in Microsoft Windows environments. In Windows, the C
+ *            standard library is implemented in dynamic link libraries (DLLs)
+ *            known as the C run-time (CRT). Each version of Visual Studio
+ *            comes with multiple versions of the CRT DLLs (debug, release, et
+ *            cetera) and allocating and freeing memory across DLL boundaries
+ *            can cause resource leaks and subtle bugs due to heap corruption.\n
+ *            Even when using this function, it is best where possible to
+ *            ensure that all components of a C application are built with the
+ *            same version of Visual Studio and configuration (Debug or
+ *            Release), and thus linked against the same CRT.\n
+ *            Use this function only to allocate memory inside third-party HDF5
+ *            filters. It will generally not be safe to use this function to
+ *            allocate memory for any other purpose.
+ *
+ * \see H5free_memory(), H5resize_memory()
+ *
+ * \since 1.8.15
+ *
+ */
 H5_DLL void * H5allocate_memory(size_t size, hbool_t clear);
+/**
+ * \ingroup H5
+ * \brief Resizes and, if required, re-allocates memory that will later be
+ *        freed internally by the HDF5 library
+ *
+ * \param[in] mem Pointer to a buffer to be resized. May be NULL
+ * \param[in] size New size of the buffer, in bytes
+
+ *
+ * \return On success, returns pointer to resized or reallocated buffer
+ *         or returns NULL if size is 0 (zero).\n
+ *         Returns NULL on failure.
+ *
+ * \details H5resize_memory() takes a pointer to an existing buffer and resizes
+ *          the buffer to match the value in \p size. If necessary, the buffer
+ *          is reallocated. If \p size is 0, the buffer is released.
+ *
+ *          The input buffer must either be NULL or have been allocated by
+ *          H5allocate_memory() since the input buffer may be freed by the
+ *          library.
+ *
+ *          For certain behaviors, the pointer \p mem may be passed in as NULL.
+ *
+ *          This function is intended to have the semantics of realloc():
+ *
+ *          <table>
+ *            <tr><td>\Code{H5resize_memory(buffer, size)}</td>
+ *                <td>Resizes buffer. Returns pointer to resized buffer.</td></tr>
+ *            <tr><td>\Code{H5resize_memory(NULL, size)}</td>
+ *                <td>Allocates memory using HDF5 Library allocator.
+ *                    Returns pointer to new buffer</td></tr>
+ *            <tr><td>\Code{H5resize_memory(buffer, 0)}</td>
+ *                <td>Frees memory using HDF5 Library allocator.
+ *                    Returns NULL.</td></tr>
+ *            <tr><td>\Code{H5resize_memory(NULL, 0)}</td>
+ *                <td>Returns NULL (undefined in C standard).</td></tr>
+ *          </table>
+ *
+ *          Unlike realloc(), which allows for a "special pointer to be
+ *          returned instead of NULL, this function always returns NULL on
+ *          failure or when size is 0 (zero).
+ *
+ * \note At this time, the only intended use for this function is to resize or
+ *       reallocate memory that will be returned to the library (and eventually
+ *       to the user) as a data buffer from a third-party HDF5 filter.
+ *
+ * \attention To avoid heap corruption, allocated memory should be freed using
+ *            the same library that initially allocated it. In most cases, the
+ *            HDF5 API uses resources that are allocated and freed either
+ *            entirely by the user or entirely by the library, so this is not a
+ *            problem. In rare cases, however, HDF5 API calls will free memory
+ *            that the user allocated. This function allows the user to safely
+ *            allocate this memory.\n
+ *            It is particularly important to use this function to resize
+ *            memory on Microsoft Windows systems. In Windows, the C standard
+ *            library is implemented in dynamic link libraries (DLLs) known as
+ *            the C run-time (CRT). Each version of Visual Studio comes with
+ *            multiple versions of the CRT DLLs (debug, release, et cetera) and
+ *            allocating and freeing memory across DLL boundaries can cause
+ *            resource leaks and subtle bugs due to heap corruption.\n
+ *            Even when using this function, it is still best to ensure that
+ *            all components of a C application are built with the same version
+ *            of Visual Studio and the same configuration (Debug or Release),
+ *            and thus linked against the same CRT.\n
+ *            Only use this function to resize memory inside third-party HDF5
+ *            filters. It will generally not be safe to use this function to
+ *            resize memory for any other purpose.
+ *
+ * \see H5allocate_memory(), H5free_memory()
+ *
+ * \since 1.8.15
+ *
+ */
 H5_DLL void * H5resize_memory(void *mem, size_t size);
 
 #ifdef __cplusplus

From c915fc2d1290c89ad7e58ffee79538a3dfeaf3a5 Mon Sep 17 00:00:00 2001
From: Gerd Heber <gheber@hdfgroup.org>
Date: Wed, 11 Nov 2020 14:03:04 -0600
Subject: [PATCH 02/16] Added H5Z "bonus track."

---
 src/H5Zmodule.h |  67 +++++
 src/H5Zpublic.h | 661 +++++++++++++++++++++++++++++++++++++++---------
 2 files changed, 603 insertions(+), 125 deletions(-)

diff --git a/src/H5Zmodule.h b/src/H5Zmodule.h
index d83f338f06e..3be26292fcd 100644
--- a/src/H5Zmodule.h
+++ b/src/H5Zmodule.h
@@ -29,4 +29,71 @@
 #define H5_MY_PKG_ERR  H5E_PLINE
 #define H5_MY_PKG_INIT YES
 
+/**
+ * \defgroup H5Z H5Z
+ *
+ *
+ * \brief Filter and Compression Interface
+ *
+ * \details The functions in this module let you configure filters that process
+ *          data during I/O operation.
+ *
+ *          HDF5 supports a filter pipeline that provides the capability for
+ *          standard and customized raw data processing during I/O operations.
+ *          HDF5 is distributed with a small set of standard filters such as
+ *          compression (gzip, SZIP, and a shuffling algorithm) and error
+ *          checking (Fletcher32 checksum). For further flexibility, the
+ *          library allows a user application to extend the pipeline through
+ *          the creation and registration of customized filters.
+ *
+ *          The flexibility of the filter pipeline implementation enables the
+ *          definition of additional filters by a user application. A filter
+ *          \li is associated with a dataset when the dataset is created,
+ *          \li can be used only with chunked data (i.e., datasets stored in
+ *              the #H5D_CHUNKED storage layout), and
+ *          \li is applied independently to each chunk of the dataset.
+ *
+ *          The HDF5 library does not support filters for contiguous datasets
+ *          because of the difficulty of implementing random access for partial
+ *          I/O. Compact dataset filters are not supported because it would not
+ *          produce significant results.
+ *
+ *          Filter identifiers for the filters distributed with the HDF5
+ *          Library are as follows:
+ *          <table>
+ *            <tr><td>#H5Z_FILTER_DEFLATE</td><td>The gzip compression, or
+ *                    deflation, filter</td></tr>
+ *            <tr><td>#H5Z_FILTER_SZIP</td><td>The SZIP compression
+ *                    filter</td></tr>
+ *            <tr><td>#H5Z_FILTER_NBIT</td><td>The N-bit compression
+ *                    filter</td></tr>
+ *            <tr><td>#H5Z_FILTER_SCALEOFFSET</td><td>The scale-offset
+ *                    compression filter</td></tr>
+ *            <tr><td>#H5Z_FILTER_SHUFFLE</td><td>The shuffle algorithm
+ *                    filter</td></tr>
+ *            <tr><td>#H5Z_FILTER_FLETCHER32</td><td>The Fletcher32 checksum,
+ *                    or error checking, filter</td></tr>
+ *          </table>
+ *          Custom filters that have been registered with the library will have
+ *          additional unique identifiers.
+ *
+ *          See \Emph{HDF5 Dynamically Loaded Filters} for more information on
+ *          how an HDF5 application can apply a filter that is not registered
+ *          with the HDF5 library.
+ *
+ * \todo Fix the reference.
+ *
+ * \defgroup H5ZPRE Predefined Filters
+ * \ingroup H5Z
+ * \defgroup FLETCHER32 Checksum Filter
+ * \ingroup H5ZPRE
+ * \defgroup SCALEOFFSET Scale-Offset Filter
+ * \ingroup H5ZPRE
+ * \defgroup SHUFFLE Shuffle Filter
+ * \ingroup H5ZPRE
+ * \defgroup SZIP Szip Filter
+ * \ingroup H5ZPRE
+ *
+ */
+
 #endif /* _H5Zmodule_H */
diff --git a/src/H5Zpublic.h b/src/H5Zpublic.h
index 97da13ccbe9..709e5fdf113 100644
--- a/src/H5Zpublic.h
+++ b/src/H5Zpublic.h
@@ -21,201 +21,610 @@
 /* Public headers needed by this file */
 #include "H5public.h"
 
-/*
- * Filter identifiers.  Values 0 through 255 are for filters defined by the
- * HDF5 library.  Values 256 through 511 are available for testing new
- * filters. Subsequent values should be obtained from the HDF5 development
- * team at help@hdfgroup.org.  These values will never change because they
- * appear in the HDF5 files.
+/**
+ * \brief Filter identifiers
+ *
+ * \details Values 0 through 255 are for filters defined by the HDF5 library.
+ *          Values 256 through 511 are available for testing new filters.
+ *          Subsequent values should be obtained from the HDF5 development team
+ *          at mailto:help@hdfgroup.org. These values will never change because
+ *          they appear in the HDF5 files.
  */
 typedef int H5Z_filter_t;
 
 /* Filter IDs */
-#define H5Z_FILTER_ERROR       (-1) /*no filter			*/
-#define H5Z_FILTER_NONE        0    /*reserved indefinitely		*/
-#define H5Z_FILTER_DEFLATE     1    /*deflation like gzip	     	*/
-#define H5Z_FILTER_SHUFFLE     2    /*shuffle the data              */
-#define H5Z_FILTER_FLETCHER32  3    /*fletcher32 checksum of EDC    */
-#define H5Z_FILTER_SZIP        4    /*szip compression              */
-#define H5Z_FILTER_NBIT        5    /*nbit compression              */
-#define H5Z_FILTER_SCALEOFFSET 6    /*scale+offset compression      */
-#define H5Z_FILTER_RESERVED    256  /*filter ids below this value are reserved for library use */
-
-#define H5Z_FILTER_MAX 65535 /*maximum filter id		*/
+/**
+ * no filter
+ */
+#define H5Z_FILTER_ERROR	(-1)
+/**
+ * reserved indefinitely
+*/
+#define H5Z_FILTER_NONE		0
+/**
+ * deflation like gzip
+ */
+#define H5Z_FILTER_DEFLATE	1
+/**
+ * shuffle the data
+ */
+#define H5Z_FILTER_SHUFFLE      2
+/**
+ * fletcher32 checksum of EDC
+*/
+#define H5Z_FILTER_FLETCHER32   3
+/**
+ * szip compression
+ */
+#define H5Z_FILTER_SZIP         4
+/**
+ * nbit compression
+ */
+#define H5Z_FILTER_NBIT         5
+/**
+ * scale+offset compression
+ */
+#define H5Z_FILTER_SCALEOFFSET  6
+/**
+ * filter ids below this value are reserved for library use
+ */
+#define H5Z_FILTER_RESERVED     256
+/**
+ * maximum filter id
+ */
+#define H5Z_FILTER_MAX		65535
 
 /* General macros */
-#define H5Z_FILTER_ALL   0  /* Symbol to remove all filters in H5Premove_filter */
-#define H5Z_MAX_NFILTERS 32 /* Maximum number of filters allowed in a pipeline */
-                            /* (should probably be allowed to be an
-                             * unlimited amount, but currently each
-                             * filter uses a bit in a 32-bit field,
-                             * so the format would have to be
-                             * changed to accommodate that)
-                             */
+/**
+ * Symbol to remove all filters in H5Premove_filter()
+ */
+#define H5Z_FILTER_ALL   0
+/**
+ * Maximum number of filters allowed in a pipeline
+ *
+ * \internal (should probably be allowed to be an unlimited amount, but
+ *            currently each filter uses a bit in a 32-bit field, so the format
+ *            would have to be changed to accommodate that)
+ */
+#define H5Z_MAX_NFILTERS        32
 
 /* Flags for filter definition (stored) */
-#define H5Z_FLAG_DEFMASK   0x00ff /*definition flag mask		*/
-#define H5Z_FLAG_MANDATORY 0x0000 /*filter is mandatory		*/
-#define H5Z_FLAG_OPTIONAL  0x0001 /*filter is optional		*/
+/**
+ * definition flag mask
+ */
+#define H5Z_FLAG_DEFMASK	0x00ff
+/**
+ * filter is mandatory
+ */
+#define H5Z_FLAG_MANDATORY  0x0000
+/**
+ * filter is optional
+ */
+#define H5Z_FLAG_OPTIONAL	0x0001
 
 /* Additional flags for filter invocation (not stored) */
-#define H5Z_FLAG_INVMASK  0xff00 /*invocation flag mask		*/
-#define H5Z_FLAG_REVERSE  0x0100 /*reverse direction; read	*/
-#define H5Z_FLAG_SKIP_EDC 0x0200 /*skip EDC filters for read	*/
+/**
+ * invocation flag mask
+ */
+#define H5Z_FLAG_INVMASK	0xff00
+/**
+ * reverse direction; read
+ */
+#define H5Z_FLAG_REVERSE	0x0100
+/**
+ * skip EDC filters for read
+ */
+#define H5Z_FLAG_SKIP_EDC	0x0200
 
 /* Special parameters for szip compression */
 /* [These are aliases for the similar definitions in szlib.h, which we can't
  * include directly due to the duplication of various symbols with the zlib.h
  * header file] */
-#define H5_SZIP_ALLOW_K13_OPTION_MASK 1
-#define H5_SZIP_CHIP_OPTION_MASK      2
-#define H5_SZIP_EC_OPTION_MASK        4
-#define H5_SZIP_NN_OPTION_MASK        32
-#define H5_SZIP_MAX_PIXELS_PER_BLOCK  32
+/**
+ * \ingroup SZIP */
+#define H5_SZIP_ALLOW_K13_OPTION_MASK   1
+/**
+ * \ingroup SZIP */
+#define H5_SZIP_CHIP_OPTION_MASK        2
+/**
+ * \ingroup SZIP */
+#define H5_SZIP_EC_OPTION_MASK          4
+/**
+ * \ingroup SZIP */
+#define H5_SZIP_NN_OPTION_MASK          32
+/**
+ * \ingroup SZIP */
+#define H5_SZIP_MAX_PIXELS_PER_BLOCK    32
 
 /* Macros for the shuffle filter */
-#define H5Z_SHUFFLE_USER_NPARMS  0 /* Number of parameters that users can set */
-#define H5Z_SHUFFLE_TOTAL_NPARMS 1 /* Total number of parameters for filter */
+/**
+ * \ingroup SHUFFLE
+ * Number of parameters that users can set for the shuffle filter
+*/
+#define H5Z_SHUFFLE_USER_NPARMS    0
+/**
+ * \ingroup SHUFFLE
+ * Total number of parameters for the shuffle filter
+ */
+#define H5Z_SHUFFLE_TOTAL_NPARMS   1
 
 /* Macros for the szip filter */
-#define H5Z_SZIP_USER_NPARMS  2 /* Number of parameters that users can set */
-#define H5Z_SZIP_TOTAL_NPARMS 4 /* Total number of parameters for filter */
-#define H5Z_SZIP_PARM_MASK    0 /* "User" parameter for option mask */
-#define H5Z_SZIP_PARM_PPB     1 /* "User" parameter for pixels-per-block */
-#define H5Z_SZIP_PARM_BPP     2 /* "Local" parameter for bits-per-pixel */
-#define H5Z_SZIP_PARM_PPS     3 /* "Local" parameter for pixels-per-scanline */
+/**
+ * \ingroup SZIP
+ * Number of parameters that users can set for SZIP
+ */
+#define H5Z_SZIP_USER_NPARMS    2
+/**
+ * \ingroup SZIP
+ * Total number of parameters for SZIP filter
+ */
+#define H5Z_SZIP_TOTAL_NPARMS   4
+/**
+ * \ingroup SZIP
+ * "User" parameter for option mask
+ */
+#define H5Z_SZIP_PARM_MASK      0
+/**
+ * \ingroup SZIP
+ * "User" parameter for pixels-per-block
+ */
+#define H5Z_SZIP_PARM_PPB       1
+/**
+ * \ingroup SZIP
+ * "Local" parameter for bits-per-pixel
+ */
+#define H5Z_SZIP_PARM_BPP       2
+/**
+ * \ingroup SZIP
+ * "Local" parameter for pixels-per-scanline
+ */
+#define H5Z_SZIP_PARM_PPS       3
 
 /* Macros for the nbit filter */
-#define H5Z_NBIT_USER_NPARMS 0 /* Number of parameters that users can set */
+/**
+ * \ingroup NBIT
+ * Number of parameters that users can set for the N-bit filter
+ */
+#define H5Z_NBIT_USER_NPARMS     0     /* Number of parameters that users can set */
 
 /* Macros for the scale offset filter */
-#define H5Z_SCALEOFFSET_USER_NPARMS 2 /* Number of parameters that users can set */
+/**
+ * \ingroup SCALEOFFSET
+ * Number of parameters that users can set for the scale-offset filter
+ */
+#define H5Z_SCALEOFFSET_USER_NPARMS      2
+
 
 /* Special parameters for ScaleOffset filter*/
+/**
+ * \ingroup SCALEOFFSET */
 #define H5Z_SO_INT_MINBITS_DEFAULT 0
+/**
+ * \ingroup SCALEOFFSET */
 typedef enum H5Z_SO_scale_type_t {
     H5Z_SO_FLOAT_DSCALE = 0,
     H5Z_SO_FLOAT_ESCALE = 1,
     H5Z_SO_INT          = 2
 } H5Z_SO_scale_type_t;
 
-/* Current version of the H5Z_class_t struct */
+/**
+ * Current version of the H5Z_class_t struct
+ */
 #define H5Z_CLASS_T_VERS (1)
 
-/* Values to decide if EDC is enabled for reading data */
+/**
+ * \ingroup FLETCHER32
+ * Values to decide if EDC is enabled for reading data
+ */
 typedef enum H5Z_EDC_t {
-    H5Z_ERROR_EDC   = -1, /* error value */
-    H5Z_DISABLE_EDC = 0,
-    H5Z_ENABLE_EDC  = 1,
-    H5Z_NO_EDC      = 2 /* must be the last */
+    H5Z_ERROR_EDC       = -1,   /**< error value */
+    H5Z_DISABLE_EDC     = 0,
+    H5Z_ENABLE_EDC      = 1,
+    H5Z_NO_EDC          = 2     /**< sentinel */
 } H5Z_EDC_t;
 
 /* Bit flags for H5Zget_filter_info */
 #define H5Z_FILTER_CONFIG_ENCODE_ENABLED (0x0001)
 #define H5Z_FILTER_CONFIG_DECODE_ENABLED (0x0002)
 
-/* Return values for filter callback function */
+/**
+ * Return values for filter callback function
+ */
 typedef enum H5Z_cb_return_t {
-    H5Z_CB_ERROR = -1,
-    H5Z_CB_FAIL  = 0, /* I/O should fail if filter fails. */
-    H5Z_CB_CONT  = 1, /* I/O continues if filter fails.   */
-    H5Z_CB_NO    = 2
+    H5Z_CB_ERROR  = -1,
+    H5Z_CB_FAIL   = 0,    /**< I/O should fail if filter fails. */
+    H5Z_CB_CONT   = 1,    /**< I/O continues if filter fails.   */
+    H5Z_CB_NO     = 2
 } H5Z_cb_return_t;
 
-/* Filter callback function definition */
-typedef H5Z_cb_return_t (*H5Z_filter_func_t)(H5Z_filter_t filter, void *buf, size_t buf_size, void *op_data);
+/**
+ *  Filter callback function definition
+ */
+typedef H5Z_cb_return_t (*H5Z_filter_func_t)(H5Z_filter_t filter, void* buf,
+                                size_t buf_size, void* op_data);
 
-/* Structure for filter callback property */
+/**
+ * Structure for filter callback property
+ */
 typedef struct H5Z_cb_t {
-    H5Z_filter_func_t func;
-    void *            op_data;
+    H5Z_filter_func_t   func;
+    void                *op_data;
 } H5Z_cb_t;
 
 #ifdef __cplusplus
 extern "C" {
 #endif
 
-/*
- * Before a dataset gets created, the "can_apply" callbacks for any filters used
- * in the dataset creation property list are called
- * with the dataset's dataset creation property list, the dataset's datatype and
- * a dataspace describing a chunk (for chunked dataset storage).
+/**
+ * \details Before a dataset gets created, the \c can_apply callbacks for any
+ *          filters used in the dataset creation property list are called with
+ *          the dataset's dataset creation property list, the dataset's
+ *          datatype and a dataspace describing a chunk (for chunked dataset
+ *          storage).
  *
- * The "can_apply" callback must determine if the combination of the dataset
- * creation property list setting, the datatype and the dataspace represent a
- * valid combination to apply this filter to.  For example, some cases of
- * invalid combinations may involve the filter not operating correctly on
- * certain datatypes (or certain datatype sizes), or certain sizes of the chunk
- * dataspace.
+ *          The \c can_apply callback must determine if the combination of the
+ *          dataset creation property list setting, the datatype and the
+ *          dataspace represent a valid combination to apply this filter to.
+ *          For example, some cases of invalid combinations may involve the
+ *          filter not operating correctly on certain datatypes (or certain
+ *          datatype sizes), or certain sizes of the chunk dataspace.
  *
- * The "can_apply" callback can be the NULL pointer, in which case, the library
- * will assume that it can apply to any combination of dataset creation
- * property list values, datatypes and dataspaces.
+ *          The \c can_apply callback can be the NULL pointer, in which case,
+ *          the library will assume that it can apply to any combination of
+ *          dataset creation property list values, datatypes and dataspaces.
  *
- * The "can_apply" callback returns positive a valid combination, zero for an
- * invalid combination and negative for an error.
+ *          The \c can_apply callback returns positive a valid combination,
+ *          zero for an invalid combination and negative for an error.
  */
+//! [H5Z_can_apply_func_t_snip]
 typedef htri_t (*H5Z_can_apply_func_t)(hid_t dcpl_id, hid_t type_id, hid_t space_id);
-
-/*
- * After the "can_apply" callbacks are checked for new datasets, the "set_local"
- * callbacks for any filters used in the dataset creation property list are
- * called.  These callbacks receive the dataset's private copy of the dataset
- * creation property list passed in to H5Dcreate (i.e. not the actual property
- * list passed in to H5Dcreate) and the datatype ID passed in to H5Dcreate
- * (which is not copied and should not be modified) and a dataspace describing
- * the chunk (for chunked dataset storage) (which should also not be modified).
+//! [H5Z_can_apply_func_t_snip]
+/**
+ * \details After the "can_apply" callbacks are checked for new datasets, the
+ *          \c set_local callbacks for any filters used in the dataset creation
+ *          property list are called. These callbacks receive the dataset's
+ *          private copy of the dataset creation property list passed in to
+ *          H5Dcreate() (i.e. not the actual property list passed in to
+ *          H5Dcreate()) and the datatype ID passed in to H5Dcreate() (which is
+ *          not copied and should not be modified) and a dataspace describing
+ *          the chunk (for chunked dataset storage) (which should also not be
+ *          modified).
  *
- * The "set_local" callback must set any parameters that are specific to this
- * dataset, based on the combination of the dataset creation property list
- * values, the datatype and the dataspace.  For example, some filters perform
- * different actions based on different datatypes (or datatype sizes) or
- * different number of dimensions or dataspace sizes.
+ *          The \c set_local callback must set any parameters that are specific
+ *          to this dataset, based on the combination of the dataset creation
+ *          property list values, the datatype and the dataspace. For example,
+ *          some filters perform different actions based on different datatypes
+ *          (or datatype sizes) or different number of dimensions or dataspace
+ *          sizes.
  *
- * The "set_local" callback can be the NULL pointer, in which case, the library
- * will assume that there are no dataset-specific settings for this filter.
+ *          The \c set_local callback can be the NULL pointer, in which case,
+ *          the library will assume that there are no dataset-specific settings
+ *          for this filter.
  *
- * The "set_local" callback must return non-negative on success and negative
- * for an error.
+ *          The \c set_local callback must return non-negative on success and
+ *          negative for an error.
  */
+//! [H5Z_set_local_func_t_snip]
 typedef herr_t (*H5Z_set_local_func_t)(hid_t dcpl_id, hid_t type_id, hid_t space_id);
-
-/*
- * A filter gets definition flags and invocation flags (defined above), the
- * client data array and size defined when the filter was added to the
- * pipeline, the size in bytes of the data on which to operate, and pointers
- * to a buffer and its allocated size.
+//! [H5Z_set_local_func_t_snip]
+/**
+ * \details A filter gets definition flags and invocation flags (defined
+ *          above), the client data array and size defined when the filter was
+ *          added to the pipeline, the size in bytes of the data on which to
+ *          operate, and pointers to a buffer and its allocated size.
  *
- * The filter should store the result in the supplied buffer if possible,
- * otherwise it can allocate a new buffer, freeing the original.  The
- * allocated size of the new buffer should be returned through the BUF_SIZE
- * pointer and the new buffer through the BUF pointer.
+ *          The filter should store the result in the supplied buffer if
+ *          possible, otherwise it can allocate a new buffer, freeing the
+ *          original. The allocated size of the new buffer should be returned
+ *          through the \p buf_size pointer and the new buffer through the \p
+ *          buf pointer.
  *
- * The return value from the filter is the number of bytes in the output
- * buffer. If an error occurs then the function should return zero and leave
- * all pointer arguments unchanged.
+ *          The return value from the filter is the number of bytes in the
+ *          output buffer. If an error occurs then the function should return
+ *          zero and leave all pointer arguments unchanged.
  */
+//! [H5Z_func_t_snip]
 typedef size_t (*H5Z_func_t)(unsigned int flags, size_t cd_nelmts, const unsigned int cd_values[],
                              size_t nbytes, size_t *buf_size, void **buf);
-
-/*
+//! [H5Z_func_t_snip]
+/**
  * The filter table maps filter identification numbers to structs that
  * contain a pointers to the filter function and timing statistics.
  */
+//! [H5Z_class2_t_snip]
 typedef struct H5Z_class2_t {
-    int                  version;         /* Version number of the H5Z_class_t struct     */
-    H5Z_filter_t         id;              /* Filter ID number                             */
-    unsigned             encoder_present; /* Does this filter have an encoder?            */
-    unsigned             decoder_present; /* Does this filter have a decoder?             */
-    const char *         name;            /* Comment for debugging                        */
-    H5Z_can_apply_func_t can_apply;       /* The "can apply" callback for a filter        */
-    H5Z_set_local_func_t set_local;       /* The "set local" callback for a filter        */
-    H5Z_func_t           filter;          /* The actual filter function                   */
+    int version;                    /**< Version number of the H5Z_class_t struct     */
+    H5Z_filter_t id;                /**< Filter ID number                             */
+    unsigned encoder_present;       /**< Does this filter have an encoder?            */
+    unsigned decoder_present;       /**< Does this filter have a decoder?             */
+    const char	*name;              /**< Comment for debugging                        */
+    H5Z_can_apply_func_t can_apply; /**< The "can apply" callback for a filter        */
+    H5Z_set_local_func_t set_local; /**< The "set local" callback for a filter        */
+    H5Z_func_t filter;              /**< The actual filter function                   */
 } H5Z_class2_t;
+//! [H5Z_class2_t_snip]
 
+/**
+ * \ingroup H5Z
+ *
+ * \brief Registers a new filter with the HDF5 library
+ *
+ * \param[in] cls A pointer to a buffer for the struct containing the
+ *                filter-definition
+ *
+ * \return \herr_t
+ *
+ * \details H5Zregister() registers a new filter with the HDF5 library.
+ *
+ * \details Making a new filter available to an application is a two-step
+ *          process. The first step is to write the three filter callback
+ *          functions described below: \c can_apply, \c set_local, and \c
+ *          filter. This call to H5Zregister(), registering the filter with the
+ *          library, is the second step. The can_apply and set_local fields can
+ *          be set to NULL if they are not required for the filter being
+ *          registered.
+ *
+ *          H5Zregister() accepts a single parameter, a pointer to a buffer for
+ *          the \p cls data structure. That data structure must conform to one
+ *          of the following definitions:
+ *          \snippet this H5Z_class1_t_snip
+ *          or
+ *          \snippet this H5Z_class2_t_snip
+ *
+ *          \c version is a library-defined value reporting the version number
+ *          of the #H5Z_class_t struct. This currently must be set to
+ *          #H5Z_CLASS_T_VERS.
+ *
+ *          \c id is the identifier for the new filter. This is a user-defined
+ *          value between #H5Z_FILTER_RESERVED and #H5Z_FILTER_MAX. These
+ *          values are defined in the HDF5 source file H5Zpublic.h, but the
+ *          symbols #H5Z_FILTER_RESERVED and #H5Z_FILTER_MAX should always be
+ *          used instead of the literal values.
+ *
+ *          \c encoder_present is a library-defined value indicating whether
+ *          the filter’s encoding capability is available to the application.
+ *
+ *          \c decoder_present is a library-defined value indicating whether
+ *          the filter’s encoding capability is available to the application.
+ *
+ *          \c name is a descriptive comment used for debugging, may contain a
+ *          descriptive name for the filter, and may be the null pointer.
+ *
+ *          \c can_apply, described in detail below, is a user-defined callback
+ *          function which determines whether the combination of the dataset
+ *          creation property list values, the datatype, and the dataspace
+ *          represent a valid combination to apply this filter to.
+ *
+ *          \c set_local, described in detail below, is a user-defined callback
+ *          function which sets any parameters that are specific to this
+ *          dataset, based on the combination of the dataset creation property
+ *          list values, the datatype, and the dataspace.
+ *
+ *          \c filter, described in detail below, is a user-defined callback
+ *          function which performs the action of the filter.
+ *
+ *          The statistics associated with a filter are not reset by this
+ *          function; they accumulate over the life of the library.
+ *
+ *          #H5Z_class_t is a macro which maps to either H5Z_class1_t or
+ *          H5Z_class2_t, depending on the needs of the application. To affect
+ *          only this macro, H5Z_class_t_vers may be defined to either 1 or 2.
+ *          Otherwise, it will behave in the same manner as other API
+ *          compatibility macros. See API Compatibility Macros in HDF5 for more
+ *          information. H5Z_class1_t matches the #H5Z_class_t structure that is
+ *          used in the 1.6.x versions of the HDF5 library.
+ *
+ *          H5Zregister() will automatically detect which structure type has
+ *          been passed in, regardless of the mapping of the #H5Z_class_t macro.
+ *          However, the application must make sure that the fields are filled
+ *          in according to the correct structure definition if the macro is
+ *          used to declare the structure.
+ *
+ *          \Bold{The callback functions:}\n Before H5Zregister() can link a
+ *          filter into an application, three callback functions must be
+ *          defined as described in the HDF5 library header file H5Zpublic.h.
+ *
+ *          When a filter is applied to the fractal heap for a group (e.g.,
+ *          when compressing group metadata) and if the can apply and set local
+ *          callback functions have been defined for that filter, HDF5 passes
+ *          the value -1 for all parameters for those callback functions. This
+ *          is done to ensure that the filter will not be applied to groups if
+ *          it relies on these parameters, as they are not applicable to group
+ *          fractal heaps; to operate on group fractal heaps, a filter must be
+ *          capable of operating on an opaque block of binary data.
+ *
+ *          The \Emph{can apply} callback function must return a positive value
+ *          for a valid combination, zero for an invalid combination, and a
+ *          negative value for an error.
+ *          \snippet this H5Z_can_apply_func_t_snip
+ *
+ *          Before a dataset is created, the \Emph{can apply} callbacks for any
+ *          filters used in the dataset creation property list are called with
+ *          the dataset's dataset creation property list, \c dcpl_id, the
+ *          dataset's datatype, \p type_id, and a dataspace describing a chunk,
+ *          \p space_id, (for chunked dataset storage).
+ *
+ *          This callback must determine whether the combination of the dataset
+ *          creation property list settings, the datatype, and the dataspace
+ *          represent a valid combination to which to apply this filter. For
+ *          example, an invalid combination may involve the filter not
+ *          operating correctly on certain datatypes, on certain datatype
+ *          sizes, or on certain sizes of the chunk dataspace. If this filter
+ *          is enabled through H5Pset_filter() as optional and the can apply
+ *          function returns 0, the library will skip the filter in the filter
+ *          pipeline.
+ *
+ *          This callback can be the NULL pointer, in which case the library
+ *          will assume that the filter can be applied to a dataset with any
+ *          combination of dataset creation property list values, datatypes,
+ *          and dataspaces.
+ *
+ *          The \Emph{set local} callback function is defined as follows:
+ *          \snippet this H5Z_set_local_func_t_snip
+ *
+ *          After the can apply callbacks are checked for a new dataset, the
+ *          \Emph{set local} callback functions for any filters used in the
+ *          dataset creation property list are called. These callbacks receive
+ *          \c dcpl_id, the dataset's private copy of the dataset creation
+ *          property list passed in to H5Dcreate() (i.e. not the actual
+ *          property list passed in to H5Dcreate()); \c type_id, the datatype
+ *          identifier passed in to H5Dcreate(), which is not copied and should
+ *          not be modified; and \c space_id, a dataspace describing the chunk
+ *          (for chunked dataset storage), which should also not be modified.
+ *
+ *          The set local callback must set any filter parameters that are
+ *          specific to this dataset, based on the combination of the dataset
+ *          creation property list values, the datatype, and the dataspace. For
+ *          example, some filters perform different actions based on different
+ *          datatypes, datatype sizes, numbers of dimensions, or dataspace
+ *          sizes.
+ *
+ *          The \Emph{set local} callback may be the NULL pointer, in which
+ *          case, the library will assume that there are no dataset-specific
+ *          settings for this filter.
+ *
+ *          The \Emph{set local} callback function must return a non-negative
+ *          value on success and a negative value for an error.
+ *
+ *          The \Emph{filter operation} callback function, defining the
+ *          filter's operation on the data, is defined as follows:
+ *          \snippet this H5Z_func_t_snip
+ *
+ *          The parameters \c flags, \c cd_nelmts, and \c cd_values are the
+ *          same as for the function H5Pset_filter(). The one exception is that
+ *          an additional flag, #H5Z_FLAG_REVERSE, is set when the filter is
+ *          called as part of the input pipeline.
+ *
+ *          The parameter \c buf points to the input buffer which has a size of
+ *          \c buf_size bytes, \c nbytes of which are valid data.
+ *
+ *          The filter should perform the transformation in place if possible.
+ *          If the transformation cannot be done in place, then the filter
+ *          should allocate a new buffer with malloc() and assign it to \c buf,
+ *          assigning the allocated size of that buffer to \c buf_size. The old
+ *          buffer should be freed by calling free().
+ *
+ *          If successful, the \Emph{filter operation} callback function
+ *          returns the number of valid bytes of data contained in \c buf. In
+ *          the case of failure, the return value is 0 (zero) and all pointer
+ *          arguments are left unchanged.
+ *
+ * \version 1.8.6 Return type for the \Emph{can apply} callback function,
+ *                \ref H5Z_can_apply_func_t, changed to \ref htri_t.
+ * \version 1.8.5 Semantics of the \Emph{can apply} and \Emph{set local}
+ *                callback functions changed to accommodate the use of filters
+ *                with group fractal heaps.
+ * \version 1.8.3 #H5Z_class_t renamed to H5Z_class2_t, H5Z_class1_t structure
+ *                introduced for backwards compatibility with release 1.6.x,
+ *                and #H5Z_class_t macro introduced in this release. Function
+ *                modified to accept either structure type.
+ * \version 1.8.0 The fields \c version, \c encoder_present, and
+ *                \c decoder_present were added to the #H5Z_class_t \c struct
+ *                in this release.
+ * \version 1.6.0 This function was substantially revised in Release 1.6.0 with
+ *                a new #H5Z_class_t struct and new set local and can apply
+ *                callback functions.
+ *
+ */
 H5_DLL herr_t H5Zregister(const void *cls);
+/**
+ * \ingroup H5Z
+ *
+ * \brief Unregisters a filter.
+ *
+ * \param[in] id Identifier of the filter to be unregistered.
+ * \return \herr_t
+ *
+ * \details H5Zunregister() unregisters the filter specified in \p id.
+ *
+ * \details This function first iterates through all opened datasets and
+ *          groups. If an open object that uses this filter is found, the
+ *          function will fail with a message indicating that an object using
+ *          the filter is still open. All open files are then flushed to make
+ *          sure that all cached data that may use this filter are written out.
+ *
+ *          If the application is a parallel program, all processes that
+ *          participate in collective data write should call this function to
+ *          ensure that all data is flushed.
+ *
+ *          After a call to H5Zunregister(), the filter specified in filter
+ *          will no longer be available to the application.
+ *
+ * \version 1.8.12 Function modified to check for open objects using the
+ *                 filter.
+ * \since 1.6.0
+ */
 H5_DLL herr_t H5Zunregister(H5Z_filter_t id);
+/**
+ * \ingroup H5Z
+ *
+ * \brief Determines whether a filter is available
+ *
+ * \param[in] id Filter identifier
+ * \return \htri_t
+ *
+ * \details H5Zfilter_avail() determines whether the filter specified in \p id
+ *          is available to the application.
+ *
+ * \since 1.6.0
+ */
 H5_DLL htri_t H5Zfilter_avail(H5Z_filter_t id);
+/**
+ * \ingroup H5Z
+ *
+ * \brief Retrieves information about a filter
+ *
+ * \param[in] filter Filter identifier
+ * \param[out] filter_config_flags A bit field encoding the returned filter
+ *                                 information
+ * \return \herr_t
+ *
+ * \details H5Zget_filter_info() retrieves information about a filter. At
+ *          present, this means that the function retrieves a filter's
+ *          configuration flags, indicating whether the filter is configured to
+ *          decode data, to encode data, neither, or both.
+ *
+ *          If \p filter_config_flags is not set to NULL prior to the function
+ *          call, the returned parameter contains a bit field specifying the
+ *          available filter configuration. The configuration flag values can
+ *          then be determined through a series of bitwise AND operations, as
+ *          described below.
+ *
+ *          Valid filter configuration flags include the following:
+ *          <table>
+ *            <tr><td>#H5Z_FILTER_CONFIG_ENCODE_ENABLED</td>
+ *                <td>Encoding is enabled for this filter</td></tr>
+ *            <tr><td>#H5Z_FILTER_CONFIG_DECODE_ENABLED</td>
+ *                <td>Decoding is enabled for this filter</td></tr>
+ *          </table>
+ *
+ *          A bitwise AND of the returned \p filter_config_flags and a valid
+ *          filter configuration flag will reveal whether the related
+ *          configuration option is available. For example, if the value of
+ *          \code
+ *          H5Z_FILTER_CONFIG_ENCODE_ENABLED & filter_config_flags
+ *          \endcode
+ *          is true, i.e., greater than 0 (zero), the queried filter
+ *          is configured to encode data; if the value is \c FALSE, i.e., equal to
+ *          0 (zero), the filter is not so configured.
+ *
+ *          If a filter is not encode-enabled, the corresponding \c H5Pset_*
+ *          function will return an error if the filter is added to a dataset
+ *          creation property list (which is required if the filter is to be
+ *          used to encode that dataset). For example, if the
+ *          #H5Z_FILTER_CONFIG_ENCODE_ENABLED flag is not returned for the SZIP
+ *          filter, #H5Z_FILTER_SZIP, a call to H5Pset_szip() will fail.
+ *
+ *          If a filter is not decode-enabled, the application will not be able
+ *          to read an existing file encoded with that filter.
+ *
+ *          This function should be called, and the returned \p
+ *          filter_config_flags analyzed, before calling any other function,
+ *          such as H5Pset_szip() , that might require a particular filter
+ *          configuration.
+ *
+ * \since 1.6.3
+ */
 H5_DLL herr_t H5Zget_filter_info(H5Z_filter_t filter, unsigned int *filter_config_flags);
 
 /* Symbols defined for compatibility with previous versions of the HDF5 API.
@@ -224,17 +633,19 @@ H5_DLL herr_t H5Zget_filter_info(H5Z_filter_t filter, unsigned int *filter_confi
  */
 #ifndef H5_NO_DEPRECATED_SYMBOLS
 
-/*
+/**
  * The filter table maps filter identification numbers to structs that
  * contain a pointers to the filter function and timing statistics.
  */
+//! [H5Z_class1_t_snip]
 typedef struct H5Z_class1_t {
-    H5Z_filter_t         id;        /* Filter ID number			     */
-    const char *         name;      /* Comment for debugging		     */
-    H5Z_can_apply_func_t can_apply; /* The "can apply" callback for a filter */
-    H5Z_set_local_func_t set_local; /* The "set local" callback for a filter */
-    H5Z_func_t           filter;    /* The actual filter function		     */
+    H5Z_filter_t id;		/**< Filter ID number			     */
+    const char	*name;		/**< Comment for debugging		     */
+    H5Z_can_apply_func_t can_apply; /**< The "can apply" callback for a filter */
+    H5Z_set_local_func_t set_local; /**< The "set local" callback for a filter */
+    H5Z_func_t filter;		/**< The actual filter function		     */
 } H5Z_class1_t;
+//! [H5Z_class1_t_snip]
 
 #endif /* H5_NO_DEPRECATED_SYMBOLS */
 

From 4c35645d179d4435df5d93fefef85cb8f77ab219 Mon Sep 17 00:00:00 2001
From: Gerd Heber <gheber@hdfgroup.org>
Date: Thu, 12 Nov 2020 13:48:07 -0600
Subject: [PATCH 03/16] Applied Quincey's patch.

---
 src/H5.c | 36 ++++++++++++++++++++++++++++++++++++
 1 file changed, 36 insertions(+)

diff --git a/src/H5.c b/src/H5.c
index e7514b408ec..7efd4f0678a 100644
--- a/src/H5.c
+++ b/src/H5.c
@@ -14,6 +14,7 @@
 /****************/
 /* Module Setup */
 /****************/
+#include "H5module.h" /* This source code file is part of the H5 module */
 
 /***********/
 /* Headers */
@@ -55,6 +56,9 @@ static int H5__mpi_delete_cb(MPI_Comm comm, int keyval, void *attr_val, int *fla
 /* Package Variables */
 /*********************/
 
+/* Package initialization variable */
+hbool_t H5_PKG_INIT_VAR = FALSE;
+
 /*****************************/
 /* Library Private Variables */
 /*****************************/
@@ -84,6 +88,33 @@ H5_debug_t     H5_debug_g; /* debugging info */
 /* Local Variables */
 /*******************/
 
+/*--------------------------------------------------------------------------
+NAME
+    H5__init_package -- Initialize interface-specific information
+USAGE
+    herr_t H5__init_package()
+RETURNS
+    Non-negative on success/Negative on failure
+DESCRIPTION
+    Initializes any interface-specific data or routines.
+--------------------------------------------------------------------------*/
+herr_t
+H5__init_package(void)
+{
+    herr_t          ret_value = SUCCEED; /* Return value */
+
+    FUNC_ENTER_NOAPI_NOINIT
+
+    /* Run the library initialization routine, if it hasn't already ran */
+    if (!H5_INIT_GLOBAL && !H5_TERM_GLOBAL) {                                                                \
+        if (H5_init_library() < 0)
+            HGOTO_ERROR(H5E_LIB, H5E_CANTINIT, FAIL, "unable to initialize library")
+    } /* end if */
+
+done:
+    FUNC_LEAVE_NOAPI(ret_value)
+} /* end H5__init_package() */
+
 /*--------------------------------------------------------------------------
  * NAME
  *   H5_init_library -- Initialize library-global information
@@ -103,6 +134,11 @@ H5_init_library(void)
 {
     herr_t ret_value = SUCCEED;
 
+    /* Set the 'library initialized' flag as early as possible, to avoid
+     * possible re-entrancy.
+     */
+    H5_INIT_GLOBAL = TRUE;                                                                               \
+
     FUNC_ENTER_NOAPI(FAIL)
 
 #ifdef H5_HAVE_PARALLEL

From e115c832918aef88e7f6de99cf8b581ac077ab09 Mon Sep 17 00:00:00 2001
From: Gerd Heber <gheber@hdfgroup.org>
Date: Thu, 12 Nov 2020 14:00:53 -0600
Subject: [PATCH 04/16] Added the missing patches from Quincey's original
 patch.

---
 src/H5checksum.c | 3 ++-
 src/H5dbg.c      | 1 +
 src/H5err.txt    | 1 +
 src/H5private.h  | 2 --
 src/H5system.c   | 3 ++-
 src/H5timer.c    | 1 +
 src/H5trace.c    | 1 +
 7 files changed, 8 insertions(+), 4 deletions(-)

diff --git a/src/H5checksum.c b/src/H5checksum.c
index bc36bb9fbe5..82964d9909e 100644
--- a/src/H5checksum.c
+++ b/src/H5checksum.c
@@ -25,6 +25,7 @@
 /****************/
 /* Module Setup */
 /****************/
+#include "H5module.h" /* This source code file is part of the H5 module */
 
 /***********/
 /* Headers */
@@ -379,7 +380,7 @@ uint32_t
 H5_checksum_lookup3(const void *key, size_t length, uint32_t initval)
 {
     const uint8_t *k = (const uint8_t *)key;
-    uint32_t       a, b, c; /* internal state */
+    uint32_t       a, b, c = 0; /* internal state */
 
     FUNC_ENTER_NOAPI_NOINIT_NOERR
 
diff --git a/src/H5dbg.c b/src/H5dbg.c
index 1b64d2c60dc..5d38efcc2ce 100644
--- a/src/H5dbg.c
+++ b/src/H5dbg.c
@@ -25,6 +25,7 @@
 /****************/
 /* Module Setup */
 /****************/
+#include "H5module.h" /* This source code file is part of the H5 module */
 
 /***********/
 /* Headers */
diff --git a/src/H5err.txt b/src/H5err.txt
index 24ac2acbfb2..05476e5f7e0 100644
--- a/src/H5err.txt
+++ b/src/H5err.txt
@@ -46,6 +46,7 @@
 MAJOR, H5E_ARGS, Invalid arguments to routine
 MAJOR, H5E_RESOURCE, Resource unavailable
 MAJOR, H5E_INTERNAL, Internal error (too specific to document in detail)
+MAJOR, H5E_LIB, General library infrastructure
 MAJOR, H5E_FILE, File accessibility
 MAJOR, H5E_IO, Low-level I/O
 MAJOR, H5E_FUNC, Function entry/exit
diff --git a/src/H5private.h b/src/H5private.h
index 1390b3f5b84..600089da3fe 100644
--- a/src/H5private.h
+++ b/src/H5private.h
@@ -2160,7 +2160,6 @@ H5_DLL herr_t H5CX_pop(void);
 #define FUNC_ENTER_API_INIT(err)                                                                             \
     /* Initialize the library */                                                                             \
     if (!H5_INIT_GLOBAL && !H5_TERM_GLOBAL) {                                                                \
-        H5_INIT_GLOBAL = TRUE;                                                                               \
         if (H5_init_library() < 0)                                                                           \
             HGOTO_ERROR(H5E_FUNC, H5E_CANTINIT, err, "library initialization failed")                        \
     } /* end if */                                                                                           \
@@ -2603,7 +2602,6 @@ extern hbool_t H5_api_entered_g; /* Has library already been entered through API
                                                                                                              \
     /* Initialize the library or bust */                                                                     \
     if (!H5_INIT_GLOBAL && !H5_TERM_GLOBAL) {                                                                \
-        H5_INIT_GLOBAL = TRUE;                                                                               \
         if (H5_init_library() < 0) {                                                                         \
             /* (Can't use H5E_THROW here) */                                                                 \
             H5E_PRINTF(H5E_CANTINIT, "interface initialization failed");                                     \
diff --git a/src/H5system.c b/src/H5system.c
index b2a2668d209..a817b7cd78b 100644
--- a/src/H5system.c
+++ b/src/H5system.c
@@ -25,6 +25,7 @@
 /****************/
 /* Module Setup */
 /****************/
+#include "H5module.h" /* This source code file is part of the H5 module */
 
 /***********/
 /* Headers */
@@ -347,7 +348,7 @@ H5_make_time(struct tm *tm)
      */
     long timezone = 0;
 #endif                /* defined(H5_HAVE_VISUAL_STUDIO) && (_MSC_VER >= 1900) */
-    time_t ret_value; /* Return value */
+    time_t ret_value = 0; /* Return value */
 
     FUNC_ENTER_NOAPI_NOINIT
 
diff --git a/src/H5timer.c b/src/H5timer.c
index 1df2d8de330..b53c3025304 100644
--- a/src/H5timer.c
+++ b/src/H5timer.c
@@ -24,6 +24,7 @@
 /****************/
 /* Module Setup */
 /****************/
+#include "H5module.h" /* This source code file is part of the H5 module */
 
 /***********/
 /* Headers */
diff --git a/src/H5trace.c b/src/H5trace.c
index 9f23d0ae648..9704fffc9b2 100644
--- a/src/H5trace.c
+++ b/src/H5trace.c
@@ -25,6 +25,7 @@
 /****************/
 /* Module Setup */
 /****************/
+#include "H5module.h" /* This source code file is part of the H5 module */
 #define H5I_FRIEND /*suppress error about including H5Ipkg      */
 
 /***********/

From 4fff3c0963a525057e7193c108c2d764c1847082 Mon Sep 17 00:00:00 2001
From: Gerd Heber <gheber@hdfgroup.org>
Date: Fri, 13 Nov 2020 09:40:46 -0600
Subject: [PATCH 05/16] H5PL (complete) and basic H5VL API documentation.

---
 src/H5PLmodule.h    |   5 +
 src/H5PLpublic.h    | 176 ++++++++++++++++++++++++++-
 src/H5VLconnector.h |  91 ++++++++++----
 src/H5VLmodule.h    |  15 +++
 src/H5VLnative.h    |   6 +
 src/H5VLpublic.h    | 287 ++++++++++++++++++++++++++++++++++++++++----
 6 files changed, 530 insertions(+), 50 deletions(-)

diff --git a/src/H5PLmodule.h b/src/H5PLmodule.h
index 8bf11ce26c7..6e6a08802cb 100644
--- a/src/H5PLmodule.h
+++ b/src/H5PLmodule.h
@@ -27,4 +27,9 @@
 #define H5_MY_PKG_ERR  H5E_PLUGIN
 #define H5_MY_PKG_INIT YES
 
+/**\defgroup H5PL H5PL
+ * \brief Plugins
+ * \todo Describe what programmatically controlling dynamically loaded plugins (H5PL) is all about
+ */
+
 #endif /* _H5PLmodule_H */
diff --git a/src/H5PLpublic.h b/src/H5PLpublic.h
index a54cce063a3..b345188cb55 100644
--- a/src/H5PLpublic.h
+++ b/src/H5PLpublic.h
@@ -28,14 +28,20 @@
  */
 #define H5PL_NO_PLUGIN "::"
 
-/* Plugin type used by the plugin library */
+//! [H5PL_type_t_snip]
+
+/**
+ * Plugin type (bit-position) used by the plugin library
+ */
 typedef enum H5PL_type_t {
-    H5PL_TYPE_ERROR  = -1, /* Error                */
-    H5PL_TYPE_FILTER = 0,  /* Filter               */
-    H5PL_TYPE_VOL    = 1,  /* VOL driver           */
-    H5PL_TYPE_NONE   = 2   /* This must be last!   */
+    H5PL_TYPE_ERROR  = -1, /**< Error                */
+    H5PL_TYPE_FILTER = 0,  /**< Filter               */
+    H5PL_TYPE_VOL    = 1,  /**< VOL driver           */
+    H5PL_TYPE_NONE   = 2   /**< Sentinel: This must be last!   */
 } H5PL_type_t;
 
+//! [H5PL_type_t_snip]
+
 /* Common dynamic plugin type flags used by the set/get_loading_state functions */
 #define H5PL_FILTER_PLUGIN 0x0001
 #define H5PL_VOL_PLUGIN    0x0002
@@ -46,14 +52,174 @@ extern "C" {
 #endif
 
 /* plugin state */
+/**
+ * \ingroup H5PL
+ * \brief Controls the loadability of dynamic plugin types
+ *
+ * \param[in] plugin_control_mask The list of dynamic plugin types to enable or disable.\n
+ *                                A plugin bit set to 0 (zero) prevents use of that dynamic plugin.\n
+ *                                A plugin bit set to 1 (one) enables use of that dynamic plugin.\n
+ *                                Setting \p plugin_control_mask to a negative value enables all dynamic
+ *                                plugin types.\n
+ *                                Setting \p plugin_control_mask to 0 (zero) disables all dynamic plugin\n
+ *                                types.
+ * \return \herr_t
+ *
+ * \details H5PLset_loading_state() uses one argument to enable or disable individual plugin types.
+ *
+ * \details The \p plugin_control_mask parameter is an encoded integer in which each bit controls a specific
+ *          plugin type. Bit positions allocated to date are specified in \ref H5PL_type_t as follows:
+ *          \snippet this H5PL_type_t_snip
+ *
+ *          A plugin bit set to 0 (zero) prevents the use of the dynamic plugin type corresponding to that bit
+ *          position. A plugin bit set to 1 (one) allows the use of that dynamic plugin type.
+ *
+ *          All dynamic plugin types can be enabled by setting \p plugin_control_mask to a negative value. A
+ *          value of 0 (zero) will disable all dynamic plugin types.
+ *
+ *          The loading of external dynamic plugins can be controlled during runtime with an environment
+ *          variable, \c HDF5_PLUGIN_PRELOAD. H5PLset_loading_state() inspects the \c HDF5_PLUGIN_PRELOAD
+ *          environment variable every time it is called. If the environment variable is set to the special
+ *          \c :: string, all dynamic plugins are disabled.
+ *
+ * \warning The environment variable \c HDF5_PLUGIN_PRELOAD controls the loading of dynamic plugin types at
+ *          runtime. If it is set to disable all plugin types, then it will disable them for \Emph{all}
+ *          running programs that access the same variable instance.
+ *
+ * \since 1.8.15
+ *
+ */
 H5_DLL herr_t  H5PLset_loading_state(unsigned int plugin_control_mask);
+/**
+ * \ingroup H5PL
+ * \brief Queries the loadability of dynamic plugin types
+ *
+ * \param[out] plugin_control_mask List of dynamic plugin types that are enabled or disabled.\n
+ *                                 A plugin bit set to 0 (zero) indicates that that the dynamic plugin type is
+ *                                 disabled.\n
+ *                                 A plugin bit set to 1 (one) indicates that that the dynamic plugin type is
+ *                                 enabled.\n
+ *                                 If the value of \p plugin_control_mask is negative, all dynamic plugin types
+ *                                 are enabled.\n
+ *                                 If the value of \p plugin_control_mask is 0 (zero), all dynamic plugins
+ *                                 are disabled.
+ * \return \herr_t
+ *
+ * \details H5PLget_loading_state() retrieves the bitmask that controls whether a certain type of plugins
+ *          (e.g.: filters, VOL drivers) will be loaded by the HDF5 library.
+ *
+ *          Bit positions allocated to date are specified in \ref H5PL_type_t as follows:
+ *          \snippet this H5PL_type_t_snip
+ *
+ * \since 1.8.15
+ *
+ */
 H5_DLL herr_t  H5PLget_loading_state(unsigned int *plugin_control_mask /*out*/);
+/**
+ * \ingroup H5PL
+ * \brief Inserts a plugin path at the end of the plugin search path list
+ *
+ * \param[in] search_path A plugin path
+ * \return \herr_t
+ *
+ * \details H5PLappend() inserts a plugin path at the end of the plugin search path list.
+ *
+ * \since 1.10.1
+ *
+ */
 H5_DLL herr_t  H5PLappend(const char *search_path);
+/**
+ * \ingroup H5PL
+ * \brief Inserts a plugin path at the beginning of the plugin search path list
+ *
+ * \param[in] search_path A plugin path
+ * \return \herr_t
+ *
+ * \details H5PLprepend() inserts a plugin path at the end of the plugin search path list.
+ *
+ * \since 1.10.1
+ *
+ */
 H5_DLL herr_t  H5PLprepend(const char *search_path);
+/**
+ * \ingroup H5PL
+ * \brief Replaces the path at the specified index in the plugin search path list
+ *
+ * \param[in] search_path A plugin path
+ * \param[in] index Index
+ * \return \herr_t
+ *
+ * \details H5PLreplace() replaces a plugin path at the specified index in the plugin search path list.
+ *
+ * \since 1.10.1
+ *
+ */
 H5_DLL herr_t  H5PLreplace(const char *search_path, unsigned int index);
+/**
+ * \ingroup H5PL
+ * \brief Inserts a path at the specified index in the plugin search path list
+ *
+ * \param[in] search_path A plugin path
+ * \param[in] index Index
+ * \return \herr_t
+ *
+ * \details H5PLinsert() inserts a plugin path at the specified index in the plugin search path list,
+ *          moving other paths after \p index.
+ *
+ * \since 1.10.1
+ *
+ */
 H5_DLL herr_t  H5PLinsert(const char *search_path, unsigned int index);
+/**
+ * \ingroup H5PL
+ * \brief Removes a plugin path at a specified index from the plugin search path list
+ *
+ * \param[in] index Index
+ * \return \herr_t
+ *
+ * \details H5PLremove() removes a plugin path at the specified \p index and compacts the plugin search path
+ *          list.
+ *
+ * \since 1.10.1
+ *
+ */
 H5_DLL herr_t  H5PLremove(unsigned int index);
+/**
+ * \ingroup H5PL
+ * \brief Queries the plugin search path list at the specified index
+ *
+ * \param[in] index Index
+ * \param[out] path_buf Pathname
+ * \param[in] buf_size Size of \p path_buf
+ * \return Returns the length of the path, a non-negative value, if successful; otherwise returns a negative
+ *         value.
+ *
+ * \details H5PLget() queries the plugin path at a specified index. If \p path_buf is non-NULL then it writes
+ *          up to \p buf_size bytes into that buffer and always returns the length of the path name.
+ *
+ *          If \p path_buf is NULL, this function will simply return the number of characters required to
+ *          store the path name, ignoring \p path_buf and \p buf_size.
+ *
+ *          If an error occurs then the buffer pointed to by \p path_buf (NULL or non-NULL) is unchanged and
+ *          the function returns a negative value. If a zero is returned for the name's length, then there is
+ *          no path name associated with the index. and the \p path_buf buffer will be unchanged.
+ *
+ * \since 1.10.1
+ *
+ */
 H5_DLL ssize_t H5PLget(unsigned int index, char *path_buf /*out*/, size_t buf_size);
+/**
+ * \ingroup H5PL
+ * \brief Retrieves the number of stored plugin paths
+ *
+ * \param[out] num_paths Current length of the plugin search path list
+ * \return \herr_t
+ *
+ * \details H5PLsize() retrieves the number of paths stored in the plugin search path list.
+ *
+ * \since 1.10.1
+ *
+ */
 H5_DLL herr_t  H5PLsize(unsigned int *num_paths /*out*/);
 
 #ifdef __cplusplus
diff --git a/src/H5VLconnector.h b/src/H5VLconnector.h
index 63ac9108669..2abdca3011d 100644
--- a/src/H5VLconnector.h
+++ b/src/H5VLconnector.h
@@ -438,39 +438,44 @@ typedef struct H5VL_token_class_t {
     herr_t (*from_str)(void *obj, H5I_type_t obj_type, const char *token_str, H5O_token_t *token);
 } H5VL_token_class_t;
 
-/* Class information for each VOL connector */
+/**
+ * \ingroup H5VLDEV
+ * Class information for each VOL connector
+ */
+//! [H5VL_class_t_snip]
 typedef struct H5VL_class_t {
     /* Overall connector fields & callbacks */
-    unsigned int       version;          /* VOL connector class struct version #     */
-    H5VL_class_value_t value;            /* Value to identify connector              */
-    const char *       name;             /* Connector name (MUST be unique!)         */
-    unsigned           cap_flags;        /* Capability flags for connector           */
-    herr_t (*initialize)(hid_t vipl_id); /* Connector initialization callback        */
-    herr_t (*terminate)(void);           /* Connector termination callback           */
+    unsigned int       version;          /**< VOL connector class struct version #     */
+    H5VL_class_value_t value;            /**< Value to identify connector              */
+    const char *       name;             /**< Connector name (MUST be unique!)         */
+    unsigned           cap_flags;        /**< Capability flags for connector           */
+    herr_t (*initialize)(hid_t vipl_id); /**< Connector initialization callback        */
+    herr_t (*terminate)(void);           /**< Connector termination callback           */
 
     /* VOL framework */
-    H5VL_info_class_t info_cls; /* VOL info fields & callbacks  */
-    H5VL_wrap_class_t wrap_cls; /* VOL object wrap / retrieval callbacks */
+    H5VL_info_class_t info_cls; /**< VOL info fields & callbacks  */
+    H5VL_wrap_class_t wrap_cls; /**< VOL object wrap / retrieval callbacks */
 
     /* Data Model */
-    H5VL_attr_class_t     attr_cls;     /* Attribute (H5A*) class callbacks */
-    H5VL_dataset_class_t  dataset_cls;  /* Dataset (H5D*) class callbacks   */
-    H5VL_datatype_class_t datatype_cls; /* Datatype (H5T*) class callbacks  */
-    H5VL_file_class_t     file_cls;     /* File (H5F*) class callbacks      */
-    H5VL_group_class_t    group_cls;    /* Group (H5G*) class callbacks     */
-    H5VL_link_class_t     link_cls;     /* Link (H5L*) class callbacks      */
-    H5VL_object_class_t   object_cls;   /* Object (H5O*) class callbacks    */
+    H5VL_attr_class_t     attr_cls;     /**< Attribute (H5A*) class callbacks */
+    H5VL_dataset_class_t  dataset_cls;  /**< Dataset (H5D*) class callbacks   */
+    H5VL_datatype_class_t datatype_cls; /**< Datatype (H5T*) class callbacks  */
+    H5VL_file_class_t     file_cls;     /**< File (H5F*) class callbacks      */
+    H5VL_group_class_t    group_cls;    /**< Group (H5G*) class callbacks     */
+    H5VL_link_class_t     link_cls;     /**< Link (H5L*) class callbacks      */
+    H5VL_object_class_t   object_cls;   /**< Object (H5O*) class callbacks    */
 
     /* Infrastructure / Services */
-    H5VL_introspect_class_t introspect_cls; /* Container/connector introspection class callbacks */
-    H5VL_request_class_t    request_cls;    /* Asynchronous request class callbacks */
-    H5VL_blob_class_t       blob_cls;       /* 'Blob' class callbacks */
-    H5VL_token_class_t      token_cls;      /* VOL connector object token class callbacks */
+    H5VL_introspect_class_t introspect_cls; /**< Container/connector introspection class callbacks */
+    H5VL_request_class_t    request_cls;    /**< Asynchronous request class callbacks */
+    H5VL_blob_class_t       blob_cls;       /**< 'Blob' class callbacks */
+    H5VL_token_class_t      token_cls;      /**< VOL connector object token class callbacks */
 
     /* Catch-all */
     herr_t (*optional)(void *obj, int op_type, hid_t dxpl_id, void **req,
-                       va_list arguments); /* Optional callback */
+                       va_list arguments); /**< Optional callback */
 } H5VL_class_t;
+//! [H5VL_class_t_snip]
 
 /********************/
 /* Public Variables */
@@ -485,10 +490,54 @@ extern "C" {
 #endif
 
 /* Helper routines for VOL connector authors */
+/**
+ * \ingroup H5VLDEV
+ * \brief Registers a new VOL connector
+ *
+ * \param[in] cls A pointer to the plugin structure to register
+ * \vipl_id
+ * \return \hid_t{VOL connector}
+ *
+ * \details H5VLregister_connector() registers a new VOL connector as a member
+ *          of the virtual object layer class. This VOL connector identifier is
+ *          good until the library is closed or the connector is unregistered.
+ *
+ *          \p vipl_id is either #H5P_DEFAULT or the identifier of a VOL
+ *          initialization property list of class #H5P_VOL_INITIALIZE created
+ *          with H5Pcreate(). When created, this property list contains no
+ *          library properties. If a VOL connector author decides that
+ *          initialization-specific data are needed, they can be added to the
+ *          empty list and retrieved by the connector in the VOL connector's
+ *          initialize callback. Use of the VOL initialization property list is
+ *          uncommon, as most VOL-specific properties are added to the file
+ *          access property list via the connector's API calls which set the
+ *          VOL connector for the file open/create. For more information, see
+ *          the VOL documentation.
+ *
+ *          H5VL_class_t is defined in H5VLconnector.h in the source code. It
+ *          contains class information for each VOL connector:
+ *          \snippet this H5VL_class_t_snip
+ *
+ * \todo Fix the reference to VOL documentation.
+ *
+ * \since 1.12.0
+ */
 H5_DLL hid_t H5VLregister_connector(const H5VL_class_t *cls, hid_t vipl_id);
+/**
+ * \ingroup H5VLDEV
+ */
 H5_DLL void *H5VLobject(hid_t obj_id);
+/**
+ * \ingroup H5VLDEV
+ */
 H5_DLL hid_t H5VLget_file_type(void *file_obj, hid_t connector_id, hid_t dtype_id);
+/**
+ * \ingroup H5VLDEV
+ */
 H5_DLL hid_t H5VLpeek_connector_id_by_name(const char *name);
+/**
+ * \ingroup H5VLDEV
+ */
 H5_DLL hid_t H5VLpeek_connector_id_by_value(H5VL_class_value_t value);
 
 #ifdef __cplusplus
diff --git a/src/H5VLmodule.h b/src/H5VLmodule.h
index 1ff9137e7be..91d61c94f8a 100644
--- a/src/H5VLmodule.h
+++ b/src/H5VLmodule.h
@@ -27,4 +27,19 @@
 #define H5_MY_PKG_ERR  H5E_VOL
 #define H5_MY_PKG_INIT YES
 
+/**
+ * \defgroup H5VL H5VL
+ * \brief Virtual Object Layer Interface
+ * \todo Describe concisely what the functions in this module are about.
+ *
+ * \defgroup H5VLDEF Definitions
+ * \ingroup H5VL
+ * \defgroup H5VLDEV VOL Developer
+ * \ingroup H5VL
+ * \defgroup H5VLNAT Native VOL
+ * \ingroup H5VL
+ * \defgroup H5VLPT Pass-through VOL
+ * \ingroup H5VL
+ */
+
 #endif /* _H5VLmodule_H */
diff --git a/src/H5VLnative.h b/src/H5VLnative.h
index b703c4fa3a6..b81f9c1fc4e 100644
--- a/src/H5VLnative.h
+++ b/src/H5VLnative.h
@@ -123,7 +123,13 @@ extern "C" {
 #endif
 
 /* Token <--> address converters */
+/**
+ * \ingroup H5VLNAT
+ */
 H5_DLL herr_t H5VLnative_addr_to_token(hid_t loc_id, haddr_t addr, H5O_token_t *token);
+/**
+ * \ingroup H5VLNAT
+ */
 H5_DLL herr_t H5VLnative_token_to_addr(hid_t loc_id, H5O_token_t token, haddr_t *addr);
 
 /* Not really public but must be included here */
diff --git a/src/H5VLpublic.h b/src/H5VLpublic.h
index 919a4b8c3fe..19cd2b9a478 100644
--- a/src/H5VLpublic.h
+++ b/src/H5VLpublic.h
@@ -28,39 +28,64 @@
 /* VOL connector identifier values
  * These are H5VL_class_value_t values, NOT hid_t values!
  */
-#define H5_VOL_INVALID  (-1)  /* Invalid ID for VOL connector ID */
-#define H5_VOL_NATIVE   0     /* Native HDF5 file format VOL connector */
-#define H5_VOL_RESERVED 256   /* VOL connector IDs below this value are reserved for library use */
-#define H5_VOL_MAX      65535 /* Maximum VOL connector ID */
+/**
+ * \ingroup H5VLDEF
+ * Invalid ID for VOL connector ID
+ */
+#define H5_VOL_INVALID  (-1)
+/**
+ * \ingroup H5VLDEF
+ * Native HDF5 file format VOL connector
+ */
+#define H5_VOL_NATIVE   0
+/**
+ * \ingroup H5VLDEF
+ * VOL connector IDs below this value are reserved for library use
+ */
+#define H5_VOL_RESERVED 256
+/**
+ * \ingroup H5VLDEF
+ * Maximum VOL connector ID
+ */
+#define H5_VOL_MAX      65535
 
 /*******************/
 /* Public Typedefs */
 /*******************/
 
-/*
- * VOL connector identifiers.  Values 0 through 255 are for connectors defined
- * by the HDF5 library.  Values 256 through 511 are available for testing new
- * connectors. Subsequent values should be obtained from the HDF5 development
- * team at help@hdfgroup.org.
+/**
+ * \ingroup H5VLDEF
+ *
+ * \brief VOL connector identifiers.
+ *
+ * \details Values 0 through 255 are for connectors defined by the HDF5
+ *          library. Values 256 through 511 are available for testing new
+ *          connectors. Subsequent values should be obtained from the HDF5
+ *          development team at mailto:help@hdfgroup.org.
  */
+//! [H5VL_class_value_t_snip]
 typedef int H5VL_class_value_t;
+//! [H5VL_class_value_t_snip]
 
-/* Enum type for each VOL subclass */
-/* (Used for various queries, etc) */
+/**
+ * \ingroup H5VLDEF
+ * \details Enum type for each VOL subclass
+ *          (Used for various queries, etc)
+ */
 typedef enum H5VL_subclass_t {
-    H5VL_SUBCLS_NONE,     /* Operations outside of a subclass */
-    H5VL_SUBCLS_INFO,     /* 'Info' subclass */
-    H5VL_SUBCLS_WRAP,     /* 'Wrap' subclass */
-    H5VL_SUBCLS_ATTR,     /* 'Attribute' subclass */
-    H5VL_SUBCLS_DATASET,  /* 'Dataset' subclass */
-    H5VL_SUBCLS_DATATYPE, /* 'Named datatype' subclass */
-    H5VL_SUBCLS_FILE,     /* 'File' subclass */
-    H5VL_SUBCLS_GROUP,    /* 'Group' subclass */
-    H5VL_SUBCLS_LINK,     /* 'Link' subclass */
-    H5VL_SUBCLS_OBJECT,   /* 'Object' subclass */
-    H5VL_SUBCLS_REQUEST,  /* 'Request' subclass */
-    H5VL_SUBCLS_BLOB,     /* 'Blob' subclass */
-    H5VL_SUBCLS_TOKEN     /* 'Token' subclass */
+    H5VL_SUBCLS_NONE,                  /**< Operations outside of a subclass */
+    H5VL_SUBCLS_INFO,                  /**< 'Info' subclass */
+    H5VL_SUBCLS_WRAP,                  /**< 'Wrap' subclass */
+    H5VL_SUBCLS_ATTR,                  /**< 'Attribute' subclass */
+    H5VL_SUBCLS_DATASET,               /**< 'Dataset' subclass */
+    H5VL_SUBCLS_DATATYPE,              /**< 'Named datatype' subclass */
+    H5VL_SUBCLS_FILE,                  /**< 'File' subclass */
+    H5VL_SUBCLS_GROUP,                 /**< 'Group' subclass */
+    H5VL_SUBCLS_LINK,                  /**< 'Link' subclass */
+    H5VL_SUBCLS_OBJECT,                /**< 'Object' subclass */
+    H5VL_SUBCLS_REQUEST,               /**< 'Request' subclass */
+    H5VL_SUBCLS_BLOB,                  /**< 'Blob' subclass */
+    H5VL_SUBCLS_TOKEN                  /**< 'Token' subclass */
 } H5VL_subclass_t;
 
 /********************/
@@ -75,16 +100,230 @@ typedef enum H5VL_subclass_t {
 extern "C" {
 #endif
 
+/**
+ * \ingroup H5VL
+ * \brief Registers a new VOL connector by name
+ *
+ * \param[in] connector_name Connector name
+ * \vipl_id
+ * \return \hid_t{VOL connector}
+ *
+ * \details H5VLregister_connector_by_name() registers a new VOL connector with
+ *          the name \p connector_name as a member of the virtual object layer
+ *          class. This VOL connector identifier is good until the library is
+ *          closed or the connector is unregistered.
+ *
+ *          \p vipl_id is either #H5P_DEFAULT or the identifier of a VOL
+ *          initialization property list of class #H5P_VOL_INITIALIZE created
+ *          with H5Pcreate(). When created, this property list contains no
+ *          library properties. If a VOL connector author decides that
+ *          initialization-specific data are needed, they can be added to the
+ *          empty list and retrieved by the connector in the VOL connector's
+ *          initialize callback. Use of the VOL initialization property list is
+ *          uncommon, as most VOL-specific properties are added to the file
+ *          access property list via the connector's API calls which set the
+ *          VOL connector for the file open/create. For more information, see
+ *          the VOL documentation.
+ *
+ * \todo Fix the reference to VOL documentation.
+ *
+ * \since 1.12.0
+ */
 H5_DLL hid_t   H5VLregister_connector_by_name(const char *connector_name, hid_t vipl_id);
+/**
+ * \ingroup H5VL
+ * \brief Registers a new VOL connector by value
+ *
+ * \param[in] connector_value Connector value
+ * \vipl_id
+ * \return \hid_t{VOL connector}
+ *
+ * \details H5VLregister_connector_by_value() registers a new VOL connector
+ *          with value connector_value as a member of the virtual object layer
+ *          class. This VOL connector identifier is good until the library is
+ *          closed or the connector is unregistered.
+ *
+ *          \p connector_value has a type of H5VL_class_value_t, which is
+ *          defined in H5VLpublic.h as follows:
+ *          \snippet this H5VL_class_value_t_snip
+ *
+ *          Valid VOL connector identifiers can have values from 0 through 255
+ *          for connectors defined by the HDF5 library. Values 256 through 511
+ *          are available for testing new connectors. Subsequent values should
+ *          be obtained by contacting the The HDF Help Desk.
+ *
+ *          \p vipl_id is either #H5P_DEFAULT or the identifier of a VOL
+ *          initialization property list of class #H5P_VOL_INITIALIZE created
+ *          with H5Pcreate(). When created, this property list contains no
+ *          library properties. If a VOL connector author decides that
+ *          initialization-specific data are needed, they can be added to the
+ *          empty list and retrieved by the connector in the VOL connector's
+ *          initialize callback. Use of the VOL initialization property list is
+ *          uncommon, as most VOL-specific properties are added to the file
+ *          access property list via the connector's API calls which set the
+ *          VOL connector for the file open/create. For more information, see
+ *          the VOL documentation.
+ *
+ * \todo Fix the reference to VOL documentation.
+ *
+ * \since 1.12.0
+ */
 H5_DLL hid_t   H5VLregister_connector_by_value(H5VL_class_value_t connector_value, hid_t vipl_id);
+/**
+ * \ingroup H5VL
+ * \brief Tests whether a VOL class has been registered under a certain name
+ *
+ * \param[in] name Alleged name of connector
+ * \return \htri_t
+ *
+ * \details H5VLis_connector_registered_by_name() tests whether a VOL class has
+ *          been registered or not, according to the supplied connector name
+ *          \p name.
+ *
+ * \since 1.12.0
+ */
 H5_DLL htri_t  H5VLis_connector_registered_by_name(const char *name);
+/**
+ * \ingroup H5VL
+ * \brief Tests whether a VOL class has been registered for a given value
+ *
+ * \param[in] connector_value Connector value
+ * \return \htri_t
+ *
+ * \details H5VLis_connector_registered_by_value() tests whether a VOL class
+ *          has been registered, according to the supplied connector value \p
+ *          connector_value.
+ *
+ *          \p connector_value has a type of H5VL_class_value_t, which is
+ *          defined in H5VLpublic.h as follows:
+ *          \snippet this H5VL_class_value_t_snip
+ *
+ *          Valid VOL connector identifiers can have values from 0 through 255
+ *          for connectors defined by the HDF5 library. Values 256 through 511
+ *          are available for testing new connectors. Subsequent values should
+ *          be obtained by contacting the The HDF Help Desk.
+ *
+ * \since 1.12.0
+ */
 H5_DLL htri_t  H5VLis_connector_registered_by_value(H5VL_class_value_t connector_value);
+/**
+ * \ingroup H5VL
+ * \brief Retrieves the VOL connector identifier for a given object identifier
+ *
+ * \obj_id
+ * \return \hid_t{VOL connector}
+ *
+ * \details H5VLget_connector_id() retrieves the registered VOL connector
+ *          identifier for the specified object identifier \p obj_id. The VOL
+ *          connector identifier must be closed with H5VLclose() when no longer
+ *          in use.
+ *
+ * \since 1.12.0
+ */
 H5_DLL hid_t   H5VLget_connector_id(hid_t obj_id);
+/**
+ * \ingroup H5VL
+ * \brief Retrieves the identifier for a registered VOL connector name
+ *
+ * \param[in] name Connector name
+ * \return \hid_t{VOL connector}
+ *
+ * \details H5VLget_connector_id_by_name() retrieves the identifier for a
+ *          registered VOL connector with the name \p name. The identifier must
+ *          be closed with H5VLclose() when no longer in use.
+ *
+ * \since 1.12.0
+ */
 H5_DLL hid_t   H5VLget_connector_id_by_name(const char *name);
+/**
+ * \ingroup H5VL
+ * \brief Retrieves the identifier for a registered VOL connector value
+ *
+ * \param[in] connector_value Connector value
+ * \return \hid_t{VOL connector}
+ *
+ * \details H5VLget_connector_id_by_value() retrieves the identifier for a
+ *          registered VOL connector with the value \p connector_value. The
+ *          identifier will need to be closed by H5VLclose().
+ *
+ *          \p connector_value has a type of H5VL_class_value_t, which is
+ *          defined in H5VLpublic.h as follows:
+ *          \snippet this H5VL_class_value_t_snip
+ *
+ *          Valid VOL connector identifiers can have values from 0 through 255
+ *          for connectors defined by the HDF5 library. Values 256 through 511
+ *          are available for testing new connectors. Subsequent values should
+ *          be obtained by contacting the The HDF Help Desk.
+ *
+ * \since 1.12.0
+ */
 H5_DLL hid_t   H5VLget_connector_id_by_value(H5VL_class_value_t connector_value);
+/**
+ * \ingroup H5VL
+ * \brief Retrieves a connector name for a VOL
+ *
+ * \obj_id{id} or file identifier
+ * \param[out] name Connector name
+ * \param[in] size Maximum length of the name to retrieve
+ * \return Returns the length of the connector name on success, and a negative value on failure.
+ *
+ * \details H5VLget_connector_name() retrieves up to \p size elements of the
+ *          VOL name \p name associated with the object or file identifier \p
+ *          id.
+ *
+ *          Passing in a NULL pointer for size will return the size of the
+ *          connector name. This can be used to determine the size of the
+ *          buffer to allocate for the name.
+ *
+ * \since 1.12.0
+ */
 H5_DLL ssize_t H5VLget_connector_name(hid_t id, char *name /*out*/, size_t size);
+/**
+ * \ingroup H5VL
+ * \brief Closes a VOL connector identifier
+ *
+ * \param[in] connector_id Connector identifier
+ * \return \herr_t
+ *
+ * \details H5VLclose() closes a VOL connector identifier. This does not affect
+ *          the file access property lists which have been defined to use this
+ *          VOL connector or files which are already opened under this
+ *          connector.
+ *
+ * \since 1.12.0
+ */
 H5_DLL herr_t  H5VLclose(hid_t connector_id);
+/**
+ * \ingroup H5VL
+ * \brief Removes a VOL connector identifier from the library
+ *
+ * \param[in] connector_id Connector identifier
+ * \return \herr_t
+ *
+ * \details H5VLunregister_connector() removes a VOL connector identifier from
+ *          the library. This does not affect the file access property lists
+ *          which have been defined to use the VOL connector or any files which
+ *          are already opened with this connector.
+ *
+ * \attention H5VLunregister_connector() will fail if attempting to unregister
+ *            the native VOL connector.
+ *
+ * \since 1.12.0
+ */
 H5_DLL herr_t  H5VLunregister_connector(hid_t connector_id);
+/**
+ * \ingroup H5VL
+ * \brief Determine if a VOL connector supports a particular
+ *        optional callback operation.
+ *
+ * \obj_id
+ * \param[in] subcls VOL subclass
+ * \param[in] opt_type Option type
+ * \param[out] supported Flag
+ * \return \herr_t
+ *
+ * \since 1.12.0
+ */
 H5_DLL herr_t  H5VLquery_optional(hid_t obj_id, H5VL_subclass_t subcls, int opt_type, hbool_t *supported);
 
 #ifdef __cplusplus

From 4a12e1b94340b1c9fac39298ec4a3e7412544306 Mon Sep 17 00:00:00 2001
From: Gerd Heber <gheber@hdfgroup.org>
Date: Fri, 13 Nov 2020 10:07:46 -0600
Subject: [PATCH 06/16] Added H5I API docs.

---
 src/H5Imodule.h |   5 +
 src/H5Ipublic.h | 619 +++++++++++++++++++++++++++++++++++++++++++++---
 2 files changed, 591 insertions(+), 33 deletions(-)

diff --git a/src/H5Imodule.h b/src/H5Imodule.h
index 62b1406312a..4e08098cf96 100644
--- a/src/H5Imodule.h
+++ b/src/H5Imodule.h
@@ -29,4 +29,9 @@
 #define H5_MY_PKG_ERR  H5E_ATOM
 #define H5_MY_PKG_INIT NO
 
+/**\defgroup H5I H5I
+ * \brief Identifier Interface
+ * \todo Describe concisely what the functions in this module are about.
+ */
+
 #endif /* _H5Imodule_H */
diff --git a/src/H5Ipublic.h b/src/H5Ipublic.h
index 697777c7734..a7c496199ca 100644
--- a/src/H5Ipublic.h
+++ b/src/H5Ipublic.h
@@ -21,37 +21,41 @@
 /* Public headers needed by this file */
 #include "H5public.h"
 
-/*
- * Library type values.  Start with `1' instead of `0' because it makes the
- * tracing output look better when hid_t values are large numbers.  Change the
- * TYPE_BITS in H5I.c if the MAXID gets larger than 32 (an assertion will
- * fail otherwise).
+/**
+ * Library type values.
+ * \internal Library type values.  Start with `1' instead of `0' because it
+ *           makes the tracing output look better when hid_t values are large
+ *           numbers. Change the TYPE_BITS in H5I.c if the MAXID gets larger
+ *           than 32 (an assertion will fail otherwise).
  *
- * When adding types here, add a section to the 'misc19' test in test/tmisc.c
- * to verify that the H5I{inc|dec|get}_ref() routines work correctly with it.
+ *           When adding types here, add a section to the 'misc19' test in
+ *           test/tmisc.c to verify that the H5I{inc|dec|get}_ref() routines
+ *           work correctly with it. \endinternal
  */
 typedef enum H5I_type_t {
-    H5I_UNINIT = (-2),  /* uninitialized type                           */
-    H5I_BADID  = (-1),  /* invalid Type                                 */
-    H5I_FILE   = 1,     /* type ID for File objects                     */
-    H5I_GROUP,          /* type ID for Group objects                    */
-    H5I_DATATYPE,       /* type ID for Datatype objects                 */
-    H5I_DATASPACE,      /* type ID for Dataspace objects                */
-    H5I_DATASET,        /* type ID for Dataset objects                  */
-    H5I_MAP,            /* type ID for Map objects                      */
-    H5I_ATTR,           /* type ID for Attribute objects                */
-    H5I_VFL,            /* type ID for virtual file layer               */
-    H5I_VOL,            /* type ID for virtual object layer             */
-    H5I_GENPROP_CLS,    /* type ID for generic property list classes    */
-    H5I_GENPROP_LST,    /* type ID for generic property lists           */
-    H5I_ERROR_CLASS,    /* type ID for error classes                    */
-    H5I_ERROR_MSG,      /* type ID for error messages                   */
-    H5I_ERROR_STACK,    /* type ID for error stacks                     */
-    H5I_SPACE_SEL_ITER, /* type ID for dataspace selection iterator     */
-    H5I_NTYPES          /* number of library types, MUST BE LAST!       */
+    H5I_UNINIT      = (-2),     /**< uninitialized type                        */
+    H5I_BADID       = (-1),     /**< invalid Type                              */
+    H5I_FILE        = 1,        /**< type ID for File objects                  */
+    H5I_GROUP,                  /**< type ID for Group objects                 */
+    H5I_DATATYPE,               /**< type ID for Datatype objects              */
+    H5I_DATASPACE,              /**< type ID for Dataspace objects             */
+    H5I_DATASET,                /**< type ID for Dataset objects               */
+    H5I_MAP,                    /**< type ID for Map objects                   */
+    H5I_ATTR,                   /**< type ID for Attribute objects             */
+    H5I_VFL,                    /**< type ID for virtual file layer            */
+    H5I_VOL,                    /**< type ID for virtual object layer          */
+    H5I_GENPROP_CLS,            /**< type ID for generic property list classes */
+    H5I_GENPROP_LST,            /**< type ID for generic property lists        */
+    H5I_ERROR_CLASS,            /**< type ID for error classes                 */
+    H5I_ERROR_MSG,              /**< type ID for error messages                */
+    H5I_ERROR_STACK,            /**< type ID for error stacks                  */
+    H5I_SPACE_SEL_ITER,         /**< type ID for dataspace selection iterator  */
+    H5I_NTYPES                  /**< number of library types, MUST BE LAST!    */
 } H5I_type_t;
 
-/* Type of atoms to return to users */
+/**
+ * Type of atoms to return to users
+ */
 typedef int64_t hid_t;
 
 #define PRIdHID PRId64
@@ -59,13 +63,18 @@ typedef int64_t hid_t;
 #define PRIXHID PRIX64
 #define PRIoHID PRIo64
 
-#define H5_SIZEOF_HID_T H5_SIZEOF_INT64_T
+/**
+ * The size of identifiers
+ */
+#define H5_SIZEOF_HID_T         H5_SIZEOF_INT64_T
 
-/* An invalid object ID. This is also negative for error return. */
-#define H5I_INVALID_HID (-1)
+/**
+ * An invalid object ID. This is also negative for error return.
+ */
+#define H5I_INVALID_HID         (-1)
 
-/*
- * Function for freeing objects. This function will be called with an object
+/**
+ * A function for freeing objects. This function will be called with an object
  * ID type number and a pointer to the object. The function should free the
  * object and return non-negative to indicate that the object
  * can be removed from the ID type. If the function returns negative
@@ -73,11 +82,19 @@ typedef int64_t hid_t;
  */
 typedef herr_t (*H5I_free_t)(void *);
 
-/* Type of the function to compare objects & keys */
+/**
+ * The type of a function to compare objects & keys
+ */
+//! [H5I_search_func_t_snip]
 typedef int (*H5I_search_func_t)(void *obj, hid_t id, void *key);
+//! [H5I_search_func_t_snip]
 
-/* Type of the H5Iiterate callback function */
+/**
+ * The type of H5Iiterate() callback functions
+ */
+//! [H5I_iterate_func_t_snip]
 typedef herr_t (*H5I_iterate_func_t)(hid_t id, void *udata);
+//! [H5I_iterate_func_t_snip]
 
 #ifdef __cplusplus
 extern "C" {
@@ -85,25 +102,561 @@ extern "C" {
 
 /* Public API functions */
 
+/**
+ * \ingroup H5I
+ *
+ * \brief Registers an object under a type and returns an ID for it
+ *
+ * \param[in] type The identifier of the type of the new ID
+ * \param[in] object Pointer to object for which a new ID is created
+ *
+ * \return \hid_t{object}
+ *
+ * \details H5Iregister() allocates and returns a new ID for an object.
+ *
+ * \details The \p type parameter is the identifier for the ID type to which
+ *          this new ID will belong. This identifier must have been created by
+ *          a call to H5Iregister_type().
+ *
+ * \details The \p object parameter is a pointer to the memory which the new ID
+ *          will be a reference to. This pointer will be stored by the library
+ *          and returned via a call to H5Iobject_verify().
+ *
+ */
 H5_DLL hid_t      H5Iregister(H5I_type_t type, const void *object);
+/**
+ * \ingroup H5I
+ *
+ * \brief Returns the object referenced by an ID
+ *
+ * \param[in] id ID to be dereferenced
+ * \param[in] id_type The identifier type
+
+ *
+ * \return Pointer to the object referenced by \p id on success, NULL on failure.
+ *
+ * \details H5Iobject_verify() returns a pointer to the memory referenced by id
+ *          after verifying that \p id is of type \p id_type. This function is
+ *          analogous to dereferencing a pointer in C with type checking.
+ *
+ * \note H5Iobject_verify() does not change the ID it is called on in any way
+ *       (as opposed to H5Iremove_verify(), which removes the ID from its
+ *       type’s hash table).
+ *
+ * \see H5Iregister()
+ *
+ */
 H5_DLL void *     H5Iobject_verify(hid_t id, H5I_type_t id_type);
+/**
+ * \ingroup H5I
+ *
+ * \brief Removes an ID from its type
+ *
+ * \param[in] id The ID to be removed from its type
+ * \param[in] id_type The identifier type
+
+ *
+ * \return Returns a pointer to the memory referred to by \p id on success,
+ *         NULL on failure.
+ *
+ * \details H5Iremove_verify() first ensures that \p id belongs to \p id_type.
+ *          If so, it removes \p id from its type and returns the pointer
+ *          to the memory it referred to. This pointer is the same pointer that
+ *          was placed in storage by H5Iregister(). If id does not belong to
+ *          \p id_type, then NULL is returned.
+ *
+ *          The \p id parameter is the ID which is to be removed from its type.
+ *
+ *          The \p type parameter is the identifier for the ID type which \p id
+ *          is supposed to belong to. This identifier must have been created by
+ *          a call to H5Iregister_type().
+ *
+ * \note This function does NOT deallocate the memory that \p id refers to.
+ *       The pointer returned by H5Iregister() must be deallocated by the user
+ *       to avoid memory leaks.
+ *
+ */
 H5_DLL void *     H5Iremove_verify(hid_t id, H5I_type_t id_type);
+/**
+ * \ingroup H5I
+ *
+ * \brief Retrieves the type of an object
+ *
+ * \obj_id{id}
+ *
+ * \return Returns the object type if successful; otherwise #H5I_BADID.
+ *
+ * \details H5Iget_type() retrieves the type of the object identified by
+ *          \p id.
+ *
+ *          Valid types returned by the function are:
+ *          \id_types
+ *
+ *          If no valid type can be determined or the identifier submitted is
+ *          invalid, the function returns #H5I_BADID.
+ *
+ *          This function is of particular use in determining the type of
+ *          object closing function (H5Dclose(), H5Gclose(), etc.) to call
+ *          after a call to H5Rdereference().
+ *
+ * \note Note that this function returns only the type of object that \p id
+ *       would identify if it were valid; it does not determine whether \p id
+ *       is valid identifier. Validity can be determined with a call to
+ *       H5Iis_valid().
+ *
+ */
 H5_DLL H5I_type_t H5Iget_type(hid_t id);
+/**
+ * \ingroup H5I
+ *
+ * \brief Retrieves an identifier for the file containing the specified object
+ *
+ * \obj_id{id}
+ *
+ * \return \hid_t{file}
+ *
+ * \details H5Iget_file_id() returns the identifier of the file associated with
+ *          the object referenced by \p id.
+ *
+ * \note Note that the HDF5 library permits an application to close a file
+ *       while objects within the file remain open. If the file containing the
+ *       object \p id is still open, H5Iget_file_id() will retrieve the
+ *       existing file identifier. If there is no existing file identifier for
+ *       the file, i.e., the file has been closed, H5Iget_file_id() will reopen
+ *       the file and return a new file identifier. In either case, the file
+ *       identifier must eventually be released using H5Fclose().
+ *
+ * \since 1.6.3
+ *
+ */
 H5_DLL hid_t      H5Iget_file_id(hid_t id);
+/**
+ * \ingroup H5I
+ *
+ * \brief Retrieves a name of an object based on the object identifier
+ *
+ * \obj_id{id}
+ * \param[out] name A buffer for thename associated with the identifier
+ * \param[in] size The size of the \p name buffer; usually the size of
+ *                 the name in bytes plus 1 for a NULL terminator
+ *
+ * \return ssize_t
+ *
+ * \details H5Iget_name() retrieves a name for the object identified by \p id.
+ *
+ * \details Up to size characters of the name are returned in \p name;
+ *          additional characters, if any, are not returned to the user
+ *          application.
+ *
+ *          If the length of the name, which determines the required value of
+ *          \p size, is unknown, a preliminary H5Iget_name() call can be made.
+ *          The return value of this call will be the size in bytes of the
+ *          object name. That value, plus 1 for a NULL terminator, is then
+ *          assigned to size for a second H5Iget_name() call, which will
+ *          retrieve the actual name.
+ *
+ *          If the object identified by \p id is an attribute, as determined
+ *          via H5Iget_type(), H5Iget_name() retrieves the name of the object
+ *          to which that attribute is attached. To retrieve the name of the
+ *          attribute itself, use H5Aget_name().
+ *
+ *          If there is no name associated with the object identifier or if the
+ *          name is NULL, H5Iget_name() returns 0 (zero).
+ *
+ * \note Note that an object in an HDF5 file may have multiple paths if there
+ *       are multiple links pointing to it. This function may return any one of
+ *       these paths. When possible, H5Iget_name() returns the path with which
+ *       the object was opened.
+ *
+ * \since 1.6.0
+ *
+ */
 H5_DLL ssize_t    H5Iget_name(hid_t id, char *name /*out*/, size_t size);
+/**
+ * \ingroup H5I
+ *
+ * \brief Increments the reference count for an object
+ *
+ * \obj_id{id}
+ *
+ * \return Returns a non-negative reference count of the object ID after
+ *         incrementing it if successful; otherwise a negative value is
+ *         returned.
+ *
+ * \details H5Iinc_ref() increments the reference count of the object
+ *          identified by \p id.
+ *
+ *          The reference count for an object ID is attached to the information
+ *          about an object in memory and has no relation to the number of
+ *          links to an object on disk.
+ *
+ *          The reference count for a newly created object will be 1. Reference
+ *          counts for objects may be explicitly modified with this function or
+ *          with H5Idec_ref(). When an object ID's reference count reaches
+ *          zero, the object will be closed. Calling an object ID's \c close
+ *          function decrements the reference count for the ID which normally
+ *          closes the object, but if the reference count for the ID has been
+ *          incremented with this function, the object will only be closed when
+ *          the reference count reaches zero with further calls to H5Idec_ref()
+ *          or the object ID's \c close function.
+ *
+ *          If the object ID was created by a collective parallel call (such as
+ *          H5Dcreate(), H5Gopen(), etc.), the reference count should be
+ *          modified by all the processes which have copies of the ID.
+ *          Generally this means that group, dataset, attribute, file and named
+ *          datatype IDs should be modified by all the processes and that all
+ *          other types of IDs are safe to modify by individual processes.
+ *
+ *          This function is of particular value when an application is
+ *          maintaining multiple copies of an object ID. The object ID can be
+ *          incremented when a copy is made. Each copy of the ID can then be
+ *          safely closed or decremented and the HDF5 object will be closed
+ *          when the reference count for that that object drops to zero.
+ *
+ * \since 1.6.2
+ *
+ */
 H5_DLL int        H5Iinc_ref(hid_t id);
+/**
+ * \ingroup H5I
+ *
+ * \brief Decrements the reference count for an object
+ *
+ * \obj_id{id}
+ *
+ * \return Returns a non-negative reference count of the object ID after
+ *         decrementing it, if successful; otherwise a negative value is
+ *         returned.
+ *
+ * \details H5Idec_ref() decrements the reference count of the object
+ *          identified by \p id.
+ *
+ *          The reference count for an object ID is attached to the information
+ *          about an object in memory and has no relation to the number of
+ *          links to an object on disk.
+ *
+ *          The reference count for a newly created object will be 1. Reference
+ *          counts for objects may be explicitly modified with this function or
+ *          with H5Iinc_ref(). When an object identifier’s reference count
+ *          reaches zero, the object will be closed. Calling an object
+ *          identifier’s \c close function decrements the reference count for
+ *          the identifier which normally closes the object, but if the
+ *          reference count for the identifier has been incremented with
+ *          H5Iinc_ref(), the object will only be closed when the reference
+ *          count reaches zero with further calls to this function or the
+ *          object identifier’s \c close function.
+ *
+ *          If the object ID was created by a collective parallel call (such as
+ *          H5Dcreate(), H5Gopen(), etc.), the reference count should be
+ *          modified by all the processes which have copies of the ID.
+ *          Generally this means that group, dataset, attribute, file and named
+ *          datatype IDs should be modified by all the processes and that all
+ *          other types of IDs are safe to modify by individual processes.
+ *
+ *          This function is of particular value when an application is
+ *          maintaining multiple copies of an object ID. The object ID can be
+ *          incremented when a copy is made. Each copy of the ID can then be
+ *          safely closed or decremented and the HDF5 object will be closed
+ *          when the reference count for that that object drops to zero.
+ *
+ * \since 1.6.2
+ *
+ */
 H5_DLL int        H5Idec_ref(hid_t id);
+/**
+ * \ingroup H5I
+ *
+ * \brief Retrieves the reference count for an object
+ *
+ * \obj_id{id}
+ *
+ * \return Returns a non-negative current reference count of the object
+ *         identifier if successful; otherwise a negative value is returned.
+ *
+ * \details H5Iget_ref() retrieves the reference count of the object identified
+ *          by \p id.
+ *
+ *          The reference count for an object identifier is attached to the
+ *          information about an object in memory and has no relation to the
+ *          number of links to an object on disk.
+ *
+ *          The function H5Iis_valid() is used to determine whether a specific
+ *          object identifier is valid.
+ *
+ * \since 1.6.2
+ *
+ */
 H5_DLL int        H5Iget_ref(hid_t id);
+/**
+ * \ingroup H5I
+ *
+ * \brief Creates and returns a new ID type
+ *
+ * \param[in] hash_size Minimum hash table size (in entries) used to store IDs
+ *                      for the new type
+ * \param[in] reserved Number of reserved IDs for the new type
+ * \param[in] free_func Function used to deallocate space for a single ID
+ *
+ * \return Returns the type identifier on success, negative on failure.
+ *
+ * \details H5Iregister_type() allocates space for a new ID type and returns an
+ *          identifier for it.
+ *
+ *          The \p hash_size parameter indicates the minimum size of the hash
+ *          table used to store IDs in the new type.
+ *
+ *          The \p reserved parameter indicates the number of IDs in this new
+ *          type to be reserved. Reserved IDs are valid IDs which are not
+ *          associated with any storage within the library.
+ *
+ *          The \p free_func parameter is a function pointer to a function
+ *          which returns an herr_t and accepts a \c void*. The purpose of this
+ *          function is to deallocate memory for a single ID. It will be called
+ *          by H5Iclear_type() and H5Idestroy_type() on each ID. This function
+ *          is NOT called by H5Iremove_verify(). The \c void* will be the same
+ *          pointer which was passed in to the H5Iregister() function. The \p
+ *          free_func function should return 0 on success and -1 on failure.
+ *
+ */
 H5_DLL H5I_type_t H5Iregister_type(size_t hash_size, unsigned reserved, H5I_free_t free_func);
+/**
+ * \ingroup H5I
+ *
+ * \brief Deletes all identifiers of the given type
+ *
+ * \param[in] type Identifier of identifier type which is to be cleared of identifiers
+ * \param[in] force Whether or not to force deletion of all identifiers
+ *
+ * \return \herr_t
+ *
+ * \details H5Iclear_type() deletes all identifiers of the type identified by
+ *          the argument \p type.
+ *
+ *          The identifier type's free function is first called on all of these
+ *          identifiers to free their memory, then they are removed from the
+ *          type.
+ *
+ *          If the \p force flag is set to false, only those identifiers whose
+ *          reference counts are equal to 1 will be deleted, and all other
+ *          identifiers will be entirely unchanged. If the force flag is true,
+ *          all identifiers of this type will be deleted.
+ *
+ */
 H5_DLL herr_t     H5Iclear_type(H5I_type_t type, hbool_t force);
+/**
+ * \ingroup H5I
+ *
+ * \brief Removes an identifier type and all identifiers within that type
+ *
+ * \param[in] type Identifier of identifier type which is to be destroyed
+ *
+ * \return \herr_t
+ *
+ * \details H5Idestroy_type deletes an entire identifier type \p type. All
+ *          identifiers of this type are destroyed and no new identifiers of
+ *          this type can be registered.
+ *
+ *          The type’s free function is called on all of the identifiers which
+ *          are deleted by this function, freeing their memory. In addition,
+ *          all memory used by this type’s hash table is freed.
+ *
+ *          Since the H5I_type_t values of destroyed identifier types are
+ *          reused when new types are registered, it is a good idea to set the
+ *          variable holding the value of the destroyed type to #H5I_UNINIT.
+ *
+ */
 H5_DLL herr_t     H5Idestroy_type(H5I_type_t type);
+/**
+ * \ingroup H5I
+ *
+ * \brief Increments the reference count on an ID type
+ *
+ * \param[in] type The identifier of the type whose reference count is to be incremented
+ *
+ * \return Returns the current reference count on success, negative on failure.
+ *
+ * \details H5Iinc_type_ref() increments the reference count on an ID type. The
+ *          reference count is used by the library to indicate when an ID type
+ *          can be destroyed.
+ *
+ *          The type parameter is the identifier for the ID type whose
+ *          reference count is to be incremented. This identifier must have
+ *          been created by a call to H5Iregister_type().
+ *
+ */
 H5_DLL int        H5Iinc_type_ref(H5I_type_t type);
+/**
+ * \ingroup H5I
+ *
+ * \brief Decrements the reference count on an identifier type
+ *
+ * \param[in] type The identifier of the type whose reference count is to be decremented
+ *
+ * \return Returns the current reference count on success, negative on failure.
+ *
+ * \details H5Idec_type_ref() decrements the reference count on an identifier
+ *          type. The reference count is used by the library to indicate when
+ *          an identifier type can be destroyed. If the reference count reaches
+ *          zero, this function will destroy it.
+ *
+ *          The type parameter is the identifier for the identifier type whose
+ *          reference count is to be decremented. This identifier must have
+ *          been created by a call to H5Iregister_type().
+ *
+ */
 H5_DLL int        H5Idec_type_ref(H5I_type_t type);
+/**
+ * \ingroup H5I
+ *
+ * \brief Retrieves the reference count on an ID type
+ *
+ * \param[in] type The identifier of the type whose reference count is to be retieved
+ *
+ * \return Returns the current reference count on success, negative on failure.
+ *
+ * \details H5Iget_type_ref() retrieves the reference count on an ID type. The
+ *          reference count is used by the library to indicate when an ID type
+ *          can be destroyed.
+ *
+ *          The type parameter is the identifier for the ID type whose
+ *          reference count is to be retrieved. This identifier must have been
+ *          created by a call to H5Iregister_type().
+ *
+ */
 H5_DLL int        H5Iget_type_ref(H5I_type_t type);
+/**
+ * \ingroup H5I
+ *
+ * \brief Finds the memory referred to by an ID within the given ID type such
+ *        that some criterion is satisfied
+ *
+ * \param[in] type The identifier of the type to be searched
+ * \param[in] func The function defining the search criteria
+ * \param[in] key A key for the search function
+ *
+ * \return Returns a pointer to the object which satisfies the search function
+ *         on success, NULL on failure.
+ *
+ * \details H5Isearch() searches through a given ID type to find an object that
+ *          satisfies the criteria defined by \p func. If such an object is
+ *          found, the pointer to the memory containing this object is
+ *          returned. Otherwise, NULL is returned. To do this, \p func is
+ *          called on every member of type \p type. The first member to satisfy
+ *          \p func is returned.
+ *
+ *          The \p type parameter is the identifier for the ID type which is to
+ *          be searched. This identifier must have been created by a call to
+ *          H5Iregister_type().
+ *
+ *          The parameter \p func is a function pointer to a function which
+ *          takes three parameters. The first parameter is a \c void* and will
+ *          be a pointer to the object to be tested. This is the same object
+ *          that was placed in storage using H5Iregister(). The second
+ *          parameter is a hid_t and is the ID of the object to be tested. The
+ *          last parameter is a \c void*. This is the \p key parameter and can
+ *          be used however the user finds helpful, or it can be ignored if it
+ *          is not needed. \p func returns 0 if the object it is testing does
+ *          not pass its criteria. A non-zero value should be returned if the
+ *          object does pass its criteria. H5I_search_func_t is defined in
+ *          H5Ipublic.h and is shown below.
+ *          \snippet this H5I_search_func_t_snip
+ *          The \p key parameter will be passed to the search function as a
+ *          parameter. It can be used to further define the search at run-time.
+ *
+ */
 H5_DLL void *     H5Isearch(H5I_type_t type, H5I_search_func_t func, void *key);
+/**
+ * \ingroup H5I
+ *
+ * \brief Calls a callback for each member of the identifier type specified
+ *
+ * \param[in] type The identifier type
+ * \param[in] op The callback function
+ * \param[in,out] op_data The data for the callback function
+ *
+ * \return The last value returned by \p op
+ *
+ * \details H5Iiterate() calls the callback function \p op for each member of
+ *          the identifier type \p type. The callback function type for \p op,
+ *          H5I_iterate_func_t, is defined in H5Ipublic.h as:
+ *          \snippet this H5I_iterate_func_t_snip
+ *          \p op takes as parameters the identifier and a pass through of
+ *          \p op_data, and returns an herr_t.
+ *
+ *          A positive return from op will cause the iteration to stop and
+ *          H5Iiterate() will return the value returned by \p op. A negative
+ *          return from \p op will cause the iteration to stop and H5Iiterate()
+ *          will return failure. A zero return from \p op will allow iteration
+ *          to continue, as long as there are other identifiers remaining in
+ *          type.
+ *
+ * \since 1.12.0
+ *
+ */
 H5_DLL herr_t     H5Iiterate(H5I_type_t type, H5I_iterate_func_t op, void *op_data);
+/**
+ * \ingroup H5I
+ *
+ * \brief Returns the number of identifiers in a given identifier type
+ *
+ * \param[in] type The identifier type
+ * \param[out] num_members Number of identifiers of the specified identifier type
+ *
+ * \return \herr_t
+ *
+ * \details H5Inmembers() returns the number of identifiers of the identifier
+ *          type specified in \p type.
+ *
+ *          The number of identifiers is returned in \p num_members. If no
+ *          identifiers of this type have been registered, the type does not
+ *          exist, or it has been destroyed, \p num_members is returned with
+ *          the value 0.
+ *
+ */
 H5_DLL herr_t     H5Inmembers(H5I_type_t type, hsize_t *num_members);
+/**
+ * \ingroup H5I
+ *
+ * \brief Determines whether an identifier type is registered
+ *
+ * \param[in] type Identifier type
+ *
+ * \return \htri_t
+ *
+ * \details H5Itype_exists() determines whether the given identifier type,
+ *          \p type, is registered with the library.
+ *
+ * \since 1.8.0
+ *
+ */
 H5_DLL htri_t     H5Itype_exists(H5I_type_t type);
+/**
+ * \ingroup H5I
+ *
+ * \brief Determines whether an identifier is valid
+ *
+ * \obj_id{id}
+ *
+ * \return \htri_t
+ *
+ * \details H5Iis_valid() determines whether the identifier \p id is valid.
+ *
+ * \details Valid identifiers are those that have been obtained by an
+ *          application and can still be used to access the original target.
+ *          Examples of invalid identifiers include:
+ *          \li Out of range values: negative, for example
+ *          \li Previously-valid identifiers that have been released:
+ *              for example, a dataset identifier for which the dataset has
+ *              been closed
+ *
+ *          H5Iis_valid() can be used with any type of identifier: object
+ *          identifier, property list identifier, attribute identifier, error
+ *          message identifier, etc. When necessary, a call to H5Iget_type()
+ *          can determine the type of the object that \p id identifies.
+ *
+ * \since 1.8.3
+ *
+ */
 H5_DLL htri_t     H5Iis_valid(hid_t id);
 
 #ifdef __cplusplus

From ba111e5f9449239bc51bb444f32b4b72f8505d46 Mon Sep 17 00:00:00 2001
From: Gerd Heber <gheber@hdfgroup.org>
Date: Fri, 13 Nov 2020 10:34:55 -0600
Subject: [PATCH 07/16] Added H5L API docs.

---
 src/H5Lmodule.h |    8 +
 src/H5Lpublic.h | 2035 +++++++++++++++++++++++++++++++++++++++++++++--
 2 files changed, 1957 insertions(+), 86 deletions(-)

diff --git a/src/H5Lmodule.h b/src/H5Lmodule.h
index 043a8651305..ad737d6b26b 100644
--- a/src/H5Lmodule.h
+++ b/src/H5Lmodule.h
@@ -29,4 +29,12 @@
 #define H5_MY_PKG_ERR  H5E_LINK
 #define H5_MY_PKG_INIT YES
 
+/**\defgroup H5L H5L
+ * \brief Link Interface
+ * \todo Describe concisely what the functions in this module are about.
+ *
+ * \defgroup TRAV Link Traversal
+ * \ingroup H5L
+ */
+
 #endif /* _H5Lmodule_H */
diff --git a/src/H5Lpublic.h b/src/H5Lpublic.h
index be920c224fe..14975bc81b2 100644
--- a/src/H5Lpublic.h
+++ b/src/H5Lpublic.h
@@ -34,14 +34,21 @@
 /* Public Macros */
 /*****************/
 
-/* Maximum length of a link's name */
-/* (encoded in a 32-bit unsigned integer) */
+/**
+ * \brief Maximum length of a link's name
+ *
+ * The maximum length of a link's name is encoded in a 32-bit unsigned integer.
+ */
 #define H5L_MAX_LINK_NAME_LEN ((uint32_t)(-1)) /* (4GB - 1) */
 
-/* Macro to indicate operation occurs on same location */
+/**
+ * \brief Macro to indicate operation occurs on same location
+ */
 #define H5L_SAME_LOC (hid_t)0
 
-/* Current version of the H5L_class_t struct */
+/**
+ * \brief Current version of the H5L_class_t struct
+ */
 #define H5L_LINK_CLASS_T_VERS 1
 
 #ifdef __cplusplus
@@ -52,91 +59,128 @@ extern "C" {
 /* Public Typedefs */
 /*******************/
 
-/* Link class types.
- * Values less than 64 are reserved for the HDF5 library's internal use.
- * Values 64 to 255 are for "user-defined" link class types; these types are
- * defined by HDF5 but their behavior can be overridden by users.
- * Users who want to create new classes of links should contact the HDF5
- * development team at help@hdfgroup.org.
- * These values can never change because they appear in HDF5 files.
+/**
+ * \brief  Link class types.
+ *
+ * Values less than 64 are reserved for the HDF5 library's internal use. Values
+ * 64 to 255 are for "user-defined" link class types; these types are defined
+ * by HDF5 but their behavior can be overridden by users. Users who want to
+ * create new classes of links should contact the HDF5 development team at
+ * mailto:help@hdfgroup.org. These values can never change because they appear
+ * in HDF5 files.
  */
 typedef enum {
-    H5L_TYPE_ERROR    = (-1), /* Invalid link type id         */
-    H5L_TYPE_HARD     = 0,    /* Hard link id                 */
-    H5L_TYPE_SOFT     = 1,    /* Soft link id                 */
-    H5L_TYPE_EXTERNAL = 64,   /* External link id             */
-    H5L_TYPE_MAX      = 255   /* Maximum link type id         */
+    H5L_TYPE_ERROR = (-1),      /**< Invalid link type id         */
+    H5L_TYPE_HARD = 0,          /**< Hard link id                 */
+    H5L_TYPE_SOFT = 1,          /**< Soft link id                 */
+    H5L_TYPE_EXTERNAL = 64,     /**< External link id             */
+    H5L_TYPE_MAX = 255	        /**< Maximum link type id         */
 } H5L_type_t;
-/* Maximum value link value for "built-in" link types */
+/**
+ * \brief  Maximum value link value for "built-in" link types
+ */
 #define H5L_TYPE_BUILTIN_MAX H5L_TYPE_SOFT
-/* Link ids at or above this value are "user-defined" link types. */
-#define H5L_TYPE_UD_MIN H5L_TYPE_EXTERNAL
+/**
+ * \brief Link ids at or above this value are "user-defined" link types.
+ */
+#define H5L_TYPE_UD_MIN      H5L_TYPE_EXTERNAL
+/**
+ * \brief Maximum link id value for "user-defined" link types.
+ */
+#define H5L_TYPE_UD_MAX      H5L_TYPE_MAX
 
-/* Information struct for link (for H5Lget_info2/H5Lget_info_by_idx2)
- * H5O_token_t version used in VOL layer and future public API calls
+/**
+ * \brief Information struct for links
  */
+//! [H5L_info2_t_snip]
 typedef struct {
-    H5L_type_t type;         /* Type of link                   */
-    hbool_t    corder_valid; /* Indicate if creation order is valid */
-    int64_t    corder;       /* Creation order                 */
-    H5T_cset_t cset;         /* Character set of link name     */
+    H5L_type_t          type;         /**< Type of link                   */
+    hbool_t             corder_valid; /**< Indicate if creation order is valid */
+    int64_t             corder;       /**< Creation order                 */
+    H5T_cset_t          cset;         /**< Character set of link name     */
     union {
-        H5O_token_t token;    /* Token of location that hard link points to */
-        size_t      val_size; /* Size of a soft link or UD link value */
+        H5O_token_t     token;        /**< Token of location that hard link points to */
+        size_t          val_size;     /**< Size of a soft link or user-defined link value */
     } u;
 } H5L_info2_t;
+//! [H5L_info2_t_snip]
 
 /* The H5L_class_t struct can be used to override the behavior of a
  * "user-defined" link class. Users should populate the struct with callback
  * functions defined below.
  */
 /* Callback prototypes for user-defined links */
-/* Link creation callback */
-typedef herr_t (*H5L_create_func_t)(const char *link_name, hid_t loc_group, const void *lnkdata,
-                                    size_t lnkdata_size, hid_t lcpl_id);
-
-/* Callback for when the link is moved */
-typedef herr_t (*H5L_move_func_t)(const char *new_name, hid_t new_loc, const void *lnkdata,
-                                  size_t lnkdata_size);
-
-/* Callback for when the link is copied */
-typedef herr_t (*H5L_copy_func_t)(const char *new_name, hid_t new_loc, const void *lnkdata,
-                                  size_t lnkdata_size);
-
-/* Callback during link traversal */
-typedef hid_t (*H5L_traverse_func_t)(const char *link_name, hid_t cur_group, const void *lnkdata,
-                                     size_t lnkdata_size, hid_t lapl_id, hid_t dxpl_id);
-
-/* Callback for when the link is deleted */
-typedef herr_t (*H5L_delete_func_t)(const char *link_name, hid_t file, const void *lnkdata,
-                                    size_t lnkdata_size);
-
-/* Callback for querying the link */
-/* Returns the size of the buffer needed */
-typedef ssize_t (*H5L_query_func_t)(const char *link_name, const void *lnkdata, size_t lnkdata_size,
-                                    void *buf /*out*/, size_t buf_size);
+/**
+ * \brief Link creation callback
+ */
+typedef herr_t (*H5L_create_func_t)(const char *link_name, hid_t loc_group,
+    const void *lnkdata, size_t lnkdata_size, hid_t lcpl_id);
+/**
+ * \brief Callback for link move
+ */
+typedef herr_t (*H5L_move_func_t)(const char *new_name, hid_t new_loc,
+    const void *lnkdata, size_t lnkdata_size);
+/**
+ * \brief Callback for link copy
+ */
+typedef herr_t (*H5L_copy_func_t)(const char *new_name, hid_t new_loc,
+    const void *lnkdata, size_t lnkdata_size);
+/**
+ * \brief Callback during link traversal
+ */
+typedef hid_t (*H5L_traverse_func_t)(const char *link_name, hid_t cur_group,
+    const void *lnkdata, size_t lnkdata_size, hid_t lapl_id, hid_t dxpl_id);
+/**
+ * \brief Callback for link deletion
+ */
+typedef herr_t (*H5L_delete_func_t)(const char *link_name, hid_t file,
+    const void *lnkdata, size_t lnkdata_size);
+/**
+ * \brief Callback for querying the link.
+ *
+ * Returns the size of the buffer needed.
+ */
+typedef ssize_t (*H5L_query_func_t)(const char *link_name, const void *lnkdata,
+    size_t lnkdata_size, void *buf /*out*/, size_t buf_size);
 
+/**
+ * \brief Link prototype
+ *
+ * The H5L_class_t struct can be used to override the behavior of a
+ * "user-defined" link class. Users should populate the struct with callback
+ * functions defined elsewhere.
+ */
+//! [H5L_class_t_snip]
 typedef struct {
-    int                 version;     /* Version number of this struct        */
-    H5L_type_t          id;          /* Link type ID                         */
-    const char *        comment;     /* Comment for debugging                */
-    H5L_create_func_t   create_func; /* Callback during link creation        */
-    H5L_move_func_t     move_func;   /* Callback after moving link           */
-    H5L_copy_func_t     copy_func;   /* Callback after copying link          */
-    H5L_traverse_func_t trav_func;   /* Callback during link traversal       */
-    H5L_delete_func_t   del_func;    /* Callback for link deletion           */
-    H5L_query_func_t    query_func;  /* Callback for queries                 */
+    int version;                    /**< Version number of this struct       */
+    H5L_type_t id;                  /**< Link type ID                        */
+    const char *comment;            /**< Comment for debugging               */
+    H5L_create_func_t create_func;  /**< Callback during link creation       */
+    H5L_move_func_t move_func;      /**< Callback after moving link          */
+    H5L_copy_func_t copy_func;      /**< Callback after copying link         */
+    H5L_traverse_func_t trav_func;  /**< Callback during link traversal      */
+    H5L_delete_func_t del_func;     /**< Callback for link deletion          */
+    H5L_query_func_t query_func;    /**< Callback for queries                */
 } H5L_class_t;
+//! [H5L_class_t_snip]
 
-/* Prototype for H5Literate2/H5Literate_by_name2() operator
- * H5O_token_t version used in VOL layer and future public API calls
+/**
+ * \brief Prototype for H5Literate2(), H5Literate_by_name2() operator
+ *
+ * The H5O_token_t version is used in the VOL layer and future public API calls.
  */
-typedef herr_t (*H5L_iterate2_t)(hid_t group, const char *name, const H5L_info2_t *info, void *op_data);
+//! [H5L_iterate2_t_snip]
+typedef herr_t (*H5L_iterate2_t)(hid_t group, const char *name, const H5L_info2_t *info,
+    void *op_data);
+//! [H5L_iterate2_t_snip]
 
-/* Callback for external link traversal */
-typedef herr_t (*H5L_elink_traverse_t)(const char *parent_file_name, const char *parent_group_name,
-                                       const char *child_file_name, const char *child_object_name,
-                                       unsigned *acc_flags, hid_t fapl_id, void *op_data);
+/**
+ * \brief Callback for external link traversal
+ */
+typedef herr_t (*H5L_elink_traverse_t)(const char *parent_file_name,
+    const char *parent_group_name, const char *child_file_name,
+    const char *child_object_name, unsigned *acc_flags, hid_t fapl_id,
+    void *op_data);
 
 /********************/
 /* Public Variables */
@@ -145,49 +189,1409 @@ typedef herr_t (*H5L_elink_traverse_t)(const char *parent_file_name, const char
 /*********************/
 /* Public Prototypes */
 /*********************/
+/**
+ * \ingroup H5L
+ *
+ * \brief Moves a link within an HDF5 file
+ *
+ * \fgdta_loc_id{src_loc}
+ * \param[in] src_name Original link name
+ * \fgdta_loc_id{dst_loc}
+ * \param[in] dst_name New link name
+ * \lcpl_id
+ * \lapl_id
+ *
+ * \return \herr_t
+ *
+ * \todo We need to get the location ID story straight!
+ *
+ * \details H5Lmove() moves a link within an HDF5 file. The original link,
+ *          \p src_name, is removed from \p src_loc and the new link,
+ *          \p dst_name, is inserted at dst_loc. This change is
+ *          accomplished as an atomic operation.
+ *
+ *          \p src_loc and \p src_name identify the original link.
+ *          \p src_loc is the original location identifier; \p src_name is
+ *          the path to the link and is interpreted relative to \p src_loc.
+ *
+ *          \p dst_loc and \p dst_name identify the new link. \p dst_loc is
+ *          either a file or group identifier; \p dst_name is the path to
+ *          the link and is interpreted relative to \p dst_loc.
+ *
+ *          \p lcpl_id and \p lapl_id are the link creation and link access
+ *          property lists, respectively, associated with the new link,
+ *          \p dst_name.
+ *
+ *          Through these property lists, several properties are available to
+ *          govern the behavior of H5Lmove(). The property controlling creation
+ *          of missing intermediate groups is set in the link creation property
+ *          list with H5Pset_create_intermediate_group(); H5Lmove() ignores any
+ *          other properties in the link creation property list. Properties
+ *          controlling character encoding, link traversals, and external link
+ *          prefixes are set in the link access property list with
+ *          H5Pset_char_encoding(), H5Pset_nlinks(), and H5Pset_elink_prefix(),
+ *          respectively.
+ *
+ * \note Note that H5Lmove() does not modify the value of the link; the new
+ *       link points to the same object as the original link pointed to.
+ *       Furthermore, if the object pointed to by the original link was already
+ *       open with a valid object identifier, that identifier will remain valid
+ *       after the call to H5Lmove().
+ *
+ * \attention Exercise care in moving links as it is possible to render data in
+ *            a file inaccessible with H5Lmove(). If the link being moved is on
+ *            the only path leading to an HDF5 object, that object may become
+ *            permanently inaccessible in the file.
+ *
+ * \since 1.8.0
+ *
+ *-------------------------------------------------------------------------
+ */
 H5_DLL herr_t H5Lmove(hid_t src_loc, const char *src_name, hid_t dst_loc, const char *dst_name, hid_t lcpl_id,
                       hid_t lapl_id);
+/**
+ * \ingroup H5L
+ *
+ * \brief Creates an identical copy of a link with the same creation time and
+ *        target.  The new link can have a different name and be in a different
+ *        location than the original.
+ *
+ * \fgdt_loc_id{src_loc}
+ * \param[in] src_name   Name of the link to be copied
+ * \fgdt_loc_id{dst_loc}
+ * \param[in] dst_name   Name to be assigned to the new copy
+ * \lcpl_id
+ * \lapl_id
+ * \return \herr_t
+ *
+ * \details H5Lcopy() copies the link specified by \p src_name from the location
+ *          specified by \p src_loc_id to the location specified by
+ *          \p dst_loc_id. The new copy of the link is created with the name
+ *          \p dst_name.
+ *
+ *          If \p dst_loc_id is a file identifier, \p dst_name will be
+ *          interpreted relative to that file’s root group.
+ *
+ *          The new link is created with the creation and access property lists
+ *          specified by \p lcpl_id and \p lapl_id. The interpretation of
+ *          \p lcpl_id is limited in the manner described in the next paragraph.
+ *
+ *          H5Lcopy() retains the creation time and the target of the original
+ *          link. However, since the link may be renamed, the character
+ *          encoding is that specified in \p lcpl_id rather than that of the
+ *          original link. Other link creation properties are ignored.
+ *
+ *          If the link is a soft link, also known as a symbolic link, its
+ *          target is interpreted relative to the location of the copy.
+ *
+ *          Several properties are available to govern the behavior of
+ *          H5Lcopy(). These properties are set in the link creation and access
+ *          property lists, \p lcpl_id and \p lapl_id, respectively. The
+ *          property controlling creation of missing intermediate groups is set
+ *          in the link creation property list with
+ *          H5Pset_create_intermediate_group(); this function ignores any
+ *          other properties in the link creation property list. Properties
+ *          controlling character encoding, link traversals, and external link
+ *          prefixes are set in the link access property list with
+ *          H5Pset_char_encoding(), H5Pset_nlinks(), and
+ *          H5Pset_elink_prefix().
+ *
+ * \note H5Lcopy() does not affect the object that the link points to.
+ *
+ * \attention H5Lcopy() cannot copy hard links across files as a hard link is
+ *            not valid without a target object; to copy objects from one file
+ *            to another, see H5Ocopy().
+ *
+ * \see H5Ocopy()
+ *
+ * \since 1.8.0
+ *
+ */
 H5_DLL herr_t H5Lcopy(hid_t src_loc, const char *src_name, hid_t dst_loc, const char *dst_name, hid_t lcpl_id,
                       hid_t lapl_id);
+/**
+ * \ingroup H5L
+ *
+ * \brief Creates a hard link to an object
+ *
+ * \fgdta_loc_id{cur_loc}
+ * \param[in] cur_name Name of the target object, which must already exist
+ * \fgdta_loc_id{dst_loc}
+ * \param[in] dst_name The name of the new link
+ * \lcpl_id
+ * \lapl_id
+ *
+ * \return \herr_t
+ *
+ * \todo We need to get the location ID story straight!
+ *
+ * \details H5Lcreate_hard() creates a new hard link to a pre-existing object
+ *          in an HDF5 file.
+ *
+ *          \p cur_loc and \p cur_name specify the location
+ *          and name, respectively, of the target object, i.e., the object that
+ *          the new hard link points to. \p dst_loc and \p dst_name specify the
+ *          location and name, respectively, of the new hard link.
+ *
+ *          \p cur_name and \p dst_name are interpreted relative to \p cur_loc
+ *          and \p dst_loc, respectively. If \p cur_loc and \p dst_loc are the
+ *          same location, the HDF5 macro #H5L_SAME_LOC can be used for either
+ *          parameter (but not both).
+ *
+ *          \p lcpl_id and \p lapl_id are the link creation and access property
+ *          lists associated with the new link.
+ *
+ * \note Hard and soft links are for use only if the target object is in the
+ *       current file. If the desired target object is in a different file from
+ *       the new link, an external link may be created with
+ *       H5Lcreate_external().
+ *
+ * \note The HDF5 library keeps a count of all hard links pointing to an
+ *       object; if the hard link count reaches zero (0), the object will be
+ *       deleted from the file. Creating new hard links to an object will
+ *       prevent it from being deleted if other links are removed. The
+ *       library maintains no similar count for soft links and they can dangle.
+ *
+ * \note The new link may be one of many that point to that object.
+ *
+ * \since 1.8.0
+ *
+ */
 H5_DLL herr_t H5Lcreate_hard(hid_t cur_loc, const char *cur_name, hid_t dst_loc, const char *dst_name,
                              hid_t lcpl_id, hid_t lapl_id);
+/**
+ * \ingroup H5L
+ *
+ * \brief Creates a soft link
+ *
+ * \param[in] link_target An HDF5 path name
+ * \fgdta_loc_id{link_loc_id}
+ * \param[in] link_name The name of the new link
+ * \lcpl_id
+ * \lapl_id
+ *
+ * \return \herr_t
+ *
+ * \todo We need to get the location ID story straight!
+ *
+ * \details H5Lcreate_soft() creates a new soft link to an object in an HDF5
+ *          file.
+ *
+ *          \p link_target specifies the HDF5 path name the soft link contains.
+ *          \p link_target can be an arbitrary HDF5 path name and is
+ *          interpreted only at lookup time. This path may be absolute in the
+ *          file or relative to \p link_loc_id.
+ *
+ *          \p link_loc_id and \p link_name specify the location and name,
+ *          respectively, of the new soft link. \p link_name is interpreted
+ *          relative to \p link_loc_id and must contain only the name of the soft
+ *          link; \p link_name may not contain any additional path elements.
+ *
+ *          If \p link_loc_id is a group identifier, the object pointed to by
+ *          \p link_name will be accessed as a member of that group. If
+ *          \p link_loc_id is a file identifier, the object will be accessed as a
+ *          member of the file's root group.
+ *
+ *          \p lcpl_id and \p lapl_id are the link creation and access property
+ *          lists associated with the new link.
+ *
+ *          For instance, if target_path is \c ./foo, \p link_loc_id specifies
+ *          \c ./x/y/bar, and the name of the new link is \c new_link, then a
+ *          subsequent request for \c ./x/y/bar/new_link will return same the
+ *          object as would be found at \c ./foo.
+ *
+ * \note H5Lcreate_soft() is for use only if the target object is in the
+ *       current file. If the desired target object is in a different file from
+ *       the new link, use H5Lcreate_external() to create an external link.
+ *
+ * \note Soft links and external links are also known as symbolic links as they
+ *       use a name to point to an object; hard links employ an object’s
+ *       address in the file.
+ *
+ * \note Unlike hard links, a soft link in an HDF5 file is allowed to dangle,
+ *       meaning that the target object need not exist at the time that the
+ *       link is created.
+ *
+ * \note The HDF5 library does not keep a count of soft links as it does of
+ *       hard links.
+ *
+ * \note The new link may be one of many that point to that object.
+ *
+ * \see H5Lcreate_hard(), H5Lcreate_external()
+ *
+ * \since 1.8.0
+ *
+
+ */
 H5_DLL herr_t H5Lcreate_soft(const char *link_target, hid_t link_loc_id, const char *link_name, hid_t lcpl_id,
                              hid_t lapl_id);
+/**
+ * \ingroup H5L
+ *
+ * \brief Removes a link from a group
+ *
+ * \fgdta_loc_id
+ * \param[in] name Name of the link to delete
+ * \lapl_id
+ *
+ * \return \herr_t
+ *
+ * \todo We need to get the location ID story straight!
+ *
+ * \details H5Ldelete() removes the link specified by \p name from the location
+ *          \p loc_id.
+ *
+ *          If the link being removed is a hard link, H5Ldelete() also
+ *          decrements the link count for the object to which name points.
+ *          Unless there is a duplicate hard link in that group, this action
+ *          removes the object to which name points from the group that
+ *          previously contained it.
+ *
+ *          Object headers keep track of how many hard links refer to an
+ *          object; when the hard link count, also referred to as the reference
+ *          count, reaches zero, the object can be removed from the file. The
+ *          file space associated will then be released, i.e., identified in
+ *          memory as freespace. Objects which are open are not removed until
+ *          all identifiers to the object are closed.
+ *
+ * \attention Exercise caution in the use of H5Ldelete(); if the link being
+ *            removed is on the only path leading to an HDF5 object, that
+ *            object may become permanently inaccessible in the file.
+ *
+ * \see H5Lcreate_hard(), H5Lcreate_soft(), H5Lcreate_external()
+ *
+ * \since 1.8.0
+ *
+ */
 H5_DLL herr_t H5Ldelete(hid_t loc_id, const char *name, hid_t lapl_id);
+/**
+ * \ingroup H5L
+ *
+ * \brief Removes the \Emph{n}-th link in a group
+ *
+ * \fgdta_loc_id
+ * \param[in] group_name Name of subject group
+ * \param[in] idx_type Index or field which determines the order
+ * \param[in] order Order within field or index
+ * \param[in] n Link for which to retrieve information
+ * \lapl_id
+ *
+ * \return \herr_t
+ *
+ * \todo We need to get the location ID story straight!
+ *
+ * \details H5Ldelete_by_idx() removes the \Emph{n}-th link in a group
+ *          according to the specified order, \p order, in the specified index,
+ *          \p index.
+ *
+ *          If \p loc_id specifies the group in which the link resides,
+ *          \p group_name can be a dot (\c .).
+ *
+ * \see H5Ldelete()
+ *
+ * \since 1.8.0
+ *
+ */
 H5_DLL herr_t H5Ldelete_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 H5L
+ *
+ * \brief Returns the value of a link
+ *
+ * \fgdta_loc_id
+ * \param[in] name Link name
+ * \param[out] buf The buffer to hold the link value
+ * \param[in] size Maximum number of bytes of link value to be returned
+ * \lapl_id
+ *
+ * \return \herr_t
+ *
+ * \todo We need to get the location ID story straight!
+ *
+ * \details H5Lget_val() returns tha value of link \p name. For smbolic links,
+ *          this is the path to which the link points, including the null
+ *          terminator. For external and user-defined links, it is the link
+ *          buffer.
+ *
+ *          \p size is the size of \p buf and should be the size of the link
+ *          value being returned. This size value can be determined through a
+ *          call to H5Lget_info(); it is returned in the \c val_size field of
+ *          the \ref H5L_info_t \c struct.
+ *
+ *          If \p size is smaller than the size of the returned value, then the
+ *          string stored in \p buf will be truncated to \p size bytes. For
+ *          soft links, this means that the value will not be null terminated.
+ *
+ *          In the case of external links, the target file and object names are
+ *          extracted from \p buf by calling H5Lunpack_elink_val().
+ *
+ *          The link class of link \p name can be determined with a call to
+ *          H5Lget_info().
+ *
+ *          \p lapl_id specifies the link access property list associated with
+ *          the link \p name. In the general case, when default link access
+ *          properties are acceptable, this can be passed in as #H5P_DEFAULT. An
+ *          example of a situation that requires a non-default link access
+ *          property list is when the link is an external link; an external
+ *          link may require that a link prefix be set in a link access
+ *          property list (see H5Pset_elink_prefix()).
+ *
+ *          This function should be used only after H5Lget_info() has been
+ *          called to verify that \p name is a symbolic link. This can be
+ *          deteremined from the \c link_type field of the \ref H5L_info_t
+ *          \c struct.
+ *
+ * \note This function will fail if called on a hard link.
+ *
+ * \see H5Lget_val_by_idx()
+ *
+ * \since 1.8.0
+ *
+ */
 H5_DLL herr_t H5Lget_val(hid_t loc_id, const char *name, void *buf /*out*/, size_t size, hid_t lapl_id);
+/**
+ * \ingroup H5L
+ *
+ * \brief Retrieves value of the \Emph{n}-th link in a group, according to the order within an index
+ *
+ * \fgdta_loc_id
+ * \param[in] group_name Group name
+ * \param[in] idx_type Type of index
+ * \param[in] order Order within field or index
+ * \param[in] n Link position for which to retrieve information
+ * \param[out] buf The buffer to hold the link value
+ * \param[in] size Maximum number of bytes of link value to be returned
+ * \lapl_id
+ *
+ * \return \herr_t
+ *
+ * \todo We need to get the location ID story straight!
+ *
+ * \details H5Lget_val_by_idx() retrieves the value of the \Emph{n}-th link in
+ *          a group, according to the specified order, \p order, within an
+ *          index, \p index.
+ *
+ *          For soft links, the value is an HDF5 path name.
+ *
+ *          For external links, this is a compound value containing file and
+ *          path name information; to use this external link information, it
+ *          must first be decoded with H5Lunpack_elink_val()
+ *
+ *          For user-defined links, this value will be described in the
+ *          definition of the user-defined link type.
+ *
+ *          \p loc_id specifies the location identifier of the group specified
+ *          by \p group_name.
+ *
+ *          \p group_name specifies the group in which the link exists. If
+ *          \p loc_id already specifies the group in which the link exists,
+ *          \p group_name must be a dot (\c .).
+ *
+ *          The size in bytes of link_val is specified in \p size. The size
+ *          value can be determined through a call to H5Lget_info_by_idx(); it
+ *          is returned in the \c val_size field of the \ref H5L_info_t
+ *          \c struct. If
+ *          size is smaller than the size of the returned value, then the
+ *          string stored in link_val will be truncated to size bytes. For soft
+ *          links, this means that the value will not be null terminated.
+ *
+ *          If the type of the link is unknown or uncertain, H5Lget_val_by_idx()
+ *          should be called only after the type has been determined via a call
+ *          to H5Lget_info_by_idx().
+ *
+ * \note This function will fail if called on a hard link.
+ *
+ * \see H5Lget_val()
+ *
+ * \since 1.8.0
+ *
+ */
 H5_DLL herr_t H5Lget_val_by_idx(hid_t loc_id, const char *group_name, H5_index_t idx_type,
                                 H5_iter_order_t order, hsize_t n, void *buf /*out*/, size_t size,
                                 hid_t lapl_id);
+/**
+ * \ingroup H5L
+ *
+ * \brief Determines whether a link with the specified name exists in a group
+ *
+ * \fgdta_loc_id
+ * \param[in] name Link name
+ * \lapl_id
+ *
+ * \return \herr_t
+ *
+ * \todo We need to get the location ID story straight!
+ *
+ * \details H5Lexists() allows an application to determine whether the link \p
+ *          name exists in the location specified by \p loc_id. The link may be
+ *          of any type; only the presence of a link with that name is checked.
+ *
+ *          Note that H5Lexists() verifies only that the target link exists. If
+ *          name includes either a relative path or an absolute path to the
+ *          target link, intermediate steps along the path must be verified
+ *          before the existence of the target link can be safely checked. If
+ *          the path is not verified and an intermediate element of the path
+ *          does not exist, H5Lexists() will fail. The example in the next
+ *          paragraph illustrates one step-by-step method for verifying the
+ *          existence of a link with a relative or absolute path.
+ *
+ *          \Bold{Example:} Use the following steps to verify the existence of
+ *          the link \c datasetD in the \c group group1/group2/softlink_to_group3/,
+ *          where \c group1 is a member of the group specified by \c loc_id:
+ *
+ *          1. First use H5Lexists() to verify that \c group1 exists.
+ *          2. If \c group1 exists, use H5Lexists() again, this time with name
+ *             set to \c group1/group2, to verify that \c group2 exists.
+ *          3. If \c group2 exists, use H5Lexists() with name set to
+ *             \c group1/group2/softlink_to_group3 to verify that
+ *             \c softlink_to_group3 exists.
+ *          4. If \c softlink_to_group3 exists, you can now safely use
+ *             H5Lexists() with \c name set to
+ *             \c group1/group2/softlink_to_group3/datasetD to verify that the
+ *             target link, \c datasetD, exists.
+ *
+ *          If the link to be verified is specified with an absolute path, the
+ *          same approach should be used, but starting with the first link in
+ *          the file’s root group. For instance, if \c datasetD were in
+ *          \c /group1/group2/softlink_to_group3, the first call to H5Lexists()
+ *          would have name set to \c /group1.
+ *
+ *          Note that this is an outline and does not include all necessary
+ *          details. Depending on circumstances, for example, you may need to
+ *          verify that an intermediate link points to a group and that a soft
+ *          link points to an existing target.
+ *
+ * \note The behavior of H5Lexists() was changed in the 1.10 release in the
+ *       case where the root group, \c "/", is the name of the link. This
+ *       change is described below:
+ *       <ol>
+ *       <li>Let \c file denote a valid HDF5 file identifier, and let \c lapl
+ *          denote a valid link access property list identifier. A call to
+ *          H5Lexists() with arguments \c file, \c "/", and \c lapl
+ *          returns a positive value; in other words,
+ *          \Code{H5Lexists(file, "/", lapl)} returns a positive value.
+ *          In HDF5 version 1.8.16, this function returns 0.</li>
+ *       <li>Let \c root denote a valid HDF5 group identifier that refers to the
+ *          root group of an HDF5 file, and let \c lapl denote a valid link
+ *          access property list identifier. A call to H5Lexists() with
+ *          arguments c root, \c "/", and \c lapl returns a positive value;
+ *          in other words, \Code{H5Lexists(root, "/", lapl)} returns a postive
+ *          value. In HDF5 version 1.8.16, this function returns 0.</li>
+ *       </ol>
+ *       Note that the function accepts link names and path names. This is
+ *       potentially misleading to callers, and we plan to separate the
+ *       functionality for link names and path names in a future release.
+ *
+ * \attention H5Lexists() checks the existence of only the final element in a
+ *            relative or absolute path; it does not check any other path
+ *            elements. The function will therefore fail when both of the
+ *            following conditions exist:
+ *            - \c name is not local to the group specified by \c loc_id or,
+ *              if \c loc_id is something other than a group identifier, \c name
+ *              is not local to the root group.
+ *            - Any element of the relative path or absolute path in name,
+ *              except the target link, does not exist.
+ *
+ * \version 1.10.0 Function behavior changed in this release. (See the note.)
+ * \since 1.8.0
+ *
+ */
 H5_DLL htri_t H5Lexists(hid_t loc_id, const char *name, hid_t lapl_id);
+/**
+ * \ingroup H5L
+ *
+ * \brief Returns information about a link
+ *
+ * \fgdta_loc_id
+ * \param[in] name Link name
+ * \param[out] linfo Buffer in which link information is returned
+ * \lapl_id
+ *
+ * \return \herr_t
+ *
+ * \todo We need to get the location ID story straight!
+ *
+ * \details H5Lget_info2() returns information about the specified link through
+ *          the \p linfo argument.
+ *
+ *          The location identifier, \p loc_id, specifies the location of the
+ *          link. A link name, \p name, interpreted relative to \p loc_id,
+ *          specifies the link being queried.
+ *
+ *          \p lapl_id is the link access property list associated with the
+ *          link name. In the general case, when default link access properties
+ *          are acceptable, this can be passed in as #H5P_DEFAULT. An example
+ *          of a situation that requires a non-default link access property
+ *          list is when the link is an external link; an external link may
+ *          require that a link prefix be set in a link access property list
+ *          (see H5Pset_elink_prefix()).
+ *
+ *          H5Lget_info2() returns information about name in the data structure
+ *          H5L_info2_t, which is described below and defined in H5Lpublic.h.
+ *          This structure is returned in the buffer \p linfo.
+ *          \snippet this H5L_info2_t_snip
+ *          In the above struct, \c type specifies the link class. Valid values
+ *          include the following:
+ *          \link_types
+ *          There will be additional valid values if user-defined links have
+ *          been registered.
+ *
+ *          \p corder specifies the link’s creation order position while
+ *          \p corder_valid indicates whether the value in corder is valid.
+ *
+ *          If \p corder_valid is \c TRUE, the value in \p corder is known to
+ *          be valid; if \p corder_valid is \c FALSE, the value in \p corder is
+ *          presumed to be invalid; \p corder starts at zero (0) and is
+ *          incremented by one (1) as new links are created. But
+ *          higher-numbered entries are not adjusted when a lower-numbered link
+ *          is deleted; the deleted link's creation order position is simply
+ *          left vacant. In such situations, the value of \p corder for the
+ *          last link created will be larger than the number of links remaining
+ *          in the group.
+ *
+ *          \p cset specifies the character set in which the link name is
+ *          encoded. Valid values include the following:
+ *          \csets
+ *          This value is set with H5Pset_char_encoding().
+ *
+ *          \c token is the location that a hard link points to, and
+ *          \c val_size is the size of a soft link or user defined link value.
+ *          H5O_token_t is used in the VOL layer. It is defined in H5public.h
+ *          as:
+ *          \snippet H5public.h H5O_token_t_snip
+ *
+ *          If the link is a symbolic link, \c val_size will be the length of
+ *          the link value, e.g., the length of the HDF5 path name with a null
+ *          terminator.
+ *
+ * \since 1.12.0
+ *
+ */
 H5_DLL herr_t H5Lget_info2(hid_t loc_id, const char *name, H5L_info2_t *linfo /*out*/, hid_t lapl_id);
+/**
+ * \ingroup H5L
+ *
+ * \brief Retrieves metadata for a link in a group, according to the order
+ *        within a field or index
+ *
+ * \loc_id
+ * \param[in] group_name Group name
+ * \idx_type
+ * \order
+ * \param[in] n Link position for which to retrieve information
+ * \param[out] linfo Buffer in which link information is returned
+ * \lapl_id
+ *
+ * \return \herr_t
+ *
+ * \details H5get_info_by_idx2() returns the metadata for a link in a group
+ *          according to a specified field or index and a specified order. The
+ *          link for which information is to be returned is specified by \p
+ *          idx_type, \p order, and \p n as follows:
+ *
+ *          - \p idx_type specifies the field by which the links in \p
+ *            group_name are ordered. The links may be indexed on this field,
+ *            in which case operations seeking specific links are likely to
+ *            complete more quickly.
+ *          - \p order specifies the order in which
+ *            the links are to be referenced for the purposes of this function.
+ *          - \p n specifies the position of the subject link. Note that this
+ *            count is zero-based; 0 (zero) indicates that the function will
+ *            return the value of the first link; if \p n is 5, the function
+ *            will return the value of the sixth link; etc.
+ *
+ *          For example, assume that \p idx_type, \p order, and \p n are
+ *          #H5_INDEX_NAME, #H5_ITER_DEC, and 5, respectively. #H5_INDEX_NAME
+ *          indicates that the links are accessed in lexicographic order by
+ *          their names. #H5_ITER_DEC specifies that the list be traversed in
+ *          reverse order, or in decremented order. And 5 specifies that this
+ *          call to the function will return the metadata for the 6th link
+ *          (\c n + 1) from the end.
+ *
+ *          See H5Literate2() for a list of valid values and further discussion
+ *          regarding \p idx_type and \p order.
+ *
+ *          If \p loc_id specifies the group in which the link resides,
+ *          \p group_name can be a dot (\c .).
+ *
+ * \since 1.12.0
+ *
+ * \see H5Lget_info2()
+ *
+ * \todo Document H5Lget_info_by_idx()
+ *
+ */
 H5_DLL herr_t H5Lget_info_by_idx2(hid_t loc_id, const char *group_name, H5_index_t idx_type,
                                   H5_iter_order_t order, hsize_t n, H5L_info2_t *linfo /*out*/,
                                   hid_t lapl_id);
+/**
+ * \ingroup H5L
+ *
+ * \brief Retrieves name of the \Emph{n}-th link in a group, according to the
+ *        order within a specified field or index
+ *
+ * \loc_id
+ * \param[in] group_name Group name
+ * \idx_type
+ * \order
+ * \param[in] n Link position for which to retrieve information
+ * \param[out] name Buffer in which link name is returned
+ * \param[in] size Size in bytes of \p name
+ * \lapl_id
+ *
+ * \return Returns the size of the link name if successful; otherwise returns a
+ *         negative value.
+ *
+ * \details H5get_name_by_idx() retrieves the name of the \Emph{n}-th link in a
+ *          group, according to the specified order, \p order, within a specified
+ *          field or index, \p idx_type.
+ *
+ *          \p idx_type specifies the index that is used. Valid values include
+ *          the following:
+ *          \indexes
+ *
+ *          \p order specifies the order in which objects are inspected along
+ *          the index specified in \p idx_type. Valid values include the
+ *          following:
+ *          \orders
+ *
+ *          If \p loc_id specifies the group in which the link resides,
+ *          \p group_name can be a dot (\c .).
+ *
+ *          The size in bytes of name is specified in \p size. If \p size is
+ *          unknown, it can be determined via an initial H5Lget_name_by_idx()
+ *          call with name set to NULL; the function's return value will be the
+ *          size of the name.
+ *
+ * \note Please note that in order for the specified index to correspond to the
+ *       creation order index, \p order must be set to #H5_ITER_INC or
+ *       #H5_ITER_DEC when calling H5Lget_name_by_idx(). \note The index \p n
+ *       passed to H5Lget_name_by_idx() is the index of the link within the
+ *       link table, sorted according to \p order and \p idx_type. If order is
+ *       #H5_ITER_NATIVE, then the link table is not sorted, and it does not
+ *       matter what \p idx_type is. Specifying #H5_ITER_NATIVE does not
+ *       guarantee any particular order, only that it remains consistent.
+ *
+ * \since 1.8.0
+ *
+ */
 H5_DLL ssize_t H5Lget_name_by_idx(hid_t loc_id, const char *group_name, H5_index_t idx_type,
                                   H5_iter_order_t order, hsize_t n, char *name /*out*/, size_t size,
                                   hid_t lapl_id);
+/**
+ * \ingroup TRAV
+ *
+ * \brief Iterates over links in a group, with user callback routine,
+ *        according to the order within an index.
+ *
+ * \group_id{grp_id}
+ * \idx_type
+ * \order
+ * \param[in,out] idx Pointer to an iteration index to allow
+ *                    continuing a previous iteration
+ * \op
+ * \op_data
+ * \return \success{The return value of the first operator that returns
+ *                  non-zero, or zero if all members were processed with no
+ *                  operator returning non-zero.}
+ * \return \failure{Negative if an error occurs in the library, or the negative
+ *                  value returned by one of the operators.}
+ *
+ * \details H5Literate2() iterates through the links in a file or
+ *          group, \p group_id, in the order of the specified
+ *          index, \p idx_type, using a user-defined callback routine
+ *          \p op. H5Literate2() does not recursively follow links into
+ *          subgroups of the specified group.
+ *
+ *          Three parameters are used to manage progress of the iteration:
+ *          \p idx_type, \p order, and \p idx_p.
+ *
+ *          \p idx_type specifies the index to be used. If the links have
+ *          not been indexed by the index type, they will first be sorted by
+ *          that index then the iteration will begin; if the links have been
+ *          so indexed, the sorting step will be unnecessary, so the iteration
+ *          may begin more quickly.
+ *
+ *          \p order specifies the order in which objects are to be inspected
+ *          along the index \p idx_type.
+ *
+ *          \p idx_p tracks the iteration and allows an iteration to be
+ *          resumed if it was stopped before all members were processed. It is
+ *          passed in by the application with a starting point and returned by
+ *          the library with the point at which the iteration stopped.
+ *
+ *          \p op_data is a user-defined pointer to the data required to
+ *          process links in the course of the iteration. This pointer is
+ *          passed back to each step of the iteration in the \p op callback
+ *          function's \p op_data parameter. \p op is invoked for each link
+ *          encounter.
+ *
+ *          \p op_data is passed to and from each iteration and can be used to
+ *          supply or aggregate information across iterations.
+ *
+ * \remark Same pattern of behavior as H5Giterate().
+ *
+ * \note This function is also available through the H5Literate() macro.
+ *
+ * \warning The behavior of H5Literate2() is undefined if the link
+ *          membership of \p group_id changes during the iteration.
+ *          This does not limit the ability to change link destinations
+ *          while iterating, but caution is advised.
+ *
+ *
+ * \since 1.12.0
+ *
+ * \see H5Literate_by_name2(), H5Lvisit2(), H5Lvisit_by_name2()
+ *
+ */
 H5_DLL herr_t  H5Literate2(hid_t grp_id, H5_index_t idx_type, H5_iter_order_t order, hsize_t *idx,
                            H5L_iterate2_t op, void *op_data);
+/**
+ * \ingroup TRAV
+ *
+ * \brief Iterates through links in a group
+ *
+ * \loc_id
+ * \param[in] group_name Group name
+ * \idx_type
+ * \order
+ * \param[in,out] idx iteration position at which to start (\Emph{IN}) or
+ *                    position at which an interrupted iteration may be restarted
+ *                    (\Emph{OUT})
+ * \op
+ * \op_data
+ * \lapl_id
+ * \return \success{The return value of the first operator that returns
+ *                  non-zero, or zero if all members were processed with no
+ *                  operator returning non-zero.}
+ * \return \failure{Negative if an error occurs in the library, or the negative
+ *                  value returned by one of the operators.}
+ *
+ * \details H5Literate_by_name2() iterates through the links in a group
+ *          specified by \p loc_id and \p group_name, in the order of the
+ *          specified index, \p idx_type, using a user-defined callback routine
+ *          \p op. H5Literate_by_name2() does not recursively follow links into
+ *          subgroups of the specified group.
+ *
+ *          \p idx_type specifies the index to be used. If the links have not
+ *          been indexed by the index type, they will first be sorted by that
+ *          index then the iteration will begin; if the links have been so
+ *          indexed, the sorting step will be unnecessary, so the iteration may
+ *          begin more quickly. Valid values include the following:
+ *          \indexes
+ *
+ *          \p order specifies the order in which objects are to be inspected
+ *          along the index specified in \p idx_type. Valid values include the
+ *          following:
+ *          \orders
+ *
+ *          \p idx_p allows an interrupted iteration to be resumed; it is
+ *          passed in by the application with a starting point and returned by
+ *          the library with the point at which the iteration stopped.
+ *
+ * \note H5Literate_by_name2() is not recursive. In particular, if a member of
+ *       \p group_name is found to be a group, call it \c subgroup_a,
+ *       H5Literate_by_name2() does not examine the members of \c subgroup_a.
+ *       When recursive iteration is required, the application must handle the
+ *       recursion, explicitly calling H5Literate_by_name2() on discovered
+ *       subgroups.
+ *
+ * \note H5Literate_by_name2() assumes that the membership of the group being
+ *       iterated over remains unchanged through the iteration; if any of the
+ *       links in the group change during the iteration, the function’s
+ *       behavior is undefined. Note, however, that objects pointed to by the
+ *       links can be modified.
+ *
+ * \note H5Literate_by_name2() is the same as H5Literate2(), except that
+ *       H5Literate2() always proceeds in alphanumeric order.
+ *
+ * \since 1.12.0
+ *
+ * \see H5Literate(), H5Lvisit()
+ *
+ */
 H5_DLL herr_t  H5Literate_by_name2(hid_t loc_id, const char *group_name, H5_index_t idx_type,
                                    H5_iter_order_t order, hsize_t *idx, H5L_iterate2_t op, void *op_data,
                                    hid_t lapl_id);
+/**
+ * \ingroup TRAV
+ *
+ * \brief Recursively visits all links starting from a specified group
+ *
+ * \group_id{grp_id}
+ * \idx_type
+ * \order
+ * \op
+ * \op_data
+ * \return \success{The return value of the first operator that returns
+ *                  non-zero, or zero if all members were processed with no
+ *                  operator returning non-zero.}
+ * \return \failure{Negative if an error occurs in the library, or the negative
+ *                  value returned by one of the operators.}
+ *
+ * \details H5Lvisit2() is a recursive iteration function to visit all links in
+ *          and below a group in an HDF5 file, thus providing a mechanism for
+ *          an application to perform a common set of operations across all of
+ *          those links or a dynamically selected subset. For non-recursive
+ *          iteration across the members of a group, see H5Literate2().
+ *
+ *          The group serving as the root of the iteration is specified by its
+ *          group or file identifier, \p group_id.
+ *
+ *          Two parameters are used to establish the iteration: \p idx_type and
+ *          \p order.
+ *
+ *          \p idx_type specifies the index to be used. If the links have not
+ *          been indexed by the index type, they will first be sorted by that
+ *          index then the iteration will begin; if the links have been so
+ *          indexed, the sorting step will be unnecessary, so the iteration may
+ *          begin more quickly. Valid values include the following:
+ *          \indexes
+ *
+ *          Note that the index type passed in \p idx_type is a best effort
+ *          setting. If the application passes in a value indicating iteration
+ *          in creation order and a group is encountered that was not tracked
+ *          in creation order, that group will be iterated over in
+ *          lexicographic order by name, or name order. (Name order is the
+ *          native order used by the HDF5 library and is always available.)
+ *
+ *          \p order specifies the order in which objects are to be inspected
+ *          along the index specified in \p idx_type. Valid values include the
+ *          following:
+ *          \orders
+ *
+ *          \p op is a callback function of type \ref H5L_iterate2_t that is invoked
+ *          for each link encountered.
+ *          \snippet this H5L_iterate2_t_snip
+ *
+ *          The \ref H5L_info2_t struct is defined (in H5Lpublic.h) as follows:
+ *          \snippet this H5L_info2_t_snip
+ *
+ *          The possible return values from the callback function, and the
+ *          effect of each, are as follows:
+ *          \li Zero causes the visit iterator to continue, returning zero when
+ *              all group members have been processed.
+ *          \li  A positive value causes the visit iterator to immediately
+ *               return that positive value, indicating short-circuit success.
+ *          \li A negative value causes the visit iterator to immediately
+ *              return that value, indicating failure.
+ *
+ *          The H5Lvisit2() \p op_data parameter is a user-defined pointer to
+ *          the data required to process links in the course of the iteration.
+ *          This pointer is passed back to each step of the iteration in the
+ *          \p op callback function's \p op_data parameter.
+ *
+ *          H5Lvisit2() and H5Ovisit2() are companion functions: one for
+ *          examining and operating on links; the other for examining and
+ *          operating on the objects that those links point to. Both functions
+ *          ensure that by the time the function completes successfully, every
+ *          link or object below the specified point in the file has been
+ *          presented to the application for whatever processing the
+ *          application requires.
+ *
+ * \since 1.12.0
+ *
+ * \see H5Literate()
+ *
+ */
 H5_DLL herr_t  H5Lvisit2(hid_t grp_id, H5_index_t idx_type, H5_iter_order_t order, H5L_iterate2_t op,
                          void *op_data);
+/**
+ * \ingroup TRAV
+ *
+ * \brief Recursively visits all links starting from a specified group
+ *
+ * \loc_id
+ * \param[in] group_name Group name
+ * \idx_type
+ * \order
+ * \op
+ * \op_data
+ * \lapl_id
+ *
+ * \return \herr_t
+ *
+ * \details H5Lvisit_by_name2() is a recursive iteration function to visit all
+ *          links in and below a group in an HDF5 file, thus providing a
+ *          mechanism for an application to perform a common set of operations
+ *          across all of those links or a dynamically selected subset. For
+ *          non-recursive iteration across the members of a group, see
+ *          H5Literate2().
+ *
+ *          The group serving as the root of the iteration is specified by the
+ *          \p loc_id / \p group_name parameter pair. \p loc_id specifies a
+ *          file or group; group_name specifies either a group in the file
+ *          (with an absolute name based in the file’s root group) or a group
+ *          relative to \p loc_id. If \p loc_id fully specifies the group that
+ *          is to serve as the root of the iteration, group_name should be '.'
+ *          (a dot). (Note that when \p loc_id fully specifies the the group
+ *          that is to serve as the root of the iteration, the user may wish to
+ *          consider using H5Lvisit2() instead of H5Lvisit_by_name2().)
+ *
+ *          Two parameters are used to establish the iteration: \p idx_type and
+ *          \p order.
+ *
+ *          \p idx_type specifies the index to be used. If the links have not
+ *          been indexed by the index type, they will first be sorted by that
+ *          index then the iteration will begin; if the links have been so
+ *          indexed, the sorting step will be unnecesary, so the iteration may
+ *          begin more quickly. Valid values include the following:
+ *          \indexes
+ *
+ *          Note that the index type passed in \p idx_type is a best effort
+ *          setting. If the application passes in a value indicating iteration
+ *          in creation order and a group is encountered that was not tracked
+ *          in creation order, that group will be iterated over in
+ *          lexicographic order by name, or name order. (Name order is the
+ *          native order used by the HDF5 library and is always available.)
+ *
+ *          \p order specifies the order in which objects are to be inspected
+ *          along the index specified in \p idx_type. Valid values include the
+ *          following:
+ *          \orders
+ *
+ *          The \p op callback function, the related \ref H5L_info2_t
+ *          \c struct, and the effect that the callback function's return value
+ *          has on the application are described in H5Lvisit2().
+ *
+ *          The H5Lvisit_by_name2() \p op_data parameter is a user-defined
+ *          pointer to the data required to process links in the course of the
+ *          iteration. This pointer is passed back to each step of the
+ *          iteration in the callback function's \p op_data parameter.
+ *
+ *          \p lapl_id is a link access property list. In the general case,
+ *          when default link access properties are acceptable, this can be
+ *          passed in as #H5P_DEFAULT. An example of a situation that requires
+ *          a non-default link access property list is when the link is an
+ *          external link; an external link may require that a link prefix be
+ *          set in a link access property list (see H5Pset_elink_prefix()).
+ *
+ *          H5Lvisit_by_name2() and H5Ovisit_by_name2() are companion
+ *          functions: one for examining and operating on links; the other for
+ *          examining and operating on the objects that those links point to.
+ *          Both functions ensure that by the time the function completes
+ *          successfully, every link or object below the specified point in the
+ *          file has been presented to the application for whatever processing
+ *          the application requires.
+ *
+ * \since 1.12.0
+ *
+ */
 H5_DLL herr_t  H5Lvisit_by_name2(hid_t loc_id, const char *group_name, H5_index_t idx_type,
                                  H5_iter_order_t order, H5L_iterate2_t op, void *op_data, hid_t lapl_id);
 
 /* UD link functions */
+/**
+ * \ingroup H5L
+ *
+ * \brief Creates a link of a user-defined type
+ *
+ * \loc_id{link_loc_id}
+ * \param[in] link_name Link name
+ * \param[in] link_type User-defined link class
+ * \param[in] udata User-supplied link information
+ * \param[in] udata_size Size of udata buffer
+ * \lcpl_id
+ * \lapl_id
+ *
+ * \return \herr_t
+ *
+ * \details H5Lcreate_ud() creates a link of user-defined type \p link_type
+ *          named \p link_name at the location specified in \p link_loc_id with
+ *          user-specified data \p udata.
+ *
+ *          \p link_name is interpreted relative to \p link_loc_id.
+ *
+ *          Valid values for the link class of the new link, \p link_type,
+ *          include #H5L_TYPE_EXTERNAL and any user-defined link classes that
+ *          have been registered with the library. See H5Lregister() for
+ *          further information.
+ *
+ *          The format of the information pointed to by \p udata is defined by
+ *          the user. \p udata_size specifies the size of the \p udata buffer.
+ *          \p udata may be NULL if \p udata_size is zero (0).
+ *
+ *          The property lists specified by \p lcpl_id and \p lapl_id specify
+ *          properties used to create and access the link.
+ *
+ * \note The external link type, #H5L_TYPE_EXTERNAL, included in the HDF5
+ *       library distribution, is implemented as a user-defined link type. This
+ *       was done, in part, to provide a model for the implementation of other
+ *       user-defined links.
+ *
+ * \since 1.8.0
+ *
+ */
 H5_DLL herr_t H5Lcreate_ud(hid_t link_loc_id, const char *link_name, H5L_type_t link_type, const void *udata,
                            size_t udata_size, hid_t lcpl_id, hid_t lapl_id);
+/**
+ * \ingroup H5LA
+ *
+ * \brief Registers a user-defined link class or changes behavior of an
+ *        existing class
+ *
+ * \param[in] cls Pointer to a buffer containing the struct describing the
+ *            user-defined link class
+ *
+ * \return \herr_t
+ *
+ * \details H5Lregister() registers a class of user-defined links, or changes
+ *          the behavior of an existing class.
+ *
+ *          \p cls is a pointer to a buffer containing a copy of the
+ *          H5L_class_t struct. This struct is defined in H5Lpublic.h as
+ *          follows:
+ *          \snippet this H5L_class_t_snip
+ *
+ *          The class definition passed with \p cls must include at least the
+ *          following:
+ *          \li An H5L_class_t version (which should be #H5L_LINK_CLASS_T_VERS)
+ *          \li A link class identifier, \c class_id
+ *          \li A traversal function, \c trav_func
+ *
+ *          Remaining \c struct members are optional and may be passed as NULL.
+ *
+ *          The link class passed in \c class_id must be in the user-definable
+ *          range between #H5L_TYPE_UD_MIN and #H5L_TYPE_UD_MAX
+ *          (see the table below) and will override
+ *          any existing link class with that identifier.
+ *
+ *          As distributed, valid values of \c class_id used in HDF5 include
+ *          the following (defined in H5Lpublic.h):
+ *          \link_types
+ *
+ *          The hard and soft link class identifiers cannot be modified or
+ *          reassigned, but the external link class is implemented as an
+ *          example in the user-definable link class identifier range.
+ *          H5Lregister() is used to register additional link classes. It could
+ *          also be used to modify the behavior of the external link class,
+ *          though that is not recommended.
+ *
+ *          The following table summarizes existing link types and values and
+ *          the reserved and user-definable link class identifier value ranges.
+ *          <table>
+ *            <tr>
+ *              <th>Link class identifier or Value range</th>
+ *              <th>Description</th>
+ *              <th>Link class or label</th>
+ *            </tr>
+ *            <tr>
+ *              <td>0 to 63</td>
+ *              <td>Reserved range</td>
+ *              <td></td>
+ *            </tr>
+ *            <tr>
+ *              <td>64 to 255</td>
+ *              <td>User-definable range</td>
+ *              <td></td>
+ *            </tr>
+ *            <tr>
+ *              <td>64</td>
+ *              <td>Minimum user-defined value</td>
+ *              <td>#H5L_TYPE_UD_MIN</td>
+ *            </tr>
+ *            <tr>
+ *              <td>64</td>
+ *              <td>External link</td>
+ *              <td>#H5L_TYPE_EXTERNAL</td>
+ *            </tr>
+ *            <tr>
+ *              <td>255</td>
+ *              <td>Maximum user-defined value</td>
+ *              <td>#H5L_TYPE_UD_MAX</td>
+ *            </tr>
+ *            <tr>
+ *              <td>255</td>
+ *              <td>Maximum value</td>
+ *              <td>#H5L_TYPE_MAX</td>
+ *            </tr>
+ *            <tr>
+ *              <td>-1</td>
+ *              <td>Error</td>
+ *              <td>#H5L_TYPE_ERROR</td>
+ *            </tr>
+ *          </table>
+ *
+ *          Note that HDF5 internally registers user-defined link classes only
+ *          by the numeric value of the link class identifier. An application,
+ *          on the other hand, will generally use a name for a user-defined
+ *          class, if for no other purpose than as a variable name. Assume,
+ *          for example, that a complex link type is registered with the link
+ *          class identifier 73 and that the code includes the following
+ *          assignment:
+ *          \code
+ *          H5L_TYPE_COMPLEX_A = 73
+ *          \endcode
+ *          The application can refer to the link class with a term,
+ *          \c  H5L_TYPE_COMPLEX_A, that conveys meaning to a human reviewing
+ *          the code, while HDF5 recognizes it by the more cryptic numeric
+ *          identifier, 73.
+ *
+ * \attention Important details and considerations include the following:
+ *            \li If you plan to distribute files or software with a
+ *                user-defined link class, please contact the Help Desk at
+ *                The HDF Group to help prevent collisions between \c class_id
+ *                values. See below.
+ *            \li As distributed with HDF5, the external link class is
+ *                implemented as an example of a user-defined link class with
+ *                #H5L_TYPE_EXTERNAL equal to #H5L_TYPE_UD_MIN. \c class_id in
+ *                the H5L_class_t \c struct must not equal #H5L_TYPE_UD_MIN
+ *                unless you intend to overwrite or modify the behavior of
+ *                external links.
+ *            \li H5Lregister() can be used only with link class identifiers
+ *                in the user-definable range (see table above).
+ *            \li The hard and soft links defined by the HDF5 library,
+ *                #H5L_TYPE_HARD and #H5L_TYPE_SOFT, reside in the reserved
+ *                range below #H5L_TYPE_UD_MIN and cannot be redefined or
+ *                modified.
+ *            \li H5Lis_registered() can be used to determine whether a desired
+ *                link class identifier is available. \Emph{Note that this
+ *                function will tell you only whether the link class identifier
+ *                has been registered with the installed copy of HDF5; it
+ *                cannot tell you whether the link class has been registered
+ *                with The HDF Group.}
+ *            \li #H5L_TYPE_MAX is the maximum allowed value for a link type
+ *                identifier.
+ *            \li #H5L_TYPE_UD_MIN equals #H5L_TYPE_EXTERNAL.
+ *            \li #H5L_TYPE_UD_MAX equals #H5L_TYPE_MAX.
+ *            \li #H5L_TYPE_ERROR indicates that an error has occurred.
+ *
+ * \note \Bold{Registration with The HDF Group:}\n
+ *       There are sometimes reasons to take a broader approach to registering
+ *       a user-defined link class than just invoking H5Lregister(). For
+ *       example:
+ *       \li A user-defined link class is intended for use across an
+ *           organization, among collaborators, or across a community of users.
+ *       \li An application or library overlying HDF5 invokes a user-defined
+ *           link class that must be shipped with the software.
+ *       \li Files are distributed that make use of a user-defined link class.
+ *       \li Or simply, a specific user-defined link class is thought to be
+ *           widely useful.
+ *
+ *       In such cases, you are encouraged to register that link class with
+ *       The HDF Group's Helpdesk. The HDF Group maintains a registry of known
+ *       user-defined link classes and tracks the selected link class
+ *       identifiers. This registry is intended to reduce the risk of
+ *       collisions between \c class_id values and to help coordinate the use
+ *       of specialized link classes.
+ *
+ * \since 1.8.0
+ *
+ */
 H5_DLL herr_t H5Lregister(const H5L_class_t *cls);
+/**
+ * \ingroup H5LA
+ *
+ * \brief Unregisters a class of user-defined links
+ *
+ * \param[in] id User-defined link class identifier
+ *
+ * \return \herr_t
+ *
+ * \details H5Lunregister() unregisters a class of user-defined links,
+ *          preventing them from being traversed, queried, moved, etc.
+ *
+ * \note A link class can be re-registered using H5Lregister().
+ *
+ * \since 1.8.0
+ *
+ */
 H5_DLL herr_t H5Lunregister(H5L_type_t id);
+/**
+ * \ingroup H5LA
+ *
+ * \brief Determines whether a class of user-defined links is registered
+ *
+ * \param[in] id User-defined link class identifier
+ *
+ * \return \htri_t
+ *
+ * \details H5Lis_registered() tests whether a user-defined link class is
+ *          currently registered, either by the HDF5 library or by the user
+ *          through the use of H5Lregister().
+ *
+ * \note A link class must be registered to create new links of that type or to
+ *       traverse existing links of that type.
+ *
+ * \since 1.8.0
+ *
+ */
 H5_DLL htri_t H5Lis_registered(H5L_type_t id);
 
 /* External link functions */
+/**
+ * \ingroup H5L
+ *
+ * \brief Decodes external link information
+ *
+ * \param[in] ext_linkval Buffer containing external link information
+ * \param[in] link_size Size, in bytes, of the \p ext_linkval buffer
+ * \param[out] flags External link flags, packed as a bitmap (\Emph{Reserved as
+ *                   a bitmap for flags; no flags are currently defined, so the
+ *                   only valid value * is 0.})
+ * \param[out] filename Returned filename \param[out] obj_path Returned
+ * object path, relative to \p filename
+ *
+ * \return \herr_t
+ *
+ * \details H5Lunpack_elink_val() decodes the external link information
+ *          returned by H5Lget_val() in the \p ext_linkval buffer.
+ *
+ *          \p ext_linkval should be the buffer set by H5Lget_val() and will
+ *          consist of two NULL-terminated strings, the filename and object
+ *          path, one after the other.
+ *
+ *          Given this buffer, H5Lunpack_elink_val() creates pointers to the
+ *          filename and object path within the buffer and returns them in
+ *          \p filename and \p obj_path, unless they are passed in as NULL.
+ *
+ *          H5Lunpack_elink_val() requires that \p ext_linkval contain a
+ *          concatenated pair of null-terminated strings, so use of this
+ *          function on a string that is not an external link \p udata buffer
+ *          may result in a segmentation fault. This failure can be avoided by
+ *          adhering to the following procedure:
+ *          <ol>
+ *            <li>Call H5Lget_info() to get the link type and the size of the
+ *                link value.<li>
+ *            <li>Verify that the link is an external link, i.e., that its link
+ *                type is #H5L_TYPE_EXTERNAL.</li>
+ *            <li>Call H5Lget_val() to get the link value.</li>
+ *            <li>Call H5Lunpack_elink_val() to unpack that value.</li>
+ *          </ol>
+ *
+ * \since 1.8.0
+ *
+ */
 H5_DLL herr_t H5Lunpack_elink_val(const void *ext_linkval /*in*/, size_t link_size, unsigned *flags,
                                   const char **filename /*out*/, const char **obj_path /*out*/);
+/**
+ * \ingroup H5L
+ *
+ * \brief Creates an external link, a soft link to an object in a different file.
+ *
+ * \param[in] file_name   Name of the target file containing the target object.
+ * \param[in] obj_name    Path within the target file to the target object
+ * \fgdt_loc_id{link_loc_id}
+ * \param[in] link_name   Name of the new link, relative to \p link_loc_id
+ * \lcpl_id
+ * \lapl_id
+ * \return \herr_t
+ *
+ * \details H5Lcreate_external() creates a new external link. An external link
+ *          is a soft link to an object in a different HDF5 file from the
+ *          location of the link, i.e., to an external object.
+ *
+ *          \p file_name identifies the target file containing the target
+ *          object; \p obj_name specifies the path of the target object within
+ *          that file. \p obj_name must be an absolute pathname in
+ *          \p file_name, i.e., it must start at the target file’s root group,
+ *          but it is not interpreted until an application attempts to traverse
+ *          it.
+ *
+ *          \p link_loc_id and \p link_name specify the location and name,
+ *          respectively, of the new link. \p link_name is interpreted relative
+ *          to \p link_loc_id.
+ *
+ *          \p lcpl_id is the link creation property list used in creating the
+ *          new link.
+ *
+ *          \p lapl_id is the link access property list used in traversing the
+ *          new link. Note that an external file opened by the traversal of an
+ *          external link is always opened with the weak file close degree
+ *          property setting, #H5F_CLOSE_WEAK (see H5Pset_fclose_degree());
+ *          any file close degree property setting in \p lapl_id is ignored.
+ *
+ *          An external link behaves similarly to a soft link, and like a soft
+ *          link in an HDF5 file, it may dangle: the target file and object
+ *          need not exist at the time that the external link is created.
+ *
+ *          When the external link \p link_name is accessed, the library will
+ *          search for the target file \p file_name as described below:
+ *
+ *          - If \p file_name is a relative pathname, the following steps are
+ *            performed:
+ *            - The library will get the prefix(es) set in the environment
+ *              variable \c HDF5_EXT_PREFIX and will try to prepend each prefix
+ *              to \p file_name to form a new \p file_name.
+ *            - If the new \p file_name does not exist or if \c HDF5_EXT_PREFIX
+ *              is not set, the library will get the prefix set via
+ *              H5Pset_elink_prefix() and prepend it to \p file_name to form a
+ *              new \p file_name.
+ *            - If the new \p file_name does not exist or no prefix is being
+ *              set by H5Pset_elink_prefix(), then the path of the file
+ *              associated with \p link_loc_id is obtained. This path can be
+ *              the absolute path or the current working directory plus the
+ *              relative path of that file when it is created/opened. The
+ *              library will prepend this path to \p file_name to form a new
+ *              \p file_name.
+ *            - If the new \p file_name does not exist, then the library will
+ *              look for \p file_name and will return failure/success
+ *              accordingly.
+ *          - If \p file_name is an absolute pathname, the library will first
+ *            try to find \p file_name. If \p file_name does not exist,
+ *            \p file_name is stripped of directory paths to form a new
+ *            \p file_name. The search for the new \p file_name then follows
+ *            the same steps as described above for a relative pathname. See
+ *            examples below illustrating how target_file_name is stripped to
+ *            form a new \p file_name.
+ *
+ *          Note that \p file_name is considered to be an absolute pathname
+ *          when the following condition is true:
+ *
+ *          - For Unix, the first character of \p file_name is a slash (\c /).
+ *            For example, consider a \p file_name of \c /tmp/A.h5.
+ *            If that target file does not exist, the new \p file_name after
+ *            stripping will be \c A.h5.
+ *          - For Windows, there are 6 cases:
+ *            -# \p file_name is an absolute drive with absolute pathname.
+ *               For example, consider a \p file_name of \c /tmp/A.h5. If that
+ *               target file does not exist, the new \p file_name after
+ *               stripping will be \c A.h5.
+ *            -# \p file_name is an absolute pathname without specifying drive
+ *               name. For example, consider a \p file_name of \c /tmp/A.h5.
+ *               If that target file does not exist, the new \p file_name after
+ *               stripping will be \c A.h5.
+ *            -# \p file_name is an absolute drive with relative pathname.
+ *               For example, consider a \p file_name of \c /tmp/A.h5. If that
+ *               target file does not exist, the new \p file_name after
+ *               stripping will be \c tmp\A.h5.
+ *            -# \p file_name is in UNC (Uniform Naming Convention) format with
+ *               server name, share name, and pathname. For example, consider
+ *               a \p file_name of \c /tmp/A.h5. If that target file does not
+ *               exist, the new \p file_name after stripping will be \c A.h5.
+ *            -# \p file_name is in Long UNC (Uniform Naming Convention) format
+ *               with server name, share name, and pathname. For example,
+ *               consider a \p file_name of \c /tmp/A.h5. If that target file
+ *               does not exist, the new \p file_name after stripping will be
+ *               \c A.h5.
+ *            -# \p file_name is in Long UNC (Uniform Naming Convention) format
+ *               with an absolute drive and an absolute pathname. For example,
+ *               consider a \p file_name of \c /tmp/A.h5. If that target file
+ *               does not exist, the new \p file_name after stripping will be
+ *               \c A.h5.
+ *
+ *          The library opens target file \p file_name with the file access
+ *          property list that is set via H5Pset_elink_fapl() when the external
+ *          link link_name is accessed. If no such property list is set, the
+ *          library uses the file access property list associated with the file
+ *          of \p link_loc_id to open the target file.
+ *
+ *          If an application requires additional control over file access
+ *          flags or the file access property list, see H5Pset_elink_cb(); this
+ *          function enables the use of an external link callback function as
+ *          described in H5L_elink_traverse_t().
+ *
+ * \attention A file close degree property setting (H5Pset_fclose_degree()) in
+ *            the external link file access property list or in the external
+ *            link callback function will be ignored. A file opened by means of
+ *            traversing an external link is always opened with the weak file
+ *            close degree property setting, #H5F_CLOSE_WEAK .
+ *
+ * \see H5Lcreate_hard(), H5Lcreate_soft(), H5Lcreate_ud()
+ *
+ * \since 1.8.0
+ */
 H5_DLL herr_t H5Lcreate_external(const char *file_name, const char *obj_name, hid_t link_loc_id,
                                  const char *link_name, hid_t lcpl_id, hid_t lapl_id);
 
@@ -205,49 +1609,508 @@ H5_DLL herr_t H5Lcreate_external(const char *file_name, const char *obj_name, hi
 /* Typedefs */
 
 /* Information struct for link (for H5Lget_info1/H5Lget_info_by_idx1) */
+//! [H5L_info1_t_snip]
 typedef struct {
-    H5L_type_t type;         /* Type of link                   */
-    hbool_t    corder_valid; /* Indicate if creation order is valid */
-    int64_t    corder;       /* Creation order                 */
-    H5T_cset_t cset;         /* Character set of link name     */
+    H5L_type_t          type;           /**< Type of link                   */
+    hbool_t             corder_valid;   /**< Indicate if creation order is valid */
+    int64_t             corder;         /**< Creation order                 */
+    H5T_cset_t          cset;           /**< Character set of link name     */
     union {
-        haddr_t address;  /* Address hard link points to    */
-        size_t  val_size; /* Size of a soft link or UD link value */
+        haddr_t         address;        /**< Address hard link points to    */
+        size_t          val_size;       /**< Size of a soft link or UD link value */
     } u;
 } H5L_info1_t;
+//! [H5L_info1_t_snip]
 
-/* Callback during link traversal */
+/** Callback during link traversal */
 typedef hid_t (*H5L_traverse_0_func_t)(const char *link_name, hid_t cur_group, const void *lnkdata,
                                        size_t lnkdata_size, hid_t lapl_id);
 
-/* User-defined link types */
+/** User-defined link types */
 typedef struct {
-    int                   version;     /* Version number of this struct        */
-    H5L_type_t            id;          /* Link type ID                         */
-    const char *          comment;     /* Comment for debugging                */
-    H5L_create_func_t     create_func; /* Callback during link creation        */
-    H5L_move_func_t       move_func;   /* Callback after moving link           */
-    H5L_copy_func_t       copy_func;   /* Callback after copying link          */
-    H5L_traverse_0_func_t trav_func;   /* Callback during link traversal       */
-    H5L_delete_func_t     del_func;    /* Callback for link deletion           */
-    H5L_query_func_t      query_func;  /* Callback for queries                 */
+    int version;                    /**< Version number of this struct        */
+  H5L_type_t id;                    /**< Link type ID                         */
+    const char *comment;            /**< Comment for debugging                */
+    H5L_create_func_t create_func;  /**< Callback during link creation        */
+    H5L_move_func_t move_func;      /**< Callback after moving link           */
+    H5L_copy_func_t copy_func;      /**< Callback after copying link          */
+    H5L_traverse_0_func_t trav_func; /**< Callback during link traversal       */
+    H5L_delete_func_t del_func;     /**< Callback for link deletion           */
+    H5L_query_func_t query_func;    /**< Callback for queries                 */
 } H5L_class_0_t;
 
-/* Prototype for H5Literate1/H5Literate_by_name1() operator */
-typedef herr_t (*H5L_iterate1_t)(hid_t group, const char *name, const H5L_info1_t *info, void *op_data);
+/** Prototype for H5Literate1() / H5Literate_by_name1() operator */
+//! [H5L_iterate1_t_snip]
+typedef herr_t (*H5L_iterate1_t)(hid_t group, const char *name, const H5L_info1_t *info,
+    void *op_data);
+//! [H5L_iterate1_t_snip]
 
 /* Function prototypes */
+/**
+ * \ingroup H5L
+ *
+ * \brief Returns information about a link
+ *
+ * \fgdta_loc_id
+ * \param[in] name Link name
+ * \param[out] linfo Buffer in which link information is returned
+ * \lapl_id
+ *
+ * \return \herr_t
+ *
+ * \deprecated As of HDF5-1.12 this function has been deprecated in favor of
+ *             the function H5Lget_info2() or the macro H5Lget_info().
+ *
+ * \todo We need to get the location ID story straight!
+ *
+ * \details H5Lget_info1() returns information about the specified link through
+ *          the \p linfo argument.
+ *
+ *          The location identifier, \p loc_id, specifies the location of the
+ *          link. A link name, \p name, interpreted relative to \p loc_id,
+ *          specifies the link being queried.
+ *
+ *          \p lapl_id is the link access property list associated with the
+ *          link \p name. In the general case, when default link access
+ *          properties are acceptable, this can be passed in as #H5P_DEFAULT.
+ *          An example of a situation that requires a non-default link access
+ *          property list is when the link is an external link; an external
+ *          link may require that a link prefix be set in a link access
+ *          property list (see H5Pset_elink_prefix()).
+ *
+ *          H5Lget_info1() returns information about name in the data structure
+ *          \ref H5L_info1_t, which is described below and defined in
+ *          H5Lpublic.h. This structure is returned in the buffer \p linfo.
+ *          \snippet this H5L_info1_t_snip
+ *          In the above struct, type specifies the link class. Valid values
+ *          include the following:
+ *          \link_types
+ *          There will be additional valid values if user-defined links have
+ *          been registered.
+ *
+ *          \c corder specifies the link’s creation order position while
+ *          \c corder_valid indicates whether the value in \c corder is valid.
+ *
+ *          If \c corder_valid is \c TRUE, the value in \c corder is known to
+ *          be valid; if \c corder_valid is \c FALSE, the value in \c corder is
+ *          presumed to be invalid;
+ *
+ *          \c corder starts at zero (0) and is incremented by one (1) as new
+ *          links are created. But higher-numbered entries are not adjusted
+ *          when a lower-numbered link is deleted; the deleted link’s creation
+ *          order position is simply left vacant. In such situations, the value
+ *          of \c corder for the last link created will be larger than the
+ *          number of links remaining in the group.
+ *
+ *          \c cset specifies the character set in which the link name is
+ *          encoded. Valid values include the following:
+ *          \csets
+ *          This value is set with H5Pset_char_encoding().
+ *
+ *          \c address and \c val_size are returned for hard and symbolic
+ *          links, respectively. Symbolic links include soft and external links
+ *          and some user-defined links.
+ *
+ *          If the link is a hard link, \c address specifies the file address
+ *          that the link points to.
+ *
+ *          If the link is a symbolic link, \c val_size will be the length of
+ *          the link value, e.g., the length of the HDF5 path name with a null
+ *          terminator.
+ *
+ * \version 1.12.0 Function was deprecated.
+ * \version 1.8.2 Fortran subroutine added in this release.
+ * \version 1.8.4 Fortran subroutine syntax changed in this release.
+ *
+ * \since 1.8.0
+ *
+ */
 H5_DLL herr_t H5Lget_info1(hid_t loc_id, const char *name, H5L_info1_t *linfo /*out*/, hid_t lapl_id);
+/**
+ * \ingroup H5L
+ *
+ * \brief Retrieves metadata for a link in a group, according to the order
+ *        within a field or index
+ *
+ * \loc_id
+ * \param[in] group_name Group name
+ * \idx_type
+ * \order
+ * \param[in] n Link position for which to retrieve information
+ * \param[out] linfo Buffer in which link information is returned
+ * \lapl_id
+ *
+ * \return \herr_t
+ *
+ * \deprecated As of HDF5-1.12 this function has been deprecated in favor of
+ *             the function H5Lget_info_by_idx2() and the macro
+ *             H5Lget_info_by_idx().
+ *
+ * \details H5get_info_by_idx1() returns the metadata for a link in a group
+ *          according to a specified field or index and a specified order.
+ *
+ *          The link for which information is to be returned is specified by \p
+ *          idx_type, \p order, and \p n as follows:
+ *
+ *          - \p idx_type specifies the field by which the links in \p
+ *            group_name are ordered. The links may be indexed on this field,
+ *            in which case operations seeking specific links are likely to
+ *            complete more quickly.
+ *          - \p order specifies the order in which
+ *            the links are to be referenced for the purposes of this function.
+ *          - \p n specifies the position of the subject link. Note that this
+ *            count is zero-based; 0 (zero) indicates that the function will
+ *            return the value of the first link; if \p n is 5, the function
+ *            will return the value of the sixth link; etc.
+ *
+ *          For example, assume that \p idx_type, \p order, and \p n are
+ *          #H5_INDEX_NAME, #H5_ITER_DEC, and 5, respectively. #H5_INDEX_NAME
+ *          indicates that the links are accessed in lexicographic order by
+ *          their names. #H5_ITER_DEC specifies that the list be traversed in
+ *          reverse order, or in decremented order. And 5 specifies that this
+ *          call to the function will return the metadata for the 6th link
+ *          (\c n + 1) from the end.
+ *
+ *          See H5Literate1() for a list of valid values and further discussion
+ *          regarding \p idx_type and \p order.
+ *
+ *          If \p loc_id specifies the group in which the link resides,
+ *          \p group_name can be a dot (\c .).
+ *
+ * \version 1.12.0 Function was renamed to H5Lget_index_by_idx1() and deprecated.
+ * \version 1.8.4 Fortran subroutine syntax changed in this release.
+ * \version 1.8.2 Fortran subroutine added in this release.
+ *
+ * \since 1.8.0
+ *
+ */
 H5_DLL herr_t H5Lget_info_by_idx1(hid_t loc_id, const char *group_name, H5_index_t idx_type,
                                   H5_iter_order_t order, hsize_t n, H5L_info1_t *linfo /*out*/,
                                   hid_t lapl_id);
+/**
+ * \ingroup TRAV
+ *
+ * \brief Iterates over links in a group, with user callback routine,
+ *        according to the order within an index.
+ *
+ * \group_id{grp_id}
+ * \idx_type
+ * \order
+ * \param[in,out] idx Pointer to an iteration index to allow
+ *                    continuing a previous iteration
+ * \op
+ * \op_data
+ * \return \success{The return value of the first operator that returns
+ *                  non-zero, or zero if all members were processed with no
+ *                  operator returning non-zero.}
+ * \return \failure{Negative if an error occurs in the library, or the negative
+ *                  value returned by one of the operators.}
+ *
+ * \deprecated Deprecated in favor of H5Literate2().
+ *
+ * \details H5Literate1() iterates through the links in a file or
+ *          group, \p group_id, in the order of the specified
+ *          index, \p idx_type, using a user-defined callback routine
+ *          \p op. H5Literate1() does not recursively follow links into
+ *          subgroups of the specified group.
+ *
+ *          Three parameters are used to manage progress of the iteration:
+ *          \p idx_type, \p order, and \p idx_p.
+ *
+ *          \p idx_type specifies the index to be used. If the links have
+ *          not been indexed by the index type, they will first be sorted by
+ *          that index then the iteration will begin; if the links have been
+ *          so indexed, the sorting step will be unnecessary, so the iteration
+ *          may begin more quickly.
+ *
+ *          \p order specifies the order in which objects are to be inspected
+ *          along the index \p idx_type.
+ *
+ *          \p idx_p tracks the iteration and allows an iteration to be
+ *          resumed if it was stopped before all members were processed. It is
+ *          passed in by the application with a starting point and returned by
+ *          the library with the point at which the iteration stopped.
+ *
+ *          \p op_data is a user-defined pointer to the data required to
+ *          process links in the course of the iteration. This pointer is
+ *          passed back to each step of the iteration in the \p op callback
+ *          function's \p op_data parameter. \p op is invoked for each link
+ *          encounter.
+ *
+ *          \p op_data is passed to and from each iteration and can be used to
+ *          supply or aggregate information across iterations.
+ *
+ * \remark Same pattern of behavior as H5Giterate().
+ *
+ * \note This function is also available through the H5Literate() macro.
+ *
+ * \warning The behavior of H5Literate1() is undefined if the link
+ *          membership of \p group_id changes during the iteration.
+ *          This does not limit the ability to change link destinations
+ *          while iterating, but caution is advised.
+ *
+ *
+ * \version 1.12.0 Function was deprecated in this release.
+ * \since 1.8.0
+ *
+ * \see H5Literate_by_name2(), H5Lvisit2(), H5Lvisit_by_name2()
+ *
+ */
 H5_DLL herr_t H5Literate1(hid_t grp_id, H5_index_t idx_type, H5_iter_order_t order, hsize_t *idx,
                           H5L_iterate1_t op, void *op_data);
+/**
+ * \ingroup TRAV
+ *
+ * \brief Iterates through links in a group by its name
+ *
+ * \loc_id
+ * \param[in] group_name Group name
+ * \idx_type
+ * \order
+ * \param[in,out] idx iteration position at which to start (\Emph{IN}) or
+ *                position at which an interrupted iteration may be restarted
+ *                (\Emph{OUT})
+ * \op
+ * \op_data
+ * \lapl_id
+ *
+ * \return \success{The return value of the first operator that returns
+ *                  non-zero, or zero if all members were processed with no
+ *                  operator returning non-zero.}
+ * \return \failure{Negative if an error occurs in the library, or the negative
+ *                  value returned by one of the operators.}
+ *
+ * \deprecated As of HDF5-1.12 this function has been deprecated in favor of
+ *             the function H5Literate_by_name2() or the macro
+ *             H5Literate_by_name().
+ *
+ * \details H5Literate_by_name1() iterates through the links in a group
+ *          specified by \p loc_id and \p group_name, in the order of the
+ *          specified index, \p idx_type, using a user-defined callback routine
+ *          \p op. H5Literate_by_name1() does not recursively follow links into
+ *          subgroups of the specified group.
+ *
+ *          \p idx_type specifies the index to be used. If the links have not
+ *          been indexed by the index type, they will first be sorted by that
+ *          index then the iteration will begin; if the links have been so
+ *          indexed, the sorting step will be unnecessary, so the iteration may
+ *          begin more quickly. Valid values include the following:
+ *          \indexes
+ *
+ *          \p order specifies the order in which objects are to be inspected
+ *          along the index specified in \p idx_type. Valid values include the
+ *          following:
+ *          \orders
+ *
+ *          \p idx allows an interrupted iteration to be resumed; it is
+ *          passed in by the application with a starting point and returned by
+ *          the library with the point at which the iteration stopped.
+ *
+ * \note H5Literate_by_name1() is not recursive. In particular, if a member of
+ *       \p group_name is found to be a group, call it \c subgroup_a,
+ *       H5Literate_by_name1() does not examine the members of \c subgroup_a.
+ *       When recursive iteration is required, the application must handle the
+ *       recursion, explicitly calling H5Literate_by_name1() on discovered
+ *       subgroups.
+ *
+ * \note H5Literate_by_name1() assumes that the membership of the group being
+ *       iterated over remains unchanged through the iteration; if any of the
+ *       links in the group change during the iteration, the function’s
+ *       behavior is undefined. Note, however, that objects pointed to by the
+ *       links can be modified.
+ *
+ * \note H5Literate_by_name1() is the same as H5Giterate(), except that
+ *       H5Giterate() always proceeds in lexicographic order.
+ *
+ * \version 1.12.0 Function H5Literate_by_name() was renamed to
+ *                 H5Literate_by_name1() and deprecated.
+ * \version 1.8.8 Fortran subroutine added.
+ *
+ * \since 1.8.0
+ *
+ */
 H5_DLL herr_t H5Literate_by_name1(hid_t loc_id, const char *group_name, H5_index_t idx_type,
                                   H5_iter_order_t order, hsize_t *idx, H5L_iterate1_t op, void *op_data,
                                   hid_t lapl_id);
+/**
+ * \ingroup TRAV
+ *
+ * \brief Recursively visits all links starting from a specified group
+ *
+ * \group_id{grp_id}
+ * \idx_type
+ * \order
+ * \op
+ * \op_data
+ *
+ * \return \success{The return value of the first operator that returns
+ *                  non-zero, or zero if all members were processed with no
+ *                  operator returning non-zero.}
+ * \return \failure{Negative if an error occurs in the library, or the negative
+ *                  value returned by one of the operators.}
+ *
+ * \deprecated As of HDF5-1.12 this function has been deprecated in favor of
+ *             the function H5Lvisit2() or the macro H5Lvisit().
+ *
+ * \details H5Lvisit1() is a recursive iteration function to visit all links in
+ *          and below a group in an HDF5 file, thus providing a mechanism for
+ *          an application to perform a common set of operations across all of
+ *          those links or a dynamically selected subset. For non-recursive
+ *          iteration across the members of a group, see H5Literate1().
+ *
+ *          The group serving as the root of the iteration is specified by its
+ *          group or file identifier, \p group_id.
+ *
+ *          Two parameters are used to establish the iteration: \p idx_type and
+ *          \p order.
+ *
+ *          \p idx_type specifies the index to be used. If the links have not
+ *          been indexed by the index type, they will first be sorted by that
+ *          index then the iteration will begin; if the links have been so
+ *          indexed, the sorting step will be unnecessary, so the iteration may
+ *          begin more quickly. Valid values include the following:
+ *          \indexes
+ *
+ *          Note that the index type passed in \p idx_type is a best effort
+ *          setting. If the application passes in a value indicating iteration
+ *          in creation order and a group is encountered that was not tracked
+ *          in creation order, that group will be iterated over in
+ *          lexicographic order by name, or name order. (Name order is the
+ *          native order used by the HDF5 library and is always available.)
+ *
+ *          \p order specifies the order in which objects are to be inspected
+ *          along the index specified in \p idx_type. Valid values include the
+ *          following:
+ *          \orders
+ *
+ *          \p op is a callback function of type \ref H5L_iterate1_t that is invoked
+ *          for each link encountered.
+ *          \snippet this H5L_iterate1_t_snip
+ *
+ *          The \ref H5L_info1_t struct is defined (in H5Lpublic.h) as follows:
+ *          \snippet this H5L_info1_t_snip
+ *
+ *          The possible return values from the callback function, and the
+ *          effect of each, are as follows:
+ *          \li Zero causes the visit iterator to continue, returning zero when
+ *              all group members have been processed.
+ *          \li  A positive value causes the visit iterator to immediately
+ *               return that positive value, indicating short-circuit success.
+ *          \li A negative value causes the visit iterator to immediately
+ *              return that value, indicating failure.
+ *
+ *          The H5Lvisit1() \p op_data parameter is a user-defined pointer to
+ *          the data required to process links in the course of the iteration.
+ *          This pointer is passed back to each step of the iteration in the
+ *          \p op callback function's \p op_data parameter.
+ *
+ *          H5Lvisit1() and H5Ovisit1() are companion functions: one for
+ *          examining and operating on links; the other for examining and
+ *          operating on the objects that those links point to. Both functions
+ *          ensure that by the time the function completes successfully, every
+ *          link or object below the specified point in the file has been
+ *          presented to the application for whatever processing the
+ *          application requires.
+ *
+ * \version 1.12.0 Function was renamed from H5Lvisit() to H5Lvisit1() and
+ *                 deprecated.
+ *
+ * \since 1.8.0
+ *
+ */
 H5_DLL herr_t H5Lvisit1(hid_t grp_id, H5_index_t idx_type, H5_iter_order_t order, H5L_iterate1_t op,
                         void *op_data);
+/**
+ * \ingroup TRAV
+ *
+ * \brief Recursively visits all links starting from a specified group
+ *
+ * \loc_id
+ * \param[in] group_name Group name
+ * \idx_type
+ * \order
+ * \op
+ * \op_data
+ * \lapl_id
+ *
+ * \return \success{The return value of the first operator that returns
+ *                  non-zero, or zero if all members were processed with no
+ *                  operator returning non-zero.}
+ * \return \failure{Negative if an error occurs in the library, or the negative
+ *                  value returned by one of the operators.}
+ *
+ * \deprecated As of HDF5-1.12 this function has been deprecated in favor of
+ *             the function H5Lvisit_by_name2() or the macro H5Lvisit_by_name().
+ *
+ * \details H5Lvisit_by_name1() is a recursive iteration function to visit all
+ *          links in and below a group in an HDF5 file, thus providing a
+ *          mechanism for an application to perform a common set of operations
+ *          across all of those links or a dynamically selected subset. For
+ *          non-recursive iteration across the members of a group, see
+ *          H5Literate1().
+ *
+ *          The group serving as the root of the iteration is specified by the
+ *          \p loc_id / \p group_name parameter pair. \p loc_id specifies a
+ *          file or group; group_name specifies either a group in the file
+ *          (with an absolute name based in the file’s root group) or a group
+ *          relative to \p loc_id. If \p loc_id fully specifies the group that
+ *          is to serve as the root of the iteration, group_name should be '.'
+ *          (a dot). (Note that when \p loc_id fully specifies the the group
+ *          that is to serve as the root of the iteration, the user may wish to
+ *          consider using H5Lvisit1() instead of H5Lvisit_by_name1().)
+ *
+ *          Two parameters are used to establish the iteration: \p idx_type and
+ *          \p order.
+ *
+ *          \p idx_type specifies the index to be used. If the links have not
+ *          been indexed by the index type, they will first be sorted by that
+ *          index then the iteration will begin; if the links have been so
+ *          indexed, the sorting step will be unnecesary, so the iteration may
+ *          begin more quickly. Valid values include the following:
+ *          \indexes
+ *
+ *          Note that the index type passed in \p idx_type is a best effort
+ *          setting. If the application passes in a value indicating iteration
+ *          in creation order and a group is encountered that was not tracked
+ *          in creation order, that group will be iterated over in
+ *          lexicographic order by name, or name order. (Name order is the
+ *          native order used by the HDF5 library and is always available.)
+ *
+ *          \p order specifies the order in which objects are to be inspected
+ *          along the index specified in \p idx_type. Valid values include the
+ *          following:
+ *          \orders
+ *
+ *          The \p op callback function, the related \ref H5L_info1_t
+ *          \c struct, and the effect that the callback function's return value
+ *          has on the application are described in H5Lvisit1().
+ *
+ *          The H5Lvisit_by_name1() \p op_data parameter is a user-defined
+ *          pointer to the data required to process links in the course of the
+ *          iteration. This pointer is passed back to each step of the
+ *          iteration in the callback function's \p op_data parameter.
+ *
+ *          \p lapl_id is a link access property list. In the general case,
+ *          when default link access properties are acceptable, this can be
+ *          passed in as #H5P_DEFAULT. An example of a situation that requires
+ *          a non-default link access property list is when the link is an
+ *          external link; an external link may require that a link prefix be
+ *          set in a link access property list (see H5Pset_elink_prefix()).
+ *
+ *          H5Lvisit_by_name1() and H5Ovisit_by_name1() are companion
+ *          functions: one for examining and operating on links; the other for
+ *          examining and operating on the objects that those links point to.
+ *          Both functions ensure that by the time the function completes
+ *          successfully, every link or object below the specified point in the
+ *          file has been presented to the application for whatever processing
+ *          the application requires.
+ *
+ * \version 1.12.0 Function renamed from H5Lvisit_by_name() to
+ *                 H5Lvisit_by_name1() and deprecated.
+ *
+ * \since 1.8.0
+ *
+ */
 H5_DLL herr_t H5Lvisit_by_name1(hid_t loc_id, const char *group_name, H5_index_t idx_type,
                                 H5_iter_order_t order, H5L_iterate1_t op, void *op_data, hid_t lapl_id);
 

From 70f358c1445a916e516dcc1c505f7d6c3389c3b8 Mon Sep 17 00:00:00 2001
From: Gerd Heber <gheber@hdfgroup.org>
Date: Tue, 17 Nov 2020 09:50:09 -0600
Subject: [PATCH 08/16] First installment from Elena's H5T batch.

---
 doxygen/aliases |   16 +-
 src/H5Tmodule.h |   76 +++
 src/H5Tpublic.h | 1459 +++++++++++++++++++++++++++++++++++++++--------
 3 files changed, 1312 insertions(+), 239 deletions(-)

diff --git a/doxygen/aliases b/doxygen/aliases
index aa22bd461fc..c10c3e8c42a 100644
--- a/doxygen/aliases
+++ b/doxygen/aliases
@@ -60,8 +60,8 @@ ALIASES += space_id{1}="\param[in] \1 Dataspace identifier"
 # Dataypes
 ################################################################################
 
-ALIASES += dtype_id="\param[in] dtype_id Datatype identifier"
-ALIASES += dtype_id{1}="\param[in] \1 Datatype identifier"
+ALIASES += type_id="\param[in] type_id Datatype identifier"
+ALIASES += type_id{1}="\param[in] \1 Datatype identifier"
 
 ALIASES += file_type_id{1}="\param[in] \1 Datatype (in-file) identifier"
 ALIASES += mem_type_id{1}="\param[in] \1 Datatype (in-memory) identifier"
@@ -133,15 +133,21 @@ ALIASES += lapl_id{1}="\param[in] \1 Link access property list identifier"
 ALIASES += lcpl_id="\param[in] lcpl_id Link creation property list identifier"
 ALIASES += lcpl_id{1}="\param[in] \1 Link creation property list identifier"
 
-ALIASES += vipl_id="\param[in] vipl_id VOL initialization property list identifier"
-ALIASES += vipl_id{1}="\param[in] \1 vipl_id VOL initialization property list identifier"
-
 ALIASES += plist_id="\param[in] plist_id Property list identifier"
 ALIASES += plist_id{1}="\param[in] \1 Property list identifier"
 
 ALIASES += plistcls_id="\param[in] plistcls_id Property list class identifier"
 ALIASES += plistcls_id{1}="\param[in] \1 Property list class identifier"
 
+ALIASES += tapl_id="\param[in] tapl_id Datatype access property list identifier"
+ALIASES += tapl_id{1}="\param[in] \1 Datatype access property list identifier"
+
+ALIASES += tcpl_id="\param[in] tcpl_id Datatype creation property list identifier"
+ALIASES += tcpl_id{1}="\param[in] \1 Datatype creation property list identifier"
+
+ALIASES += vipl_id="\param[in] vipl_id VOL initialization property list identifier"
+ALIASES += vipl_id{1}="\param[in] \1 vipl_id VOL initialization property list identifier"
+
 ################################################################################
 # Objects
 ################################################################################
diff --git a/src/H5Tmodule.h b/src/H5Tmodule.h
index b508dfdcaf3..fd545c20a39 100644
--- a/src/H5Tmodule.h
+++ b/src/H5Tmodule.h
@@ -29,4 +29,80 @@
 #define H5_MY_PKG_ERR  H5E_DATATYPE
 #define H5_MY_PKG_INIT YES
 
+/**
+ * \defgroup H5T H5T
+ * \brief Datatype Interface
+ * \todo Describe concisely what the functions in this module are about.
+ *
+ * \defgroup ARRAY Array Datatypes
+ * \ingroup H5T
+ * \defgroup ATOM Atomic Datatypes
+ * \ingroup H5T
+ * \defgroup COMPOUND Compound Datatypes
+ * \ingroup H5T
+ * \defgroup CONV Conversion Function
+ * \ingroup H5T
+ * \defgroup ENUM Enumeration Datatypes
+ * \ingroup H5T
+ * \defgroup GTO General Datatype Operations
+ * \ingroup H5T
+ * \defgroup OPAQUE Opaque Datatypes
+ * \ingroup H5T
+ * \defgroup STRING String Datatypes
+ * \ingroup H5T
+ * \defgroup VLEN Variable-length Sequence Datatypes
+ * \ingroup H5T
+ *
+ * \defgroup PDT Predefined Datatypes
+ * \ingroup H5T
+ * \details What is a predefined HDF5 datatype?
+ * \todo Fill in the blanks!
+ *
+ * \defgroup PDTCPU By CPU
+ * \ingroup PDT
+ * \details CPU-specific datatypes
+ * \defgroup PDTALPHA DEC Alpha
+ * \ingroup PDTCPU
+ * \defgroup PDTX86 AMD & INTEL
+ * \ingroup PDTCPU
+ * \defgroup PDTMIPS SGI MIPS
+ * \ingroup PDTCPU
+ *
+ * \defgroup PDTIEEE IEEE
+ * \ingroup PDT
+ * \details The IEEE floating point types in big- and little-endian byte orders.
+ *
+ * \defgroup PDTSTD Standard Datatypes
+ * \ingroup PDT
+ * \details These are "standard" types. For instance, signed (2's complement)
+ *          and unsigned integers of various sizes in big- and little-endian
+ *          byte orders.
+ *
+ * \defgroup PDTUNIX UNIX-specific Datatypes
+ * \ingroup PDT
+ * \details Types which are particular to Unix.
+ * \todo Fill in the blanks!
+ *
+ * \defgroup PDTNAT Native Datatypes
+ * \ingroup PDT
+ * \details These are the datatypes detected during library \Emph{compilation}
+ *          by \c H5detect(). Their names differ from other HDF5 datatype names
+ *          as follows:
+ *          \li Instead of a class name, precision and byte order as the last
+ *              component, they have a C-like type name.
+ *          \li If the type begins with \c U then it is the unsigned version of
+ *              the integer type; other integer types are signed.
+ *          \li The datatype \c LLONG corresponds C's \Code{long long} and
+ *              \c LDOUBLE is \Code{long double}. These types might be the same
+ *              as \c LONG and \c DOUBLE, respectively.
+ * \defgroup PDTC9x C9x Integer Datatypes
+ * \ingroup PDTNAT
+ * \details C9x integer types
+ * \todo Fill in the blanks!
+ *
+ * \defgroup PDTS Strings
+ * \ingroup PDT
+ *
+ */
+
 #endif /* _H5Tmodule_H */
diff --git a/src/H5Tpublic.h b/src/H5Tpublic.h
index 73a00b68b7f..07778eadee2 100644
--- a/src/H5Tpublic.h
+++ b/src/H5Tpublic.h
@@ -23,197 +23,241 @@
 
 #define HOFFSET(S, M) (offsetof(S, M))
 
-/* These are the various classes of datatypes */
-/* If this goes over 16 types (0-15), the file format will need to change) */
+/**
+ * These are the various classes of datatypes
+ * internal If this goes over 16 types (0-15), the file format will need to
+ *          change.
+ */
+//! [H5T_class_t_snip]
 typedef enum H5T_class_t {
-    H5T_NO_CLASS  = -1, /*error                                      */
-    H5T_INTEGER   = 0,  /*integer types                              */
-    H5T_FLOAT     = 1,  /*floating-point types                       */
-    H5T_TIME      = 2,  /*date and time types                        */
-    H5T_STRING    = 3,  /*character string types                     */
-    H5T_BITFIELD  = 4,  /*bit field types                            */
-    H5T_OPAQUE    = 5,  /*opaque types                               */
-    H5T_COMPOUND  = 6,  /*compound types                             */
-    H5T_REFERENCE = 7,  /*reference types                            */
-    H5T_ENUM      = 8,  /*enumeration types                          */
-    H5T_VLEN      = 9,  /*Variable-Length types                      */
-    H5T_ARRAY     = 10, /*Array types                                */
-
-    H5T_NCLASSES /*this must be last                          */
+    H5T_NO_CLASS         = -1,  /**< error                                   */
+    H5T_INTEGER          = 0,   /**< integer types                           */
+    H5T_FLOAT            = 1,   /**< floating-point types                    */
+    H5T_TIME             = 2,   /**< date and time types                     */
+    H5T_STRING           = 3,   /**< character string types                  */
+    H5T_BITFIELD         = 4,   /**< bit field types                         */
+    H5T_OPAQUE           = 5,   /**< opaque types                            */
+    H5T_COMPOUND         = 6,   /**< compound types                          */
+    H5T_REFERENCE        = 7,   /**< reference types                         */
+    H5T_ENUM             = 8,	/**< enumeration types                       */
+    H5T_VLEN             = 9,   /**< variable-Length types                   */
+    H5T_ARRAY	         = 10,	/**< array types                             */
+
+    H5T_NCLASSES                /**< sentinel: this must be last             */
 } H5T_class_t;
+//! [H5T_class_t_snip]
 
-/* Byte orders */
+/**
+ * Byte orders
+ */
 typedef enum H5T_order_t {
-    H5T_ORDER_ERROR = -1, /*error                                      */
-    H5T_ORDER_LE    = 0,  /*little endian                              */
-    H5T_ORDER_BE    = 1,  /*bit endian                                 */
-    H5T_ORDER_VAX   = 2,  /*VAX mixed endian                           */
-    H5T_ORDER_MIXED = 3,  /*Compound type with mixed member orders     */
-    H5T_ORDER_NONE  = 4   /*no particular order (strings, bits,..)     */
+    H5T_ORDER_ERROR      = -1,  /**< error                                   */
+    H5T_ORDER_LE         = 0,   /**< little endian                           */
+    H5T_ORDER_BE         = 1,   /**< bit endian                              */
+    H5T_ORDER_VAX        = 2,   /**< VAX mixed endian                        */
+    H5T_ORDER_MIXED      = 3,   /**< Compound type with mixed member orders  */
+    H5T_ORDER_NONE       = 4    /**< no particular order (strings, bits,..)  */
     /*H5T_ORDER_NONE must be last */
 } H5T_order_t;
 
-/* Types of integer sign schemes */
+/**
+ * Types of integer sign schemes
+ */
 typedef enum H5T_sign_t {
-    H5T_SGN_ERROR = -1, /*error                                      */
-    H5T_SGN_NONE  = 0,  /*this is an unsigned type                   */
-    H5T_SGN_2     = 1,  /*two's complement                           */
+    H5T_SGN_ERROR        = -1,  /**< error                                   */
+    H5T_SGN_NONE         = 0,   /**< this is an unsigned type                */
+    H5T_SGN_2            = 1,   /**< two's complement                        */
 
-    H5T_NSGN = 2 /*this must be last!                         */
+    H5T_NSGN             = 2    /** sentinel: this must be last!             */
 } H5T_sign_t;
 
-/* Floating-point normalization schemes */
+/**
+ * Floating-point normalization schemes
+ */
 typedef enum H5T_norm_t {
-    H5T_NORM_ERROR   = -1, /*error                                      */
-    H5T_NORM_IMPLIED = 0,  /*msb of mantissa isn't stored, always 1     */
-    H5T_NORM_MSBSET  = 1,  /*msb of mantissa is always 1                */
-    H5T_NORM_NONE    = 2   /*not normalized                             */
+    H5T_NORM_ERROR       = -1,  /**< error                                   */
+    H5T_NORM_IMPLIED     = 0,   /**< msb of mantissa isn't stored, always 1  */
+    H5T_NORM_MSBSET      = 1,   /**< msb of mantissa is always 1             */
+    H5T_NORM_NONE        = 2    /**< not normalized                          */
     /*H5T_NORM_NONE must be last */
 } H5T_norm_t;
 
-/*
- * Character set to use for text strings.  Do not change these values since
- * they appear in HDF5 files!
+/**
+ * Character set to use for text strings.
+ * \internal Do not change these values since they appear in HDF5 files!
  */
 typedef enum H5T_cset_t {
-    H5T_CSET_ERROR       = -1, /*error                                      */
-    H5T_CSET_ASCII       = 0,  /*US ASCII                                   */
-    H5T_CSET_UTF8        = 1,  /*UTF-8 Unicode encoding		     */
-    H5T_CSET_RESERVED_2  = 2,  /*reserved for later use		     */
-    H5T_CSET_RESERVED_3  = 3,  /*reserved for later use		     */
-    H5T_CSET_RESERVED_4  = 4,  /*reserved for later use		     */
-    H5T_CSET_RESERVED_5  = 5,  /*reserved for later use		     */
-    H5T_CSET_RESERVED_6  = 6,  /*reserved for later use		     */
-    H5T_CSET_RESERVED_7  = 7,  /*reserved for later use		     */
-    H5T_CSET_RESERVED_8  = 8,  /*reserved for later use		     */
-    H5T_CSET_RESERVED_9  = 9,  /*reserved for later use		     */
-    H5T_CSET_RESERVED_10 = 10, /*reserved for later use		     */
-    H5T_CSET_RESERVED_11 = 11, /*reserved for later use		     */
-    H5T_CSET_RESERVED_12 = 12, /*reserved for later use		     */
-    H5T_CSET_RESERVED_13 = 13, /*reserved for later use		     */
-    H5T_CSET_RESERVED_14 = 14, /*reserved for later use		     */
-    H5T_CSET_RESERVED_15 = 15  /*reserved for later use		     */
+    H5T_CSET_ERROR       = -1,  /**< error                           */
+    H5T_CSET_ASCII       = 0,   /**< US ASCII                        */
+    H5T_CSET_UTF8        = 1,   /**< UTF-8 Unicode encoding		     */
+    H5T_CSET_RESERVED_2  = 2,   /**< reserved for later use		     */
+    H5T_CSET_RESERVED_3  = 3,   /**< reserved for later use		     */
+    H5T_CSET_RESERVED_4  = 4,   /**< reserved for later use		     */
+    H5T_CSET_RESERVED_5  = 5,   /**< reserved for later use		     */
+    H5T_CSET_RESERVED_6  = 6,   /**< reserved for later use		     */
+    H5T_CSET_RESERVED_7  = 7,   /**< reserved for later use		     */
+    H5T_CSET_RESERVED_8  = 8,   /**< reserved for later use		     */
+    H5T_CSET_RESERVED_9  = 9,   /**< reserved for later use		     */
+    H5T_CSET_RESERVED_10 = 10,  /**< reserved for later use		     */
+    H5T_CSET_RESERVED_11 = 11,  /**< reserved for later use		     */
+    H5T_CSET_RESERVED_12 = 12,  /**< reserved for later use		     */
+    H5T_CSET_RESERVED_13 = 13,  /**< reserved for later use		     */
+    H5T_CSET_RESERVED_14 = 14,  /**< reserved for later use		     */
+    H5T_CSET_RESERVED_15 = 15   /**< reserved for later use		     */
 } H5T_cset_t;
-#define H5T_NCSET H5T_CSET_RESERVED_2 /*Number of character sets actually defined  */
+#define H5T_NCSET H5T_CSET_RESERVED_2    		/*Number of character sets actually defined  */
 
-/*
- * Type of padding to use in character strings.  Do not change these values
- * since they appear in HDF5 files!
+/**
+ * Type of padding to use in character strings.
+ * \internal  Do not change these values since they appear in HDF5 files!
  */
 typedef enum H5T_str_t {
-    H5T_STR_ERROR       = -1, /*error                                      */
-    H5T_STR_NULLTERM    = 0,  /*null terminate like in C                   */
-    H5T_STR_NULLPAD     = 1,  /*pad with nulls                             */
-    H5T_STR_SPACEPAD    = 2,  /*pad with spaces like in Fortran            */
-    H5T_STR_RESERVED_3  = 3,  /*reserved for later use		     */
-    H5T_STR_RESERVED_4  = 4,  /*reserved for later use		     */
-    H5T_STR_RESERVED_5  = 5,  /*reserved for later use		     */
-    H5T_STR_RESERVED_6  = 6,  /*reserved for later use		     */
-    H5T_STR_RESERVED_7  = 7,  /*reserved for later use		     */
-    H5T_STR_RESERVED_8  = 8,  /*reserved for later use		     */
-    H5T_STR_RESERVED_9  = 9,  /*reserved for later use		     */
-    H5T_STR_RESERVED_10 = 10, /*reserved for later use		     */
-    H5T_STR_RESERVED_11 = 11, /*reserved for later use		     */
-    H5T_STR_RESERVED_12 = 12, /*reserved for later use		     */
-    H5T_STR_RESERVED_13 = 13, /*reserved for later use		     */
-    H5T_STR_RESERVED_14 = 14, /*reserved for later use		     */
-    H5T_STR_RESERVED_15 = 15  /*reserved for later use		     */
+    H5T_STR_ERROR        = -1,  /**< error                           */
+    H5T_STR_NULLTERM     = 0,   /**< null terminate like in C        */
+    H5T_STR_NULLPAD      = 1,   /**< pad with nulls                  */
+    H5T_STR_SPACEPAD     = 2,   /**< pad with spaces like in Fortran */
+    H5T_STR_RESERVED_3   = 3,   /**< reserved for later use		     */
+    H5T_STR_RESERVED_4   = 4,   /**< reserved for later use		     */
+    H5T_STR_RESERVED_5   = 5,   /**< reserved for later use		     */
+    H5T_STR_RESERVED_6   = 6,   /**< reserved for later use		     */
+    H5T_STR_RESERVED_7   = 7,   /**< reserved for later use		     */
+    H5T_STR_RESERVED_8   = 8,   /**< reserved for later use		     */
+    H5T_STR_RESERVED_9   = 9,   /**< reserved for later use		     */
+    H5T_STR_RESERVED_10  = 10,  /**< reserved for later use		     */
+    H5T_STR_RESERVED_11  = 11,  /**< reserved for later use		     */
+    H5T_STR_RESERVED_12  = 12,  /**< reserved for later use		     */
+    H5T_STR_RESERVED_13  = 13,  /**< reserved for later use		     */
+    H5T_STR_RESERVED_14  = 14,  /**< reserved for later use		     */
+    H5T_STR_RESERVED_15  = 15   /**< reserved for later use		     */
 } H5T_str_t;
-#define H5T_NSTR H5T_STR_RESERVED_3 /*num H5T_str_t types actually defined	     */
+#define H5T_NSTR H5T_STR_RESERVED_3		/*num H5T_str_t types actually defined	     */
 
-/* Type of padding to use in other atomic types */
+/**
+ * Type of padding to use in other atomic types
+ */
 typedef enum H5T_pad_t {
-    H5T_PAD_ERROR      = -1, /*error                                      */
-    H5T_PAD_ZERO       = 0,  /*always set to zero                         */
-    H5T_PAD_ONE        = 1,  /*always set to one                          */
-    H5T_PAD_BACKGROUND = 2,  /*set to background value                    */
+    H5T_PAD_ERROR        = -1,  /**< error                           */
+    H5T_PAD_ZERO         = 0,   /**< always set to zero              */
+    H5T_PAD_ONE          = 1,   /**< always set to one               */
+    H5T_PAD_BACKGROUND   = 2,   /**< set to background value         */
 
-    H5T_NPAD = 3 /*THIS MUST BE LAST                          */
+    H5T_NPAD             = 3    /*THIS MUST BE LAST                          */
 } H5T_pad_t;
 
-/* Commands sent to conversion functions */
+/**
+ * Commands sent to conversion functions
+ */
 typedef enum H5T_cmd_t {
-    H5T_CONV_INIT = 0, /*query and/or initialize private data	     */
-    H5T_CONV_CONV = 1, /*convert data from source to dest datatype */
-    H5T_CONV_FREE = 2  /*function is being removed from path	     */
+    H5T_CONV_INIT	= 0,	/**< query and/or initialize private data	     */
+    H5T_CONV_CONV	= 1, 	/**< convert data from source to dest datatype */
+    H5T_CONV_FREE	= 2	/**< function is being removed from path	     */
 } H5T_cmd_t;
 
-/* How is the `bkg' buffer used by the conversion function? */
+/**
+ * How is the `bkg' buffer used by the conversion function?
+ */
 typedef enum H5T_bkg_t {
-    H5T_BKG_NO   = 0, /*background buffer is not needed, send NULL */
-    H5T_BKG_TEMP = 1, /*bkg buffer used as temp storage only       */
-    H5T_BKG_YES  = 2  /*init bkg buf with data before conversion   */
+    H5T_BKG_NO		= 0, 	/**< background buffer is not needed, send NULL */
+    H5T_BKG_TEMP	= 1,	/**< bkg buffer used as temp storage only       */
+    H5T_BKG_YES		= 2	/**< init bkg buf with data before conversion   */
 } H5T_bkg_t;
 
-/* Type conversion client data */
+/**
+ * Type conversion client data
+ */
+//! [H5T_cdata_t_snip]
 typedef struct H5T_cdata_t {
-    H5T_cmd_t command;  /*what should the conversion function do?    */
-    H5T_bkg_t need_bkg; /*is the background buffer needed?	     */
-    hbool_t   recalc;   /*recalculate private data		     */
-    void *    priv;     /*private data				     */
+    H5T_cmd_t		command;/**< what should the conversion function do?    */
+    H5T_bkg_t		need_bkg;/**< is the background buffer needed?	     */
+    hbool_t		recalc;	/**< recalculate private data		     */
+    void		*priv;	/**< private data				     */
 } H5T_cdata_t;
+//! [H5T_cdata_t_snip]
 
-/* Conversion function persistence */
+/**
+ * Conversion function persistence
+ */
 typedef enum H5T_pers_t {
-    H5T_PERS_DONTCARE = -1, /*wild card				     */
-    H5T_PERS_HARD     = 0,  /*hard conversion function		     */
-    H5T_PERS_SOFT     = 1   /*soft conversion function		     */
+    H5T_PERS_DONTCARE	= -1, 	/**< wild card				     */
+    H5T_PERS_HARD	= 0,	/**< hard conversion function		     */
+    H5T_PERS_SOFT	= 1 	/**< soft conversion function		     */
 } H5T_pers_t;
 
-/* The order to retrieve atomic native datatype */
+/**
+ * The order to retrieve atomic native datatype
+ */
+//! [H5T_direction_t_snip]
 typedef enum H5T_direction_t {
-    H5T_DIR_DEFAULT = 0, /*default direction is inscendent            */
-    H5T_DIR_ASCEND  = 1, /*in inscendent order                        */
-    H5T_DIR_DESCEND = 2  /*in descendent order                        */
+    H5T_DIR_DEFAULT     = 0,    /**< default direction is inscendent        */
+    H5T_DIR_ASCEND      = 1,    /**< in inscendent order                    */
+    H5T_DIR_DESCEND     = 2     /**< in descendent order                    */
 } H5T_direction_t;
+//! [H5T_direction_t_snip]
 
-/* The exception type passed into the conversion callback function */
+/**
+ * The exception type passed into the conversion callback function
+ */
 typedef enum H5T_conv_except_t {
-    H5T_CONV_EXCEPT_RANGE_HI  = 0, /*source value is greater than destination's range */
-    H5T_CONV_EXCEPT_RANGE_LOW = 1, /*source value is less than destination's range    */
-    H5T_CONV_EXCEPT_PRECISION = 2, /*source value loses precision in destination      */
-    H5T_CONV_EXCEPT_TRUNCATE  = 3, /*source value is truncated in destination         */
-    H5T_CONV_EXCEPT_PINF      = 4, /*source value is positive infinity(floating number) */
-    H5T_CONV_EXCEPT_NINF      = 5, /*source value is negative infinity(floating number) */
-    H5T_CONV_EXCEPT_NAN       = 6  /*source value is NaN(floating number)             */
+    H5T_CONV_EXCEPT_RANGE_HI       = 0,   /**< source value is greater than destination's range */
+    H5T_CONV_EXCEPT_RANGE_LOW      = 1,   /**< source value is less than destination's range    */
+    H5T_CONV_EXCEPT_PRECISION      = 2,   /**< source value loses precision in destination      */
+    H5T_CONV_EXCEPT_TRUNCATE       = 3,   /**< source value is truncated in destination         */
+    H5T_CONV_EXCEPT_PINF           = 4,   /**< source value is positive infinity(floating number) */
+    H5T_CONV_EXCEPT_NINF           = 5,   /**< source value is negative infinity(floating number) */
+    H5T_CONV_EXCEPT_NAN            = 6    /**< source value is NaN(floating number)             */
 } H5T_conv_except_t;
 
-/* The return value from conversion callback function H5T_conv_except_func_t */
+/**
+ * The return value from conversion callback function H5T_conv_except_func_t()
+ */
 typedef enum H5T_conv_ret_t {
-    H5T_CONV_ABORT     = -1, /*abort conversion                           */
-    H5T_CONV_UNHANDLED = 0,  /*callback function failed to handle the exception      */
-    H5T_CONV_HANDLED   = 1   /*callback function handled the exception successfully  */
+    H5T_CONV_ABORT      = -1,   /**< abort conversion                           */
+    H5T_CONV_UNHANDLED  = 0,    /**< callback function failed to handle the exception      */
+    H5T_CONV_HANDLED    = 1     /**< callback function handled the exception successfully  */
 } H5T_conv_ret_t;
 
-/* Variable Length Datatype struct in memory */
-/* (This is only used for VL sequences, not VL strings, which are stored in char *'s) */
+/**
+ * Variable Length Datatype struct in memory (This is only used for VL
+ * sequences, not VL strings, which are stored in char *'s)
+ */
 typedef struct {
-    size_t len; /* Length of VL data (in base type units) */
-    void * p;   /* Pointer to VL data */
+    size_t len; /**< Length of VL data (in base type units) */
+    void *p;    /**< Pointer to VL data */
 } hvl_t;
 
 /* Variable Length String information */
-#define H5T_VARIABLE                                                                                         \
-    ((size_t)(                                                                                               \
-        -1)) /* Indicate that a string is variable length (null-terminated in C, instead of fixed length) */
+/**
+ * Indicate that a string is variable length (null-terminated in C, instead of
+ * fixed length)
+ */
+#define H5T_VARIABLE    ((size_t)(-1))
 
 /* Opaque information */
-#define H5T_OPAQUE_TAG_MAX 256 /* Maximum length of an opaque tag */
-                               /* This could be raised without too much difficulty */
+/**
+ * Maximum length of an opaque tag
+ * \internal This could be raised without too much difficulty
+ */
+#define H5T_OPAQUE_TAG_MAX      256
 
 #ifdef __cplusplus
 extern "C" {
 #endif
 
-/* All datatype conversion functions are... */
-typedef herr_t (*H5T_conv_t)(hid_t src_id, hid_t dst_id, H5T_cdata_t *cdata, size_t nelmts, size_t buf_stride,
-                             size_t bkg_stride, void *buf, void *bkg, hid_t dset_xfer_plist);
+/**
+ * All datatype conversion functions are...
+ */
+//! [H5T_conv_t_snip]
+typedef herr_t (*H5T_conv_t) (hid_t src_id, hid_t dst_id, H5T_cdata_t *cdata,
+      size_t nelmts, size_t buf_stride, size_t bkg_stride, void *buf,
+      void *bkg, hid_t dset_xfer_plist);
+//! [H5T_conv_t_snip]
 
-/* Exception handler.  If an exception like overflow happenes during conversion,
- * this function is called if it's registered through H5Pset_type_conv_cb.
+/**
+ * Exception handler.  If an exception like overflow happenes during conversion,
+ * this function is called if it's registered through H5Pset_type_conv_cb().
  */
-typedef H5T_conv_ret_t (*H5T_conv_except_func_t)(H5T_conv_except_t except_type, hid_t src_id, hid_t dst_id,
-                                                 void *src_buf, void *dst_buf, void *user_data);
+typedef H5T_conv_ret_t (*H5T_conv_except_func_t)(H5T_conv_except_t except_type,
+    hid_t src_id, hid_t dst_id, void *src_buf, void *dst_buf, void *user_data);
 
 /* When this header is included from a private header, don't make calls to H5open() */
 #undef H5OPEN
@@ -226,10 +270,26 @@ typedef H5T_conv_ret_t (*H5T_conv_except_func_t)(H5T_conv_except_t except_type,
 /*
  * The IEEE floating point types in various byte orders.
  */
-#define H5T_IEEE_F32BE (H5OPEN H5T_IEEE_F32BE_g)
-#define H5T_IEEE_F32LE (H5OPEN H5T_IEEE_F32LE_g)
-#define H5T_IEEE_F64BE (H5OPEN H5T_IEEE_F64BE_g)
-#define H5T_IEEE_F64LE (H5OPEN H5T_IEEE_F64LE_g)
+/**
+ * \ingroup PDTIEEE
+ * 32-bit big-endian IEEE floating-point numbers
+ */
+#define H5T_IEEE_F32BE		(H5OPEN H5T_IEEE_F32BE_g)
+/**
+ * \ingroup PDTIEEE
+ * 32-bit little-endian IEEE floating-point numbers
+ */
+#define H5T_IEEE_F32LE		(H5OPEN H5T_IEEE_F32LE_g)
+/**
+ * \ingroup PDTIEEE
+ * 64-bit big-endian IEEE floating-point numbers
+ */
+#define H5T_IEEE_F64BE		(H5OPEN H5T_IEEE_F64BE_g)
+/**
+ * \ingroup PDTIEEE
+ * 64-bit little-endian IEEE floating-point numbers
+ */
+#define H5T_IEEE_F64LE		(H5OPEN H5T_IEEE_F64LE_g)
 H5_DLLVAR hid_t H5T_IEEE_F32BE_g;
 H5_DLLVAR hid_t H5T_IEEE_F32LE_g;
 H5_DLLVAR hid_t H5T_IEEE_F64BE_g;
@@ -239,33 +299,141 @@ H5_DLLVAR hid_t H5T_IEEE_F64LE_g;
  * These are "standard" types.  For instance, signed (2's complement) and
  * unsigned integers of various sizes and byte orders.
  */
-#define H5T_STD_I8BE        (H5OPEN H5T_STD_I8BE_g)
-#define H5T_STD_I8LE        (H5OPEN H5T_STD_I8LE_g)
-#define H5T_STD_I16BE       (H5OPEN H5T_STD_I16BE_g)
-#define H5T_STD_I16LE       (H5OPEN H5T_STD_I16LE_g)
-#define H5T_STD_I32BE       (H5OPEN H5T_STD_I32BE_g)
-#define H5T_STD_I32LE       (H5OPEN H5T_STD_I32LE_g)
-#define H5T_STD_I64BE       (H5OPEN H5T_STD_I64BE_g)
-#define H5T_STD_I64LE       (H5OPEN H5T_STD_I64LE_g)
-#define H5T_STD_U8BE        (H5OPEN H5T_STD_U8BE_g)
-#define H5T_STD_U8LE        (H5OPEN H5T_STD_U8LE_g)
-#define H5T_STD_U16BE       (H5OPEN H5T_STD_U16BE_g)
-#define H5T_STD_U16LE       (H5OPEN H5T_STD_U16LE_g)
-#define H5T_STD_U32BE       (H5OPEN H5T_STD_U32BE_g)
-#define H5T_STD_U32LE       (H5OPEN H5T_STD_U32LE_g)
-#define H5T_STD_U64BE       (H5OPEN H5T_STD_U64BE_g)
-#define H5T_STD_U64LE       (H5OPEN H5T_STD_U64LE_g)
-#define H5T_STD_B8BE        (H5OPEN H5T_STD_B8BE_g)
-#define H5T_STD_B8LE        (H5OPEN H5T_STD_B8LE_g)
-#define H5T_STD_B16BE       (H5OPEN H5T_STD_B16BE_g)
-#define H5T_STD_B16LE       (H5OPEN H5T_STD_B16LE_g)
-#define H5T_STD_B32BE       (H5OPEN H5T_STD_B32BE_g)
-#define H5T_STD_B32LE       (H5OPEN H5T_STD_B32LE_g)
-#define H5T_STD_B64BE       (H5OPEN H5T_STD_B64BE_g)
-#define H5T_STD_B64LE       (H5OPEN H5T_STD_B64LE_g)
-#define H5T_STD_REF_OBJ     (H5OPEN H5T_STD_REF_OBJ_g)
-#define H5T_STD_REF_DSETREG (H5OPEN H5T_STD_REF_DSETREG_g)
-#define H5T_STD_REF         (H5OPEN H5T_STD_REF_g)
+/**
+ * \ingroup PDTSTD
+ * 8-bit big-endian signed integers
+ */
+#define H5T_STD_I8BE		(H5OPEN H5T_STD_I8BE_g)
+/**
+ * \ingroup PDTSTD
+ * 8-bit little-endian signed integers
+ */
+#define H5T_STD_I8LE		(H5OPEN H5T_STD_I8LE_g)
+/**
+ * \ingroup PDTSTD
+ * 16-bit big-endian signed integers
+ */
+#define H5T_STD_I16BE		(H5OPEN H5T_STD_I16BE_g)
+/**
+ * \ingroup PDTSTD
+ * 16-bit little-endian signed integers
+ */
+#define H5T_STD_I16LE		(H5OPEN H5T_STD_I16LE_g)
+/**
+ * \ingroup PDTSTD
+ * 32-bit big-endian signed integers
+ */
+#define H5T_STD_I32BE		(H5OPEN H5T_STD_I32BE_g)
+/**
+ * \ingroup PDTSTD
+ * 32-bit little-endian signed integers
+ */
+#define H5T_STD_I32LE		(H5OPEN H5T_STD_I32LE_g)
+/**
+ * \ingroup PDTSTD
+ * 64-bit big-endian signed integers
+ */
+#define H5T_STD_I64BE		(H5OPEN H5T_STD_I64BE_g)
+/**
+ * \ingroup PDTSTD
+ * 64-bit little-endian signed integers
+ */
+#define H5T_STD_I64LE		(H5OPEN H5T_STD_I64LE_g)
+/**
+ * \ingroup PDTSTD
+ * 8-bit big-endian unsigned integers
+ */
+#define H5T_STD_U8BE		(H5OPEN H5T_STD_U8BE_g)
+/**
+ * \ingroup PDTSTD
+ * 8-bit little-endian unsigned integers
+ */
+#define H5T_STD_U8LE		(H5OPEN H5T_STD_U8LE_g)
+/**
+ * \ingroup PDTSTD
+ * 16-bit big-endian unsigned integers
+ */
+#define H5T_STD_U16BE		(H5OPEN H5T_STD_U16BE_g)
+/**
+ * \ingroup PDTSTD
+ * 16-bit little-endian unsigned integers
+ */
+#define H5T_STD_U16LE		(H5OPEN H5T_STD_U16LE_g)
+/**
+ * \ingroup PDTSTD
+ * 32-bit big-endian unsigned integers
+ */
+#define H5T_STD_U32BE		(H5OPEN H5T_STD_U32BE_g)
+/**
+ * \ingroup PDTSTD
+ * 32-bit little-endian unsigned integers
+ */
+#define H5T_STD_U32LE		(H5OPEN H5T_STD_U32LE_g)
+/**
+ * \ingroup PDTSTD
+ * 64-bit big-endian unsigned integers
+ */
+#define H5T_STD_U64BE		(H5OPEN H5T_STD_U64BE_g)
+/**
+ * \ingroup PDTSTD
+ * 64-bit little-endian unsigned integers
+ */
+#define H5T_STD_U64LE		(H5OPEN H5T_STD_U64LE_g)
+/**
+ * \ingroup PDTSTD
+ * 8-bit big-endian bitfield
+ */
+#define H5T_STD_B8BE		(H5OPEN H5T_STD_B8BE_g)
+/**
+ * \ingroup PDTSTD
+ * 8-bit little-endian bitfield
+ */
+#define H5T_STD_B8LE		(H5OPEN H5T_STD_B8LE_g)
+/**
+ * \ingroup PDTSTD
+ * 16-bit big-endian bitfield
+ */
+#define H5T_STD_B16BE		(H5OPEN H5T_STD_B16BE_g)
+/**
+ * \ingroup PDTSTD
+ * 16-bit little-endian bitfield
+ */
+#define H5T_STD_B16LE		(H5OPEN H5T_STD_B16LE_g)
+/**
+ * \ingroup PDTSTD
+ * 32-bit big-endian bitfield
+ */
+#define H5T_STD_B32BE		(H5OPEN H5T_STD_B32BE_g)
+/**
+ * \ingroup PDTSTD
+ * 32-bit little-endian bitfield
+ */
+#define H5T_STD_B32LE		(H5OPEN H5T_STD_B32LE_g)
+/**
+ * \ingroup PDTSTD
+ * 64-bit big-endian bitfield
+ */
+#define H5T_STD_B64BE		(H5OPEN H5T_STD_B64BE_g)
+/**
+ * \ingroup PDTSTD
+ * 64-bit little-endian bitfield
+ */
+#define H5T_STD_B64LE		(H5OPEN H5T_STD_B64LE_g)
+/**
+ * \ingroup PDTSTD
+ * Object reference
+ */
+#define H5T_STD_REF_OBJ         (H5OPEN H5T_STD_REF_OBJ_g)
+/**
+ * \ingroup PDTSTD
+ * Dataset region reference
+ */
+#define H5T_STD_REF_DSETREG     (H5OPEN H5T_STD_REF_DSETREG_g)
+/**
+ * \ingroup PDTSTD
+ * Generic reference
+ */
+#define H5T_STD_REF             (H5OPEN H5T_STD_REF_g)
 H5_DLLVAR hid_t H5T_STD_I8BE_g;
 H5_DLLVAR hid_t H5T_STD_I8LE_g;
 H5_DLLVAR hid_t H5T_STD_I16BE_g;
@@ -297,10 +465,22 @@ H5_DLLVAR hid_t H5T_STD_REF_g;
 /*
  * Types which are particular to Unix.
  */
-#define H5T_UNIX_D32BE (H5OPEN H5T_UNIX_D32BE_g)
-#define H5T_UNIX_D32LE (H5OPEN H5T_UNIX_D32LE_g)
-#define H5T_UNIX_D64BE (H5OPEN H5T_UNIX_D64BE_g)
-#define H5T_UNIX_D64LE (H5OPEN H5T_UNIX_D64LE_g)
+/**
+ * \ingroup PDTUNIX
+ */
+#define H5T_UNIX_D32BE		(H5OPEN H5T_UNIX_D32BE_g)
+/**
+ * \ingroup PDTUNIX
+ */
+#define H5T_UNIX_D32LE		(H5OPEN H5T_UNIX_D32LE_g)
+/**
+ * \ingroup PDTUNIX
+ */
+#define H5T_UNIX_D64BE		(H5OPEN H5T_UNIX_D64BE_g)
+/**
+ * \ingroup PDTUNIX
+ */
+#define H5T_UNIX_D64LE		(H5OPEN H5T_UNIX_D64LE_g)
 H5_DLLVAR hid_t H5T_UNIX_D32BE_g;
 H5_DLLVAR hid_t H5T_UNIX_D32LE_g;
 H5_DLLVAR hid_t H5T_UNIX_D64BE_g;
@@ -310,12 +490,20 @@ H5_DLLVAR hid_t H5T_UNIX_D64LE_g;
  * Types particular to the C language.  String types use `bytes' instead
  * of `bits' as their size.
  */
+/**
+ * \ingroup PDTS
+ * String datatype in C (size defined in bytes rather than in bits)
+ */
 #define H5T_C_S1 (H5OPEN H5T_C_S1_g)
 H5_DLLVAR hid_t H5T_C_S1_g;
 
 /*
  * Types particular to Fortran.
  */
+/**
+ * \ingroup PDTS
+ * String datatype in Fortran (as defined for the HDF5 C library)
+ */
 #define H5T_FORTRAN_S1 (H5OPEN H5T_FORTRAN_S1_g)
 H5_DLLVAR hid_t H5T_FORTRAN_S1_g;
 
@@ -323,63 +511,239 @@ H5_DLLVAR hid_t H5T_FORTRAN_S1_g;
  * These types are for Intel CPU's.  They are little endian with IEEE
  * floating point.
  */
-#define H5T_INTEL_I8  H5T_STD_I8LE
-#define H5T_INTEL_I16 H5T_STD_I16LE
-#define H5T_INTEL_I32 H5T_STD_I32LE
-#define H5T_INTEL_I64 H5T_STD_I64LE
-#define H5T_INTEL_U8  H5T_STD_U8LE
-#define H5T_INTEL_U16 H5T_STD_U16LE
-#define H5T_INTEL_U32 H5T_STD_U32LE
-#define H5T_INTEL_U64 H5T_STD_U64LE
-#define H5T_INTEL_B8  H5T_STD_B8LE
-#define H5T_INTEL_B16 H5T_STD_B16LE
-#define H5T_INTEL_B32 H5T_STD_B32LE
-#define H5T_INTEL_B64 H5T_STD_B64LE
-#define H5T_INTEL_F32 H5T_IEEE_F32LE
-#define H5T_INTEL_F64 H5T_IEEE_F64LE
+/**
+ * \ingroup PDTX86
+ * 8-bit little-endian signed (2's complement) integers for Intel CPUs
+ */
+#define H5T_INTEL_I8		H5T_STD_I8LE
+/**
+ * \ingroup PDTX86
+ * 16-bit little-endian signed (2's complement) integers for Intel CPUs
+ */
+#define H5T_INTEL_I16		H5T_STD_I16LE
+/**
+ * \ingroup PDTX86
+ * 32-bit little-endian signed (2's complement) integers for Intel CPUs
+ */
+#define H5T_INTEL_I32		H5T_STD_I32LE
+/**
+ * \ingroup PDTX86
+ * 64-bit little-endian signed (2's complement) integers for Intel CPUs
+ */
+#define H5T_INTEL_I64		H5T_STD_I64LE
+/**
+ * \ingroup PDTX86
+ * 8-bit little-endian unsigned integers for Intel CPUs
+ */
+#define H5T_INTEL_U8		H5T_STD_U8LE
+/**
+ * \ingroup PDTX86
+ * 16-bit little-endian unsigned integers for Intel CPUs
+ */
+#define H5T_INTEL_U16		H5T_STD_U16LE
+/**
+ * \ingroup PDTX86
+ * 32-bit little-endian unsigned integers for Intel CPUs
+ */
+#define H5T_INTEL_U32		H5T_STD_U32LE
+/**
+ * \ingroup PDTX86
+ * 64-bit little-endian unsigned integers for Intel CPUs
+ */
+#define H5T_INTEL_U64		H5T_STD_U64LE
+/**
+ * \ingroup PDTX86
+ * 8-bit little-endian bitfield for Intel CPUs
+ */
+#define H5T_INTEL_B8		H5T_STD_B8LE
+/**
+ * \ingroup PDTX86
+ * 16-bit little-endian bitfield for Intel CPUs
+ */
+#define H5T_INTEL_B16		H5T_STD_B16LE
+/**
+ * \ingroup PDTX86
+ * 32-bit little-endian bitfield for Intel CPUs
+ */
+#define H5T_INTEL_B32		H5T_STD_B32LE
+/**
+ * \ingroup PDTX86
+ * 64-bit little-endian bitfield for Intel CPUs
+ */
+#define H5T_INTEL_B64		H5T_STD_B64LE
+/**
+ * \ingroup PDTX86
+ * 32-bit little-endian IEEE floating-point numbers for Intel CPUs
+ */
+#define H5T_INTEL_F32		H5T_IEEE_F32LE
+/**
+ * \ingroup PDTX86
+ * 64-bit little-endian IEEE floating-point numbers for Intel CPUs
+ */
+#define H5T_INTEL_F64		H5T_IEEE_F64LE
 
 /*
  * These types are for DEC Alpha CPU's.  They are little endian with IEEE
  * floating point.
  */
-#define H5T_ALPHA_I8  H5T_STD_I8LE
-#define H5T_ALPHA_I16 H5T_STD_I16LE
-#define H5T_ALPHA_I32 H5T_STD_I32LE
-#define H5T_ALPHA_I64 H5T_STD_I64LE
-#define H5T_ALPHA_U8  H5T_STD_U8LE
-#define H5T_ALPHA_U16 H5T_STD_U16LE
-#define H5T_ALPHA_U32 H5T_STD_U32LE
-#define H5T_ALPHA_U64 H5T_STD_U64LE
-#define H5T_ALPHA_B8  H5T_STD_B8LE
-#define H5T_ALPHA_B16 H5T_STD_B16LE
-#define H5T_ALPHA_B32 H5T_STD_B32LE
-#define H5T_ALPHA_B64 H5T_STD_B64LE
-#define H5T_ALPHA_F32 H5T_IEEE_F32LE
-#define H5T_ALPHA_F64 H5T_IEEE_F64LE
+/**
+ * \ingroup PDTALPHA
+ * 8-bit little-endian signed (2's complement) integers for DEC Alpha CPUs
+ */
+#define H5T_ALPHA_I8		H5T_STD_I8LE
+/**
+ * \ingroup PDTALPHA
+ * 16-bit little-endian signed (2's complement) integers for DEC Alpha CPUs
+ */
+#define H5T_ALPHA_I16		H5T_STD_I16LE
+/**
+ * \ingroup PDTALPHA
+ * 32-bit little-endian signed (2's complement) integers for DEC Alpha CPUs
+ */
+#define H5T_ALPHA_I32		H5T_STD_I32LE
+/**
+ * \ingroup PDTALPHA
+ * 64-bit little-endian signed (2's complement) integers for DEC Alpha CPUs
+ */
+#define H5T_ALPHA_I64		H5T_STD_I64LE
+/**
+ * \ingroup PDTALPHA
+ * 8-bit little-endian unsigned integers for DEC Alpha CPUs
+ */
+#define H5T_ALPHA_U8		H5T_STD_U8LE
+/**
+ * \ingroup PDTALPHA
+ * 16-bit little-endian unsigned integers for DEC Alpha CPUs
+ */
+#define H5T_ALPHA_U16		H5T_STD_U16LE
+/**
+ * \ingroup PDTALPHA
+ * 32-bit little-endian unsigned integers for DEC Alpha CPUs
+ */
+#define H5T_ALPHA_U32		H5T_STD_U32LE
+/**
+ * \ingroup PDTALPHA
+ * 64-bit little-endian unsigned integers for DEC Alpha CPUs
+ */
+#define H5T_ALPHA_U64		H5T_STD_U64LE
+/**
+ * \ingroup PDTALPHA
+ * 8-bit little-endian bitfield for DEC Alpha CPUs
+ */
+#define H5T_ALPHA_B8		H5T_STD_B8LE
+/**
+ * \ingroup PDTALPHA
+ * 16-bit little-endian bitfield for DEC Alpha CPUs
+ */
+#define H5T_ALPHA_B16		H5T_STD_B16LE
+/**
+ * \ingroup PDTALPHA
+ * 32-bit little-endian bitfield for DEC Alpha CPUs
+ */
+#define H5T_ALPHA_B32		H5T_STD_B32LE
+/**
+ * \ingroup PDTALPHA
+ * 64-bit little-endian bitfield for DEC Alpha CPUs
+ */
+#define H5T_ALPHA_B64		H5T_STD_B64LE
+/**
+ * \ingroup PDTALPHA
+ * 32-bit little-endian IEEE floating-point numbers for DEC Alpha CPUs
+ */
+#define H5T_ALPHA_F32		H5T_IEEE_F32LE
+/**
+ * \ingroup PDTALPHA
+ * 64-bit little-endian IEEE floating-point numbers for DEC Alpha CPUs
+ */
+#define H5T_ALPHA_F64		H5T_IEEE_F64LE
 
 /*
  * These types are for MIPS cpu's commonly used in SGI systems. They are big
  * endian with IEEE floating point.
  */
-#define H5T_MIPS_I8  H5T_STD_I8BE
-#define H5T_MIPS_I16 H5T_STD_I16BE
-#define H5T_MIPS_I32 H5T_STD_I32BE
-#define H5T_MIPS_I64 H5T_STD_I64BE
-#define H5T_MIPS_U8  H5T_STD_U8BE
-#define H5T_MIPS_U16 H5T_STD_U16BE
-#define H5T_MIPS_U32 H5T_STD_U32BE
-#define H5T_MIPS_U64 H5T_STD_U64BE
-#define H5T_MIPS_B8  H5T_STD_B8BE
-#define H5T_MIPS_B16 H5T_STD_B16BE
-#define H5T_MIPS_B32 H5T_STD_B32BE
-#define H5T_MIPS_B64 H5T_STD_B64BE
-#define H5T_MIPS_F32 H5T_IEEE_F32BE
-#define H5T_MIPS_F64 H5T_IEEE_F64BE
+/**
+ * \ingroup PDTMIPS
+ * 8-bit big-endian signed (2's complement) integers for SGI MIPS CPUs
+ */
+#define H5T_MIPS_I8		H5T_STD_I8BE
+/**
+ * \ingroup PDTMIPS
+ * 16-bit big-endian signed (2's complement) integers for SGI MIPS CPUs
+ */
+#define H5T_MIPS_I16		H5T_STD_I16BE
+/**
+ * \ingroup PDTMIPS
+ * 32-bit big-endian signed (2's complement) integers for SGI MIPS CPUs
+ */
+#define H5T_MIPS_I32		H5T_STD_I32BE
+/**
+ * \ingroup PDTMIPS
+ * 64-bit big-endian signed (2's complement) integers for SGI MIPS CPUs
+ */
+#define H5T_MIPS_I64		H5T_STD_I64BE
+/**
+ * \ingroup PDTMIPS
+ * 8-bit big-endian unsigned integers for SGI MIPS CPUs
+ */
+#define H5T_MIPS_U8		H5T_STD_U8BE
+/**
+ * \ingroup PDTMIPS
+ * 16-bit big-endian unsigned integers for SGI MIPS CPUs
+ */
+#define H5T_MIPS_U16		H5T_STD_U16BE
+/**
+ * \ingroup PDTMIPS
+ * 32-bit big-endian unsigned integers for SGI MIPS CPUs
+ */
+#define H5T_MIPS_U32		H5T_STD_U32BE
+/**
+ * \ingroup PDTMIPS
+ * 64-bit big-endian unsigned integers for SGI MIPS CPUs
+ */
+#define H5T_MIPS_U64		H5T_STD_U64BE
+/**
+ * \ingroup PDTMIPS
+ * 8-bit big-endian bitfield for SGI MIPS CPUs
+ */
+#define H5T_MIPS_B8		H5T_STD_B8BE
+/**
+ * \ingroup PDTMIPS
+ * 16-bit big-endian bitfield for SGI MIPS CPUs
+ */
+#define H5T_MIPS_B16		H5T_STD_B16BE
+/**
+ * \ingroup PDTMIPS
+ * 32-bit big-endian bitfield for SGI MIPS CPUs
+ */
+#define H5T_MIPS_B32		H5T_STD_B32BE
+/**
+ * \ingroup PDTMIPS
+ * 64-bit big-endian bitfield for SGI MIPS CPUs
+ */
+#define H5T_MIPS_B64		H5T_STD_B64BE
+/**
+ * \ingroup PDTMIPS
+ * 32-bit big-endian IEEE floating-point numbers for MIPS CPUs
+ */
+#define H5T_MIPS_F32		H5T_IEEE_F32BE
+/**
+ * \ingroup PDTMIPS
+ * 64-bit big-endian IEEE floating-point numbers for MIPS CPUs
+ */
+#define H5T_MIPS_F64		H5T_IEEE_F64BE
 
 /*
  * The VAX floating point types (i.e. in VAX byte order)
  */
+/**
+ * \ingroup PDTALPHA
+ * 32-bit VAX byte order floating-point numbers for OpenVMS on DEC Alpha CPUs
+ */
 #define H5T_VAX_F32 (H5OPEN H5T_VAX_F32_g)
+/**
+ * \ingroup PDTALPHA
+ * 64-bit VAX byte order floating-point numbers for OpenVMS on DEC Alpha CPUs
+ */
 #define H5T_VAX_F64 (H5OPEN H5T_VAX_F64_g)
 H5_DLLVAR hid_t H5T_VAX_F32_g;
 H5_DLLVAR hid_t H5T_VAX_F64_g;
@@ -393,32 +757,128 @@ H5_DLLVAR hid_t H5T_VAX_F64_g;
  * to C's `long long' and LDOUBLE is `long double' (these types might be the
  * same as `LONG' and `DOUBLE' respectively).
  */
-#define H5T_NATIVE_CHAR   (CHAR_MIN ? H5T_NATIVE_SCHAR : H5T_NATIVE_UCHAR)
+/**
+ * \ingroup PDTNAT
+ * C-style \c char
+ */
+#define H5T_NATIVE_CHAR	  (CHAR_MIN?H5T_NATIVE_SCHAR:H5T_NATIVE_UCHAR)
+/**
+ * \ingroup PDTNAT
+ * C-style \Code{signed char}
+ */
 #define H5T_NATIVE_SCHAR  (H5OPEN H5T_NATIVE_SCHAR_g)
+/**
+ * \ingroup PDTNAT
+ * C-style \Code{unsigned char}
+ */
 #define H5T_NATIVE_UCHAR  (H5OPEN H5T_NATIVE_UCHAR_g)
+/**
+ * \ingroup PDTNAT
+ * C-style \Code{short}
+ */
 #define H5T_NATIVE_SHORT  (H5OPEN H5T_NATIVE_SHORT_g)
+/**
+ * \ingroup PDTNAT
+ * C-style \Code{unsigned short}
+ */
 #define H5T_NATIVE_USHORT (H5OPEN H5T_NATIVE_USHORT_g)
+/**
+ * \ingroup PDTNAT
+ * C-style \Code{int}
+ */
 #define H5T_NATIVE_INT    (H5OPEN H5T_NATIVE_INT_g)
+/**
+ * \ingroup PDTNAT
+ * C-style \Code{unsigned int}
+ */
 #define H5T_NATIVE_UINT   (H5OPEN H5T_NATIVE_UINT_g)
+/**
+ * \ingroup PDTNAT
+ * C-style \Code{long}
+ */
 #define H5T_NATIVE_LONG   (H5OPEN H5T_NATIVE_LONG_g)
+/**
+ * \ingroup PDTNAT
+ * C-style \Code{unsigned long}
+ */
 #define H5T_NATIVE_ULONG  (H5OPEN H5T_NATIVE_ULONG_g)
+/**
+ * \ingroup PDTNAT
+ * C-style \Code{long long}
+ */
 #define H5T_NATIVE_LLONG  (H5OPEN H5T_NATIVE_LLONG_g)
+/**
+ * \ingroup PDTNAT
+ * C-style \Code{unsigned long long}
+ */
 #define H5T_NATIVE_ULLONG (H5OPEN H5T_NATIVE_ULLONG_g)
+/**
+ * \ingroup PDTNAT
+ * C-style \Code{float}
+ */
 #define H5T_NATIVE_FLOAT  (H5OPEN H5T_NATIVE_FLOAT_g)
+/**
+ * \ingroup PDTNAT
+ * C-style \Code{double}
+ */
 #define H5T_NATIVE_DOUBLE (H5OPEN H5T_NATIVE_DOUBLE_g)
-#if H5_SIZEOF_LONG_DOUBLE != 0
+#if H5_SIZEOF_LONG_DOUBLE !=0
+/**
+ * \ingroup PDTNAT
+ * C-style \Code{long double}
+ */
 #define H5T_NATIVE_LDOUBLE (H5OPEN H5T_NATIVE_LDOUBLE_g)
 #endif
+/**
+ * \ingroup PDTNAT
+ * HDF5 8-bit bitfield based on native types
+ */
 #define H5T_NATIVE_B8     (H5OPEN H5T_NATIVE_B8_g)
+/**
+ * \ingroup PDTNAT
+ * HDF5 16-bit bitfield based on native types
+ */
 #define H5T_NATIVE_B16    (H5OPEN H5T_NATIVE_B16_g)
+/**
+ * \ingroup PDTNAT
+ * HDF5 32-bit bitfield based on native types
+ */
 #define H5T_NATIVE_B32    (H5OPEN H5T_NATIVE_B32_g)
-#define H5T_NATIVE_B64    (H5OPEN H5T_NATIVE_B64_g)
+/**
+ * \ingroup PDTNAT
+ * HDF5 64-bit bitfield based on native types
+ */
+#define H5T_NATIVE_B64	  (H5OPEN H5T_NATIVE_B64_g)
+/**
+ * \ingroup PDTNAT
+ * HDF5 opaque unit based on native types
+ */
 #define H5T_NATIVE_OPAQUE (H5OPEN H5T_NATIVE_OPAQUE_g)
+/**
+ * \ingroup PDTNAT
+ * HDF5 address type based on native types
+ */
 #define H5T_NATIVE_HADDR  (H5OPEN H5T_NATIVE_HADDR_g)
+/**
+ * \ingroup PDTNAT
+ * HDF5 size type based on native types
+ */
 #define H5T_NATIVE_HSIZE  (H5OPEN H5T_NATIVE_HSIZE_g)
+/**
+ * \ingroup PDTNAT
+ * HDF5 signed size type based on native types
+ */
 #define H5T_NATIVE_HSSIZE (H5OPEN H5T_NATIVE_HSSIZE_g)
-#define H5T_NATIVE_HERR   (H5OPEN H5T_NATIVE_HERR_g)
-#define H5T_NATIVE_HBOOL  (H5OPEN H5T_NATIVE_HBOOL_g)
+/**
+ * \ingroup PDTNAT
+ * HDF5 error code type based on native types
+ */
+#define H5T_NATIVE_HERR	  (H5OPEN H5T_NATIVE_HERR_g)
+/**
+ * \ingroup PDTNAT
+ * HDF5 Boolean type based on native types
+ */
+#define H5T_NATIVE_HBOOL	(H5OPEN H5T_NATIVE_HBOOL_g)
 H5_DLLVAR hid_t H5T_NATIVE_SCHAR_g;
 H5_DLLVAR hid_t H5T_NATIVE_UCHAR_g;
 H5_DLLVAR hid_t H5T_NATIVE_SHORT_g;
@@ -446,12 +906,30 @@ H5_DLLVAR hid_t H5T_NATIVE_HERR_g;
 H5_DLLVAR hid_t H5T_NATIVE_HBOOL_g;
 
 /* C9x integer types */
-#define H5T_NATIVE_INT8        (H5OPEN H5T_NATIVE_INT8_g)
-#define H5T_NATIVE_UINT8       (H5OPEN H5T_NATIVE_UINT8_g)
+/**
+ * \ingroup PDTC9x
+ */
+#define H5T_NATIVE_INT8	       (H5OPEN H5T_NATIVE_INT8_g)
+/**
+ * \ingroup PDTC9x
+ */
+#define H5T_NATIVE_UINT8	   (H5OPEN H5T_NATIVE_UINT8_g)
+/**
+ * \ingroup PDTC9x
+ */
 #define H5T_NATIVE_INT_LEAST8  (H5OPEN H5T_NATIVE_INT_LEAST8_g)
-#define H5T_NATIVE_UINT_LEAST8 (H5OPEN H5T_NATIVE_UINT_LEAST8_g)
-#define H5T_NATIVE_INT_FAST8   (H5OPEN H5T_NATIVE_INT_FAST8_g)
-#define H5T_NATIVE_UINT_FAST8  (H5OPEN H5T_NATIVE_UINT_FAST8_g)
+/**
+ * \ingroup PDTC9x
+ */
+#define H5T_NATIVE_UINT_LEAST8  (H5OPEN H5T_NATIVE_UINT_LEAST8_g)
+/**
+ * \ingroup PDTC9x
+ */
+#define H5T_NATIVE_INT_FAST8 	(H5OPEN H5T_NATIVE_INT_FAST8_g)
+/**
+ * \ingroup PDTC9x
+ */
+#define H5T_NATIVE_UINT_FAST8	(H5OPEN H5T_NATIVE_UINT_FAST8_g)
 H5_DLLVAR hid_t H5T_NATIVE_INT8_g;
 H5_DLLVAR hid_t H5T_NATIVE_UINT8_g;
 H5_DLLVAR hid_t H5T_NATIVE_INT_LEAST8_g;
@@ -459,12 +937,30 @@ H5_DLLVAR hid_t H5T_NATIVE_UINT_LEAST8_g;
 H5_DLLVAR hid_t H5T_NATIVE_INT_FAST8_g;
 H5_DLLVAR hid_t H5T_NATIVE_UINT_FAST8_g;
 
-#define H5T_NATIVE_INT16        (H5OPEN H5T_NATIVE_INT16_g)
-#define H5T_NATIVE_UINT16       (H5OPEN H5T_NATIVE_UINT16_g)
-#define H5T_NATIVE_INT_LEAST16  (H5OPEN H5T_NATIVE_INT_LEAST16_g)
-#define H5T_NATIVE_UINT_LEAST16 (H5OPEN H5T_NATIVE_UINT_LEAST16_g)
-#define H5T_NATIVE_INT_FAST16   (H5OPEN H5T_NATIVE_INT_FAST16_g)
-#define H5T_NATIVE_UINT_FAST16  (H5OPEN H5T_NATIVE_UINT_FAST16_g)
+/**
+ * \ingroup PDTC9x
+ */
+#define H5T_NATIVE_INT16		(H5OPEN H5T_NATIVE_INT16_g)
+/**
+ * \ingroup PDTC9x
+ */
+#define H5T_NATIVE_UINT16		(H5OPEN H5T_NATIVE_UINT16_g)
+/**
+ * \ingroup PDTC9x
+ */
+#define H5T_NATIVE_INT_LEAST16	(H5OPEN H5T_NATIVE_INT_LEAST16_g)
+/**
+ * \ingroup PDTC9x
+ */
+#define H5T_NATIVE_UINT_LEAST16	(H5OPEN H5T_NATIVE_UINT_LEAST16_g)
+/**
+ * \ingroup PDTC9x
+ */
+#define H5T_NATIVE_INT_FAST16	(H5OPEN H5T_NATIVE_INT_FAST16_g)
+/**
+ * \ingroup PDTC9x
+ */
+#define H5T_NATIVE_UINT_FAST16	(H5OPEN H5T_NATIVE_UINT_FAST16_g)
 H5_DLLVAR hid_t H5T_NATIVE_INT16_g;
 H5_DLLVAR hid_t H5T_NATIVE_UINT16_g;
 H5_DLLVAR hid_t H5T_NATIVE_INT_LEAST16_g;
@@ -472,12 +968,30 @@ H5_DLLVAR hid_t H5T_NATIVE_UINT_LEAST16_g;
 H5_DLLVAR hid_t H5T_NATIVE_INT_FAST16_g;
 H5_DLLVAR hid_t H5T_NATIVE_UINT_FAST16_g;
 
-#define H5T_NATIVE_INT32        (H5OPEN H5T_NATIVE_INT32_g)
-#define H5T_NATIVE_UINT32       (H5OPEN H5T_NATIVE_UINT32_g)
-#define H5T_NATIVE_INT_LEAST32  (H5OPEN H5T_NATIVE_INT_LEAST32_g)
-#define H5T_NATIVE_UINT_LEAST32 (H5OPEN H5T_NATIVE_UINT_LEAST32_g)
-#define H5T_NATIVE_INT_FAST32   (H5OPEN H5T_NATIVE_INT_FAST32_g)
-#define H5T_NATIVE_UINT_FAST32  (H5OPEN H5T_NATIVE_UINT_FAST32_g)
+/**
+ * \ingroup PDTC9x
+ */
+#define H5T_NATIVE_INT32		(H5OPEN H5T_NATIVE_INT32_g)
+/**
+ * \ingroup PDTC9x
+ */
+#define H5T_NATIVE_UINT32		(H5OPEN H5T_NATIVE_UINT32_g)
+/**
+ * \ingroup PDTC9x
+ */
+#define H5T_NATIVE_INT_LEAST32	(H5OPEN H5T_NATIVE_INT_LEAST32_g)
+/**
+ * \ingroup PDTC9x
+ */
+#define H5T_NATIVE_UINT_LEAST32	(H5OPEN H5T_NATIVE_UINT_LEAST32_g)
+/**
+ * \ingroup PDTC9x
+ */
+#define H5T_NATIVE_INT_FAST32	(H5OPEN H5T_NATIVE_INT_FAST32_g)
+/**
+ * \ingroup PDTC9x
+ */
+#define H5T_NATIVE_UINT_FAST32	(H5OPEN H5T_NATIVE_UINT_FAST32_g)
 H5_DLLVAR hid_t H5T_NATIVE_INT32_g;
 H5_DLLVAR hid_t H5T_NATIVE_UINT32_g;
 H5_DLLVAR hid_t H5T_NATIVE_INT_LEAST32_g;
@@ -485,12 +999,30 @@ H5_DLLVAR hid_t H5T_NATIVE_UINT_LEAST32_g;
 H5_DLLVAR hid_t H5T_NATIVE_INT_FAST32_g;
 H5_DLLVAR hid_t H5T_NATIVE_UINT_FAST32_g;
 
-#define H5T_NATIVE_INT64        (H5OPEN H5T_NATIVE_INT64_g)
-#define H5T_NATIVE_UINT64       (H5OPEN H5T_NATIVE_UINT64_g)
-#define H5T_NATIVE_INT_LEAST64  (H5OPEN H5T_NATIVE_INT_LEAST64_g)
+/**
+ * \ingroup PDTC9x
+ */
+#define H5T_NATIVE_INT64		(H5OPEN H5T_NATIVE_INT64_g)
+/**
+ * \ingroup PDTC9x
+ */
+#define H5T_NATIVE_UINT64		(H5OPEN H5T_NATIVE_UINT64_g)
+/**
+ * \ingroup PDTC9x
+ */
+#define H5T_NATIVE_INT_LEAST64	(H5OPEN H5T_NATIVE_INT_LEAST64_g)
+/**
+ * \ingroup PDTC9x
+ */
 #define H5T_NATIVE_UINT_LEAST64 (H5OPEN H5T_NATIVE_UINT_LEAST64_g)
-#define H5T_NATIVE_INT_FAST64   (H5OPEN H5T_NATIVE_INT_FAST64_g)
-#define H5T_NATIVE_UINT_FAST64  (H5OPEN H5T_NATIVE_UINT_FAST64_g)
+/**
+ * \ingroup PDTC9x
+ */
+#define H5T_NATIVE_INT_FAST64	(H5OPEN H5T_NATIVE_INT_FAST64_g)
+/**
+ * \ingroup PDTC9x
+ */
+#define H5T_NATIVE_UINT_FAST64	(H5OPEN H5T_NATIVE_UINT_FAST64_g)
 H5_DLLVAR hid_t H5T_NATIVE_INT64_g;
 H5_DLLVAR hid_t H5T_NATIVE_UINT64_g;
 H5_DLLVAR hid_t H5T_NATIVE_INT_LEAST64_g;
@@ -499,19 +1031,296 @@ H5_DLLVAR hid_t H5T_NATIVE_INT_FAST64_g;
 H5_DLLVAR hid_t H5T_NATIVE_UINT_FAST64_g;
 
 /* Operations defined on all datatypes */
+/**
+ * \ingroup H5T
+ *
+ * \brief Creates a new datatype.
+ *
+ * \param[in] type Class of datatype to create
+ * \param[in] size  Size, in bytes, of the datatype being created
+ *
+ * \return \hid_t{datatype}
+ *
+ * \details H5Tcreate() creates a new datatype of the specified class with the
+ *          specified number of bytes. This function is used only with the
+ *          following datatype classes:
+ *          - #H5T_COMPOUND
+ *          - #H5T_OPAQUE
+ *          - #H5T_ENUM
+ *          - #H5T_STRING
+ *
+ *          Other datatypes, including integer and floating-point datatypes,
+ *          are typically created by using H5Tcopy() to copy and modify a
+ *          predefined datatype.
+ *
+ *          When creating a variable-length string datatype, \p size must
+ *          be #H5T_VARIABLE.
+ *
+ *          When creating a fixed-length string datatype, \p size will
+ *          be the length of the string in bytes. The length of the
+ *          string in characters will depend on i the encoding used; see
+ *          H5Pset_char_encoding().
+ *
+ *          ENUMs created with this function have a signed native integer
+ *          base datatype.  Use H5Tenum_create() if a different integer base
+ *          datatype is required.
+ *
+ *          The datatype identifier returned from this function should be
+ *          released with H5Tclose or resource leaks will result.
+ *
+ * \since 1.2.0
+ *
+ * \see H5Tclose()
+ *
+ * \todo Original has a reference to “Creating variable-length string
+ *       datatypes”.
+ * \todo Create an example for H5Tcreate.
+ *
+ */
 H5_DLL hid_t  H5Tcreate(H5T_class_t type, size_t size);
+/**
+ * \ingroup H5T
+ *
+ * \brief Copies an existing datatype.
+ *
+ * \type_id
+ *
+ * \return \hid_t{datatype}
+ *
+ * \details H5Tcopy() makes a copy of an existing datatype. The returned type
+ *          is always transient and unlocked.
+ *
+ *          The \p type_id argument can be either a datatype identifier,
+ *          a predefined datatype (defined in H5Tpublic.h), or a dataset
+ *          identifier.  If \p type_id is a dataset identifier, this function
+ *          returns a transient, modifiable datatype which is a copy of the
+ *          dataset's datatype.
+ *
+ *          The returned datatype identifier should be released with H5Tclose()
+ *          to prevent resource leak.
+ *
+ * \todo Create an example for H5Tcopy().
+ *
+ */
 H5_DLL hid_t  H5Tcopy(hid_t type_id);
+/**
+ * \ingroup H5T
+ *
+ * \brief Releases a datatype
+ *
+ * \type_id
+ *
+ * \return \herr_t
+ *
+ * \details H5Tclose() releases the datatype \p dtype_id. Further access
+ *          through this datatype identifier is illegal. Failure to release
+ *          a datatype with this call will result in resource leaks.
+ *
+ */
 H5_DLL herr_t H5Tclose(hid_t type_id);
+/**
+ * \ingroup H5T
+ *
+ * \brief Determines whether two datatype identifiers refer to the same datatype
+ *
+ * \type_id{type1_id}
+ * \type_id{type2_id}
+ *
+ * \return \htri_t
+ *
+ * \details H5Tequal() determines whether two datatype identifiers refer to
+ *          the same datatype.
+ *
+ * \since 1.6 or earlier
+ *
+ */
 H5_DLL htri_t H5Tequal(hid_t type1_id, hid_t type2_id);
 H5_DLL herr_t H5Tlock(hid_t type_id);
+/**
+ * \ingroup H5T
+ *
+ * \brief Commits a transient datatype, linking it into the file and creating
+ *        a new committed datatype
+ *
+ * \fg_loc_id
+ * \param[in] name Name given to committed datatype
+ * \type_id Identifier of datatype to be committed and, upon function’s
+ *          return, identifier for the committed datatype
+ * \lcpl_id
+ * \tcpl_id
+ * \tapl_id
+ *
+ * \return \herr_t
+ *
+ * \details H5Tcommit2() saves a transient datatype as an immutable committed
+ *          datatype in a file. The datatype specified by \p dtype_id is
+ *          committed to the file with the name name at the location specified
+ *          by \p loc_id and with the datatype creation and access property
+ *          lists \p tcpl_id and \p tapl_id, respectively.
+ *
+ *          \p loc_id may be a file identifier, or a group identifier within
+ *          that file. \p name may be either an absolute path in the file or
+ *          a relative path from \p loc_id naming the newly-commited datatype.
+ *
+ *          The link creation property list, \p lcpl_id, governs creation of
+ *          the link(s) by which the new committed datatype is accessed and
+ *          the creation of any intermediate groups that may be missing.
+ *
+ *          Once commited, this datatype may be used to define the datatype
+ *          of any other dataset or attribute in the file.
+ *
+ *          This function will not accept a datatype that cannot actually hold
+ *          information. This currently includes compound datatypes with no
+ *          fields and enumerated datatypes with no members.
+ *
+ *          Committed datatypes are sometimes referred to as named datatypes.
+ *
+ * \version 1.8.7 Function modified in this release to reject datatypes that
+ *          will not accomodate actual data, such as a compound datatype
+ *          with no fields or an enumerated datatype with no members.
+ *
+ * \since 1.8.0
+ *
+ */
 H5_DLL herr_t H5Tcommit2(hid_t loc_id, const char *name, hid_t type_id, hid_t lcpl_id, hid_t tcpl_id,
                          hid_t tapl_id);
 H5_DLL hid_t  H5Topen2(hid_t loc_id, const char *name, hid_t tapl_id);
+/**
+ * \ingroup H5T
+ *
+ * \brief Commits a transient datatype to a file, creating a new named
+ *        datatype, but does not link it into the file structure
+ *
+ * \fg_loc_id
+ * \type_id
+ * \tcpl_id
+ * \tapl_id
+ *
+ * \return \herr_t
+ *
+ * \details H5Tcommit_anon() commits a transient datatype (not immutable)
+ *          to a file, turning it into a named datatype with the specified
+ *          creation and property lists. With default property lists,
+ *          #H5P_DEFAULT, H5Tcommit_anon() provides similar functionality to
+ *          that of H5Tcommit(), with the differences described below.
+ *
+ *          #H5P_DEFAULT can be passed in for the datatype creation property
+ *          list identifier, \p tcpl_id.  The datatype access property list
+ *          identifier, \p tapl_id, is provided for future functionality and
+ *          is not used at this time. This parameter should always be passed
+ *          as the value #H5P_DEFAULT.
+ *
+ *          Note that H5Tcommit_anon() does not link this newly-committed
+ *          datatype into the file. After the H5Tcommit_anon() call, the
+ *          datatype identifier \p type_id must be linked into the HDF5 file
+ *          structure with H5Olink() or it will be deleted from the file when
+ *          the file is closed.
+ *
+ *          The differences between this function and H5Tcommit() are as follows:
+ *          \li H5Tcommit_anon() explicitly includes property lists,
+ *              which provides for greater control of the creation process
+ *              and of the properties of the new named datatype. H5Tcommit()
+ *              always uses default properties.
+ *          \li H5Tcommit_anon() neither provides the new named datatype’s
+ *              name nor links it into the HDF5 file structure; those actions
+ *              must be performed separately through a call to H5Olink(),
+ *              which offers greater control over linking.
+ *
+ *          This function will not accept a datatype that cannot actually
+ *          hold data. This currently includes compound datatypes with no
+ *          fields and enumerated datatypes with no members.
+ *
+ * \version 1.8.7 Function modified in this release to reject datatypes that
+ *                will not accomodate actual data, such as a compound datatype
+ *                with no fields or an enumerated datatype with no members.
+ *
+ * \since 1.2.0
+ *
+ */
 H5_DLL herr_t H5Tcommit_anon(hid_t loc_id, hid_t type_id, hid_t tcpl_id, hid_t tapl_id);
+/**
+ * \ingroup H5T
+ *
+ * \brief Returns a copy of a datatype's creation property list
+ *
+ * \type_id
+ *
+ * \return \hid_t{datatype creation property list}
+ *
+ * \details H5Tget_create_plist() returns a property list identifier
+ *          for the datatype creation property list associated with the datatype
+ *          specified by \p type_id.
+ *
+ *          The creation property list identifier should be released with
+ *          H5Pclose() to prevent memory leaks.
+ *
+ * \since 1.8.0
+ *
+ */
 H5_DLL hid_t  H5Tget_create_plist(hid_t type_id);
+/**
+ * \ingroup H5T
+ *
+ * \brief Determines whether a datatype is a committed type or a transient type
+ *
+ * \type_id
+ *
+ * \return \htri_t
+ *
+ * \details H5Tcommitted() queries a type to determine whether the type
+ *          specified by the \p dtype_id identifier is a committed (formerly
+ *          known as a \Emph{named}) type or a transient type. If this function returns
+ *          a positive value, then the type is committed (that is, it has been
+ *          committed, perhaps by some other application). Datasets which
+ *          return committed datatypes with H5Dget_type() are able to share
+ *          the datatype with other datasets in the same file.
+ *
+ * \version 1.8.0 Fortran API was added
+ *
+ * \since 1.6 or earlier
+ *
+ */
 H5_DLL htri_t H5Tcommitted(hid_t type_id);
 H5_DLL herr_t H5Tencode(hid_t obj_id, void *buf, size_t *nalloc);
 H5_DLL hid_t  H5Tdecode(const void *buf);
+/**
+ * \ingroup H5T
+ *
+ * \brief Flushes all buffers associated with a committed datatype to disk
+ *
+ * \type_id
+ *
+ * \return \herr_t
+ *
+ * \details H5Tflush() causes all buffers associated with a committed datatype
+ *          \p type_id to be immediately flushed to disk without removing the
+ *          data from the cache.
+ *
+ *          HDF5 does not possess full control over buffering.  H5Tflush()
+ *          flushes the internal HDF5 buffers and then asks the operating
+ *          system (the OS) to flush the system buffers for the open
+ *          files. After that, the OS is responsible for ensuring that the
+ *          data is actually flushed to disk.
+ *
+ * \return \herr_t
+ *
+ * \since 1.10.0  C function introduced with this release.
+ *
+ * \see     H5Dflush()
+ *          H5Drefresh()
+ *          H5Tflush()
+ *          H5Grefresh()
+ *          H5Oflush()
+ *          H5Orefresh()
+ *          H5Tflush()
+ *          H5Trefresh()
+ *          H5Fstart_swmr_write()
+ *          H5Pget_append_flush()
+ *          H5Pget_object_flush_cb()
+ *          H5Pset_append_flush()
+ *          H5Pset_object_flush_cb()
+ *
+ */
 H5_DLL herr_t H5Tflush(hid_t type_id);
 H5_DLL herr_t H5Trefresh(hid_t type_id);
 
@@ -538,9 +1347,108 @@ H5_DLL herr_t H5Tset_tag(hid_t type, const char *tag);
 H5_DLL char * H5Tget_tag(hid_t type);
 
 /* Querying property values */
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5T
+ *
+ * \brief Returns the base datatype from which a datatype is derived
+ *
+ * \type_id{type}
+ *
+ * \return \hid_t{datatype}
+ *
+ * \details H5Tget_super() returns the base datatype from which the datatype
+ *          \p type_id is derived.  In the case of an enumeration type, the
+ *          return value is an integer type.
+ *
+ *          The datatype identifier returned by this function must be released
+ *          with H5Tclose()  when the identifier is no longer needed so that
+ *          resource leaks will not develop.
+ *
+ */
 H5_DLL hid_t       H5Tget_super(hid_t type);
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5T
+ *
+ * \brief Returns a datatype class
+ *
+ * \type_id
+ *
+ * \return Returns the datatype class if successful; otherwise #H5T_NO_CLASS.
+ *
+ * \details H5Tget_class() returns the class of the datatype \p type_id.
+ *          Valid class identifiers, as defined in H5Tpublic.h, are:
+ *          \snippet this H5T_class_t_snip
+ *
+ * \note The library returns #H5T_STRING for both fixed-length and
+ *       variable-length strings.
+ *
+ * \note Unsupported datatype: The time datatype class, #H5T_TIME,
+ *       is not supported. If #H5T_TIME is used, the resulting data will
+ *       be readable and modifiable only on the originating computing
+ *       platform; it will not be portable to other platforms.
+ *
+ */
 H5_DLL H5T_class_t H5Tget_class(hid_t type_id);
+/**
+ * \ingroup H5T
+ *
+ * \brief Determines whether a datatype contains any datatypes of the given
+ *        datatype class
+ *
+ * \type_id
+ * \param[in] cls Datatype class
+ *
+ * \return \htri_t
+ *
+ * \details H5Tdetect_class() determines whether the datatype specified in
+ *          \p type_id contains any datatypes of the datatype class specified
+ *          in \p dtype_class.
+ *
+ *          This function is useful primarily in recursively examining all the
+ *          fields and/or base types of compound, array, and variable-length
+ *          datatypes.
+ *
+ *          Valid class identifiers, as defined in H5Tpublic.h, are:
+ *          \snippet this H5T_class_t_snip
+ *
+ * \since 1.6.0
+ *
+ */
 H5_DLL htri_t      H5Tdetect_class(hid_t type_id, H5T_class_t cls);
+/**
+ * \ingroup H5T
+ *
+ * \brief Returns the size of a datatype
+ *
+ * \type_id
+ *
+ * \return Returns the size of the datatype in bytes if successful; otherwise,
+ *         returns 0.
+ *
+ * \details H5Tget_size() returns the size of a datatype in bytes.
+ *          \li For atomic datatypes, array datatypes, compound datatypes, and
+ *          other datatypes of a constant size, the returned value is the
+ *          size of the actual datatype in bytes.
+ *          \li For variable-length string datatypes the returned value is
+ *          the size of the pointer to the actual string, or \c sizeof(\c
+ *          char \c *). This function does not return the size of actual
+ *          variable-length string data.
+ *          \li For variable-length sequence datatypes (see H5Tvlen_create()),
+ *          the returned value is the size of the \p hvl_t struct, or \c
+ *          sizeof(\p hvl_t). The \p hvl_t struct contains a pointer to the
+ *          actual data and a size value.  This function does not return the
+ *          size of actual variable-length sequence data.
+ *
+ * \since 1.2.0
+ *
+ * \see H5Tset_size()
+ *
+ * \todo Original has a reference to “Creating variable-length string datatypes”.
+ * \todo Create an example for H5Tget_size().
+ *
+ */
 H5_DLL size_t      H5Tget_size(hid_t type_id);
 H5_DLL H5T_order_t H5Tget_order(hid_t type_id);
 H5_DLL size_t      H5Tget_precision(hid_t type_id);
@@ -562,6 +1470,89 @@ H5_DLL hid_t       H5Tget_member_type(hid_t type_id, unsigned membno);
 H5_DLL herr_t      H5Tget_member_value(hid_t type_id, unsigned membno, void *value /*out*/);
 H5_DLL H5T_cset_t  H5Tget_cset(hid_t type_id);
 H5_DLL htri_t      H5Tis_variable_str(hid_t type_id);
+/**
+ * \ingroup H5T
+ *
+ * \brief Returns the native datatype identifier of a specified datatype
+ *
+ * \type_id
+ * \param[in] direction Direction of search
+ *
+ * \return \hid_t{native datatype}
+ *
+ * \details H5Tget_native_type() returns the equivalent native datatype
+ *          identifier for the datatype specified by \p type_id.
+ *
+ *          H5Tget_native_type() is designed primarily to facilitate use of
+ *          the H5Dread() function, for which users otherwise must undertake a
+ *          multi-step process to determine the native datatype of a dataset
+ *          prior to reading it into memory. This function can be used for
+ *          the following purposes:
+ *
+ *          \li To determine the native datatype of an atomic datatype
+ *          \li To determine the base datatype of an array, enumerated, or
+ *              variable-length datatype
+ *          \li To determine the native atomic datatypes of the individual
+ *              components of a compound datatype
+ *
+ *          For example, if \p type_id is a compound datatype, the returned
+ *          datatype identifier will be for a similar compound datatype with
+ *          each element converted to the corresponding native datatype;
+ *          nested compound datatypes will be unwound. If \p type_id is an
+ *          array, the returned datatype identifier will be for the native
+ *          datatype of a single array element.
+ *
+ *          H5Tget_native_type() selects the first matching native datatype
+ *          from the following list:
+ *
+ *          \li #H5T_NATIVE_CHAR
+ *          \li #H5T_NATIVE_SHORT
+ *          \li #H5T_NATIVE_INT
+ *          \li #H5T_NATIVE_LONG
+ *          \li #H5T_NATIVE_LLONG
+ *
+ *          \li #H5T_NATIVE_UCHAR
+ *          \li #H5T_NATIVE_USHORT
+ *          \li #H5T_NATIVE_UINT
+ *          \li #H5T_NATIVE_ULONG
+ *          \li #H5T_NATIVE_ULLONG
+ *
+ *          \li #H5T_NATIVE_FLOAT
+ *          \li #H5T_NATIVE_DOUBLE
+ *          \li #H5T_NATIVE_LDOUBLE
+ *
+ *          \li #H5T_NATIVE_B8
+ *          \li #H5T_NATIVE_B16
+ *          \li #H5T_NATIVE_B32
+ *          \li #H5T_NATIVE_B64
+ *
+ *          The direction parameter indicates the order in which the library
+ *          searches for a native datatype match. Valid values for direction
+ *          are as follows:
+ *          \snippet this H5T_direction_t_snip
+ *
+ *          H5Tget_native_type() is designed primarily for use with integer,
+ *          floating point, and bitfield datatypes. String, time, opaque, and
+ *          reference datatypes are returned as a copy of dtype_id. See above
+ *          for compound, array, enumerated, and variable-length datatypes.
+ *
+ *          The identifier returned by H5Tget_native_type() should eventually
+ *          be closed by calling H5Tclose() to release resources.
+ *
+ *          \note Please note that a datatype is actually an object
+ *          identifier or handle returned from opening the datatype. It
+ *          is not persistent and its value can be different from one HDF5
+ *          session to the next.
+ *
+ *          \note H5Tequal() can be used to compare datatypes.
+ *
+ *          \note HDF5 High Level APIs that may also be of interest are: H5LTdtype_to_text()
+ *                creates a text description of a datatype. H5LTtext_to_dtype() creates an
+ *                HDF5 datatype given a text description.
+ *
+ * \since 1.6.0
+ *
+ */
 H5_DLL hid_t       H5Tget_native_type(hid_t type_id, H5T_direction_t direction);
 
 /* Setting property values */

From ef87f48134e58fd14a66ed5e8bb33f99a15c675f Mon Sep 17 00:00:00 2001
From: Gerd Heber <gheber@hdfgroup.org>
Date: Tue, 17 Nov 2020 14:05:43 -0600
Subject: [PATCH 09/16] Second installment of Elena's H5T batch.

---
 src/H5Tpublic.h | 716 +++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 713 insertions(+), 3 deletions(-)

diff --git a/src/H5Tpublic.h b/src/H5Tpublic.h
index 07778eadee2..26beef391eb 100644
--- a/src/H5Tpublic.h
+++ b/src/H5Tpublic.h
@@ -50,6 +50,7 @@ typedef enum H5T_class_t {
 /**
  * Byte orders
  */
+//! [H5T_order_t_snip]
 typedef enum H5T_order_t {
     H5T_ORDER_ERROR      = -1,  /**< error                                   */
     H5T_ORDER_LE         = 0,   /**< little endian                           */
@@ -59,10 +60,12 @@ typedef enum H5T_order_t {
     H5T_ORDER_NONE       = 4    /**< no particular order (strings, bits,..)  */
     /*H5T_ORDER_NONE must be last */
 } H5T_order_t;
+//! [H5T_order_t_snip]
 
 /**
  * Types of integer sign schemes
  */
+//! [H5T_sign_t_snip]
 typedef enum H5T_sign_t {
     H5T_SGN_ERROR        = -1,  /**< error                                   */
     H5T_SGN_NONE         = 0,   /**< this is an unsigned type                */
@@ -70,10 +73,12 @@ typedef enum H5T_sign_t {
 
     H5T_NSGN             = 2    /** sentinel: this must be last!             */
 } H5T_sign_t;
+//! [H5T_sign_t_snip]
 
 /**
  * Floating-point normalization schemes
  */
+//! [H5T_norm_t_snip]
 typedef enum H5T_norm_t {
     H5T_NORM_ERROR       = -1,  /**< error                                   */
     H5T_NORM_IMPLIED     = 0,   /**< msb of mantissa isn't stored, always 1  */
@@ -81,6 +86,7 @@ typedef enum H5T_norm_t {
     H5T_NORM_NONE        = 2    /**< not normalized                          */
     /*H5T_NORM_NONE must be last */
 } H5T_norm_t;
+//! [H5T_norm_t_snip]
 
 /**
  * Character set to use for text strings.
@@ -135,14 +141,16 @@ typedef enum H5T_str_t {
 /**
  * Type of padding to use in other atomic types
  */
+//! [H5T_pad_t_snip]
 typedef enum H5T_pad_t {
     H5T_PAD_ERROR        = -1,  /**< error                           */
     H5T_PAD_ZERO         = 0,   /**< always set to zero              */
     H5T_PAD_ONE          = 1,   /**< always set to one               */
     H5T_PAD_BACKGROUND   = 2,   /**< set to background value         */
 
-    H5T_NPAD             = 3    /*THIS MUST BE LAST                          */
+    H5T_NPAD             = 3    /**< sentinal: THIS MUST BE LAST     */
 } H5T_pad_t;
+//! [H5T_pad_t_snip]
 
 /**
  * Commands sent to conversion functions
@@ -1135,6 +1143,22 @@ H5_DLL herr_t H5Tclose(hid_t type_id);
  *
  */
 H5_DLL htri_t H5Tequal(hid_t type1_id, hid_t type2_id);
+/**
+ * \ingroup H5T
+ *
+ * \brief Locks a datatype
+ *
+ * \type_id
+ *
+ * \return \herr_t
+ *
+ * \details H5Tlock() locks the datatype specified by the dtype_id identifier,
+ *          making it read-only and non-destructible. This is normally done by
+ *          the library for predefined datatypes so the application does not
+ *          inadvertently change or delete a predefined type. Once a datatype
+ *          is locked it can never be unlocked.
+ *
+ */
 H5_DLL herr_t H5Tlock(hid_t type_id);
 /**
  * \ingroup H5T
@@ -1184,6 +1208,29 @@ H5_DLL herr_t H5Tlock(hid_t type_id);
  */
 H5_DLL herr_t H5Tcommit2(hid_t loc_id, const char *name, hid_t type_id, hid_t lcpl_id, hid_t tcpl_id,
                          hid_t tapl_id);
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5T
+ *
+ * \brief Opens a committed (named) datatype
+ *
+ * \fgdta_loc_id
+ * \param[in] name Name of the datatype to open
+ * \tapl_id
+ *
+ * \return \hid_t{datatype}
+ *
+ * \details H5Topen2() opens a committed datatype at the location specified
+ *          by \p loc_id and returns an identifier for the datatype. \p
+ *          loc_id is either a file or group identifier. The identifier should
+ *          eventually be closed by calling H5Tclose()  to release resources.
+ *
+ *          The committed datatype is opened with the datatype access property
+ *          list tapl_id.
+ *
+ * \since 1.8.0
+ *
+ */
 H5_DLL hid_t  H5Topen2(hid_t loc_id, const char *name, hid_t tapl_id);
 /**
  * \ingroup H5T
@@ -1281,7 +1328,61 @@ H5_DLL hid_t  H5Tget_create_plist(hid_t type_id);
  *
  */
 H5_DLL htri_t H5Tcommitted(hid_t type_id);
+/**
+ * \ingroup H5T
+ *
+ * \brief Encodes a datatype object description into a binary buffer
+ *
+ * \param[in] obj_id Identifier of the object to be encoded
+ * \param[in,out] buf Buffer for the object to be encoded into.
+ * \param[in,out] nalloc IN: The size of the allocated buffer
+ *                       OUT: The size of the buffer needed
+ *
+ * \return \herr_t
+ *
+ * \details H5Tencode() Given datatype identifier, H5Tencode() converts a
+ *          datatype description into binary form in a buffer. Using this
+ *          binary form in the buffer, a datatype object can be reconstructed
+ *          using H5Tdecode() to return a new object handle (\ref hid_t) for
+ *          this datatype.
+ *
+ *          If the provided buffer is NULL, only the size of buffer needed is
+ *          returned through \p nalloc.
+ *
+ *          A preliminary H5Tencode() call can be made to find out the size
+ *          of the buffer needed. This value is returned as \p nalloc. That
+ *          value can then be assigned to \p nalloc for a second H5Tencode()
+ *          call, which will retrieve the actual encoded object.
+ *
+ *          If the library finds that \p nalloc is not big enough for the
+ *          object, it simply returns the size of the buffer needed through
+ *          \p nalloc without encoding the provided buffer.
+ *
+ * \since 1.2.0
+ *
+ */
 H5_DLL herr_t H5Tencode(hid_t obj_id, void *buf, size_t *nalloc);
+/**
+ * \ingroup H5T
+ *
+ * \brief Decodes a binary object description of datatype and return a new
+ *        object handle
+ *
+ * \param[in] buf Buffer for the datatype object to be decoded
+ *
+ * \return \hid_t{datatype}
+ *
+ * \details H5Tdecode() Given an object description of datatype in binary in a
+ *          buffer, H5Tdecode() reconstructs the HDF5 datatype object and
+ *          returns a new object handle for it. The binary description of
+ *          the object is encoded by H5Tencode(). User is responsible for
+ *          passing in the right buffer.
+ *
+ *          The datatype identifier returned by this function can be released
+ *          with H5Tclose() when the identifier is no longer needed so that
+ *          resource leaks will not develop.
+ *
+ */
 H5_DLL hid_t  H5Tdecode(const void *buf);
 /**
  * \ingroup H5T
@@ -1322,6 +1423,27 @@ H5_DLL hid_t  H5Tdecode(const void *buf);
  *
  */
 H5_DLL herr_t H5Tflush(hid_t type_id);
+/**
+ * \ingroup H5T
+ *
+ * \brief Refreshes all buffers associated with a committed datatype
+ *
+ * \type_id
+ *
+ * \return \herr_t
+ *
+ * \details H5Trefresh() causes all buffers associated with a committed
+ *          datatype to be cleared and immediately re-loaded with updated
+ *          contents from disk.
+ *
+ *          This function essentially closes the datatype, evicts all
+ *          metadata associated with it from the cache, and then re-opens the
+ *          datatype. The reopened datatype is automatically re-registered
+ *          with the same identifier.
+ *
+ * \since 1.2.0
+ *
+ */
 H5_DLL herr_t H5Trefresh(hid_t type_id);
 
 /* Operations defined on compound datatypes */
@@ -1348,7 +1470,6 @@ H5_DLL char * H5Tget_tag(hid_t type);
 
 /* Querying property values */
 /**
- * --------------------------------------------------------------------------
  * \ingroup H5T
  *
  * \brief Returns the base datatype from which a datatype is derived
@@ -1450,16 +1571,215 @@ H5_DLL htri_t      H5Tdetect_class(hid_t type_id, H5T_class_t cls);
  *
  */
 H5_DLL size_t      H5Tget_size(hid_t type_id);
+/**
+ * \ingroup ATOM
+ *
+ * \brief Returns the byte order of an atomic datatype
+ *
+ * \type_id
+ *
+ * \return Returns a byte order constant if successful; otherwise returns
+ *         #H5T_ORDER_ERROR (-1)
+ *
+ * \details H5Tget_order() returns the byte order of an atomic datatype.
+ *          Possible return values are:
+ *          \snippet this H5T_order_t_snip
+ *          Members of a compound datatype need not have the same byte
+ *          order. If members of a compound datatype have more than one of
+ *          little endian, big endian, or VAX byte order, H5Tget_order() will
+ *          return #H5T_ORDER_MIXED for the compound datatype. A byte order of
+ *          #H5T_ORDER_NONE will, however, be ignored; for example, if one or
+ *          more members of a compound datatype have byte order #H5T_ORDER_NONE
+ *          but all other members have byte order #H5T_ORDER_LE,  H5Tget_order()
+ *          will return #H5T_ORDER_LE for the compound datatype.
+ *
+ * \since 1.2.0
+ *
+ */
 H5_DLL H5T_order_t H5Tget_order(hid_t type_id);
+/**
+ * \ingroup ATOM
+ *
+ * \brief Returns the precision of an atomic datatype
+ *
+ * \type_id
+ *
+ * \return Returns the number of significant bits if successful; otherwise 0
+ *
+ * \details H5Tget_precision() returns the precision of an atomic datatype
+ *          (for example, integer or float) or a datatype whose base (parent)
+ *          type is an atomic type (for example, array, enum and variable
+ *          length). The precision is the number of significant bits which,
+ *          unless padding is present, is 8 times larger than the value
+ *          returned by H5Tget_size().
+ *
+ * \since 1.2.0
+ *
+ */
 H5_DLL size_t      H5Tget_precision(hid_t type_id);
+/**
+ * \ingroup ATOM
+ *
+ * \brief Retrieves the bit offset of the first significant bit
+ *
+ * \type_id
+ *
+ * \return Returns an offset value if successful; otherwise returns a
+ *         negative value.
+ *
+ * \details H5Tget_offset() retrieves the bit offset of the first significant
+ *          bit. The significant bits of an atomic datum can be offset from the
+ *          beginning of the memory for that datum by an amount of padding. The
+ *          'offset' property specifies the number of bits of padding that
+ *          appear to the "right of" the value. That is, if we have a 32-bit
+ *          datum with 16-bits of precision having the value 0x1122 then it
+ *          will be laid out in memory as (from small byte address toward
+ *          larger byte addresses):
+ *          \code{.unparsed}
+ *          0:  [ pad]  [0x11]  [0x22]  [ pad]
+ *          1:  [ pad]  [0x22]  [0x11]  [ pad]
+ *          2:  [0x11]  [ pad]  [ pad]  [0x22]
+ *          3:  [0x22]  [ pad]  [ pad]  [0x11]
+ *          \endcode
+ *
+ * \since 1.2.0
+ *
+ */
 H5_DLL int         H5Tget_offset(hid_t type_id);
+/**
+ * \ingroup ATOM
+ *
+ * \brief Retrieves the padding type of the least and most-significant bit padding
+ *
+ * \type_id
+ * \param[out] lsb Buffer for the least-significant bit padding type
+ * \param[out] msb Buffer for the most-significant bit padding type
+ *
+ * \return \herr_t
+ *
+ * \details H5Tget_pad() retrieves the padding type of the least and
+ *          most-significant bit padding. Valid padding types are:
+ *          \snippet this H5T_pad_t_snip
+ *
+ * \since 1.2.0
+ *
+ */
 H5_DLL herr_t      H5Tget_pad(hid_t type_id, H5T_pad_t *lsb /*out*/, H5T_pad_t *msb /*out*/);
-H5_DLL H5T_sign_t  H5Tget_sign(hid_t type_id);
+/**
+ * \ingroup ATOM
+ *
+ * \brief Retrieves the sign type for an integer type
+ *
+ * \type_id
+ *
+ * \return Returns a valid sign type if successful; otherwise #H5T_SGN_ERROR (-1)
+ *
+ * \details H5Tget_sign() retrieves the sign type for an integer type.
+ *          Valid types are:
+ *          \snippet this H5T_sign_t_snip
+ *
+ * \since 1.2.0
+ *
+ */
+H5_DLL H5T_sign_t H5Tget_sign(hid_t type_id);
+/**
+ * \ingroup ATOM
+ *
+ * \brief Retrieves floating point datatype bit field information
+ *
+ * \type_id
+ * \param[out] spos Pointer to location to return floating-point sign bit
+ * \param[out] epos Pointer to location to return exponent bit-position
+ * \param[out] esize Pointer to location to return size of exponent in bits
+ * \param[out] mpos Pointer to location to return mantissa bit-position
+ * \param[out] msize Pointer to location to return size of mantissa in bits
+ *
+ * \return \herr_t
+ *
+ * \details H5Tget_fields() retrieves information about the locations of
+ *          the various bit fields of a floating point datatype. The field
+ *          positions are bit positions in the significant region of the
+ *          datatype. Bits are numbered with the least significant bit number
+ *          zero. Any (or even all) of the arguments can be null pointers.
+ *
+ * \since 1.2.0
+ *
+ */
 H5_DLL herr_t H5Tget_fields(hid_t type_id, size_t *spos /*out*/, size_t *epos /*out*/, size_t *esize /*out*/,
                             size_t *mpos /*out*/, size_t *msize /*out*/);
+/**
+ * \ingroup ATOM
+ *
+ * \brief Retrieves the exponent bias of a floating-point type
+ *
+ * \type_id
+ *
+ * \return Returns the bias if successful and 0, otherwise.
+ *
+ * \details H5Tget_ebias() retrieves the exponent bias of a floating-point type.
+ *
+ * \since 1.2.0
+ *
+ */
 H5_DLL size_t H5Tget_ebias(hid_t type_id);
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup ATOM
+ *
+ * \brief Retrieves mantissa normalization of a floating-point datatype
+ *
+ * \type_id
+ *
+ * \return Returns a valid normalization type if successful; otherwise
+ *         returns #H5T_NORM_ERROR (-1)
+ *
+ * \details H5Tget_norm() retrieves the mantissa normalization of a
+ *          floating-point datatype. Valid normalization types are:
+ *          \snippet this H5T_norm_t_snip
+ *
+ * \since 1.2.0
+ *
+ */
 H5_DLL H5T_norm_t  H5Tget_norm(hid_t type_id);
+/**
+ * \ingroup ATOM
+ *
+ * \brief Retrieves the internal padding type for unused bits in floating-point
+ *        datatypes
+ *
+ * \type_id
+ *
+ * \return Returns a valid padding type if successful; otherwise returns
+ *         #H5T_PAD_ERROR (-1).
+ *
+ * \details H5Tget_inpad() retrieves the internal padding type for unused
+ *          bits in floating-point datatypes. Valid padding types are:
+ *          \snippet this H5T_pad_t_snip
+ *
+ * \since 1.2.0
+ *
+ */
 H5_DLL H5T_pad_t   H5Tget_inpad(hid_t type_id);
+/**
+ * \ingroup ATOM
+ *
+ * \brief Retrieves the type of padding used for a string datatype
+ *
+ * \type_id
+ *
+ * \return Returns a valid string of the padding if successful; otherwise
+ *         returns #H5T_STR_ERROR (-1)
+ *
+ * \details H5Tget_strpad() retrieves the type of padding used for a string
+ *          datatype.
+ *
+ *          The string padding type is set with H5Tset_strpad().  Possible
+ *          values returned are:
+ * \str_pad_type
+ *
+ * \since 1.2.0
+ *
+ */
 H5_DLL H5T_str_t   H5Tget_strpad(hid_t type_id);
 H5_DLL int         H5Tget_nmembers(hid_t type_id);
 H5_DLL char *      H5Tget_member_name(hid_t type_id, unsigned membno);
@@ -1468,7 +1788,46 @@ H5_DLL size_t      H5Tget_member_offset(hid_t type_id, unsigned membno);
 H5_DLL H5T_class_t H5Tget_member_class(hid_t type_id, unsigned membno);
 H5_DLL hid_t       H5Tget_member_type(hid_t type_id, unsigned membno);
 H5_DLL herr_t      H5Tget_member_value(hid_t type_id, unsigned membno, void *value /*out*/);
+/**
+ * \ingroup ATOM
+ *
+ * \brief Retrieves the character set type of a string datatype
+ *
+ * \type_id
+ *
+ * \return Returns a valid character set type if successful; otherwise
+ *         #H5T_CSET_ERROR (-1).
+ *
+ * \details H5Tget_cset() retrieves the character set type of a string datatype.
+ *          Valid character set types are:
+ *          \csets
+ *
+ * \since 1.2.0
+ *
+ */
 H5_DLL H5T_cset_t  H5Tget_cset(hid_t type_id);
+/**
+ * \ingroup ATOM
+ *
+ * \brief Determines whether datatype is a variable-length string
+ *
+ * \type_id
+ *
+ * \return Returns:
+ *         \li a positive value if the specified datatype is a variable-length
+ *             string
+ *         \li 0 if the specified datatype is not a variable-length string
+ *         \li a negative value when the function fails
+ *
+ * \details H5Tis_variable_str() determines whether the datatype identified
+ *          by \p dtype_id is a variable-length string.
+ *
+ *          This function can be used to distinguish between fixed and
+ *          variable-length string datatypes.
+ *
+ * \since 1.6.0
+ *
+ */
 H5_DLL htri_t      H5Tis_variable_str(hid_t type_id);
 /**
  * \ingroup H5T
@@ -1556,24 +1915,375 @@ H5_DLL htri_t      H5Tis_variable_str(hid_t type_id);
 H5_DLL hid_t       H5Tget_native_type(hid_t type_id, H5T_direction_t direction);
 
 /* Setting property values */
+/**
+ * \ingroup H5T
+ *
+ * \brief Sets size for a datatype.
+ *
+ * \type_id
+ * \param[in] size New datatype size is bytes or #H5T_VARIABLE
+ *
+ * \return \herr_t
+ *
+ * \details H5Tset_size() sets the total size, \p size, in bytes, for a
+ *          datatype.
+ *
+ *          \p size must have a positive value, unless it is passed in as
+ *          #H5T_VARIABLE and the datatype is a string datatype.
+ *
+ *          \li Numeric datatypes: If the datatype is atomic and the size
+ *          is decreased so that significant bits of the datatype extend
+ *          beyond the edge of the new size, then the offset property of the
+ *          datatype is decreased toward zero.  If the offset becomes zero
+ *          and the significant bits of the datatype still hang over the edge
+ *          of the new size, then the number of significant bits is decreased.
+ *
+ *          \li String or character datatypes: The size set for a string
+ *          datatype should include space for the null-terminator character,
+ *          otherwise it will not be stored on (or retrieved from)
+ *          disk. Adjusting the size of a string automatically sets the
+ *          precision to \p 8*size.
+ *
+ *          \li Variable-length string datatypes: If \p dtype_id is a
+ *          variable-length string, size must normally be set to #H5T_VARIABLE.
+ *
+ *          \li Compound datatypes: This function may be used to increase or
+ *          decrease the size of a compound datatype, but the function will
+ *          fail if the new size is too small to accommodate all member fields.
+ *
+ *          \li Ineligible datatypes: This function cannot be used with
+ *          enumerated datatypes (#H5T_ENUM), array datatypes (#H5T_ARRAY),
+ *          variable-length array datatypes (#H5T_VLEN), or reference datatypes
+ *          (#H5T_REFERENCE).
+ *
+ * \since 1.2.0
+ *
+ * \see H5Tget_size()
+ *
+ *\todo Create an example for H5Tset_size().
+ *\todo Original has a reference to “Creating variable-length string datatypes”.
+ *
+ */
 H5_DLL herr_t H5Tset_size(hid_t type_id, size_t size);
 H5_DLL herr_t H5Tset_order(hid_t type_id, H5T_order_t order);
 H5_DLL herr_t H5Tset_precision(hid_t type_id, size_t prec);
+/**
+ * \ingroup ATOM
+ *
+ * \brief Sets the bit offset of the first significant bit
+ *
+ * \type_id
+ * \param[in] offset Offset of first significant bit
+ *
+ * \return \herr_t
+ *
+ * \details H5Tset_offset() sets the bit offset of the first significant
+ *          bit. The significant bits of an atomic datum can be offset from
+ *          the beginning of the memory for that datum by an amount of
+ *          padding. The offset property specifies the number of bits of
+ *          padding that appear “to the right of” the value. That is,
+ *          if we have a 32-bit datum with 16-bits of precision having the
+ *          value 0x1122, then it will be laid out in memory as (from small
+ *          byte address toward larger byte addresses):
+ *          \code{.unparsed}
+ *          0:  [ pad]  [0x11]  [0x22]  [ pad]
+ *          1:  [ pad]  [0x22]  [0x11]  [ pad]
+ *          2:  [0x11]  [ pad]  [ pad]  [0x22]
+ *          3:  [0x22]  [ pad]  [ pad]  [0x11]
+ *          \endcode
+ *          If the offset is incremented then the total size is incremented
+ *          also if necessary to prevent significant bits of the value from
+ *          hanging over the edge of the datatype.
+ *
+ *          The offset of an #H5T_STRING cannot be set to anything but zero.
+ *
+ * \since 1.2.0
+ *
+ */
 H5_DLL herr_t H5Tset_offset(hid_t type_id, size_t offset);
 H5_DLL herr_t H5Tset_pad(hid_t type_id, H5T_pad_t lsb, H5T_pad_t msb);
 H5_DLL herr_t H5Tset_sign(hid_t type_id, H5T_sign_t sign);
+/**
+ * \ingroup ATOM
+ *
+ * \brief Sets locations and sizes of floating point bit fields
+ *
+ * \type_id
+ * \param[in] spos Sign position, i.e., the bit offset of the floating-point
+ *                 sign bit
+ * \param[in] epos Exponent bit position
+ * \param[in] esize Size of exponent in bits
+ * \param[in] mpos Mantissa bit position
+ * \param[in] msize Size of mantissa in bits
+ *
+ * \return \herr_t
+ *
+ * \details H5Tset_fields() sets the locations and sizes of the various
+ *          floating-point bit fields. The field positions are bit positions
+ *          in the significant region of the datatype. Bits are numbered with
+ *          the least significant bit number zero.
+ *
+ *          Fields are not allowed to extend beyond the number of bits of
+ *          precision, nor are they allowed to overlap with one another.
+ *
+ * \since 1.2.0
+ *
+ */
 H5_DLL herr_t H5Tset_fields(hid_t type_id, size_t spos, size_t epos, size_t esize, size_t mpos, size_t msize);
+/**
+ * \ingroup ATOM
+ *
+ * \brief Sets the exponent bias of a floating-point type
+ *
+ * \type_id
+ * \param[in] ebias Exponent bias value
+ *
+ * \return \herr_t
+ *
+ * \details H5Tset_ebias() sets the exponent bias of a floating-point type.
+ *
+ * \since 1.2.0
+ *
+ */
 H5_DLL herr_t H5Tset_ebias(hid_t type_id, size_t ebias);
+/**
+ * \ingroup ATOM
+ *
+ * \brief Sets the mantissa normalization of a floating-point datatype
+ *
+ * \type_id
+ * \param[in] norm Mantissa normalization type
+ *
+ * \return \herr_t
+ *
+ * \details H5Tset_norm() sets the mantissa normalization of a floating-point
+ *          datatype. Valid normalization types are:
+ *          \snippet this H5T_norm_t_snip
+ *
+ * \since 1.2.0
+ *
+ */
 H5_DLL herr_t H5Tset_norm(hid_t type_id, H5T_norm_t norm);
+/**
+ * \ingroup ATOM
+ *
+ * \brief Fills unused internal floating-point bits
+ *
+ * \type_id
+ * \param[in] pad Padding type
+ *
+ * \return \herr_t
+ *
+ * \details H5Tset_inpad() If any internal bits of a floating point-type are
+ *          unused (that is, those significant bits which are not part of the
+ *          sign, exponent, or mantissa), then H5Tset_inpad()  will be filled
+ *          according to the value of the padding value property inpad. Valid
+ *          padding types are:
+ *          \snippet this H5T_pad_t_snip
+ *
+ * \since 1.2.0
+ *
+ */
 H5_DLL herr_t H5Tset_inpad(hid_t type_id, H5T_pad_t pad);
+/**
+ * \ingroup ATOM
+ *
+ * \brief Sets character set to be used in a string or character datatype
+ *
+ * \type_id
+ * \param[in] cset Character set type
+ *
+ * \return \herr_t
+ *
+ * \details H5Tset_cset() sets the character set to be used in a dataset with
+ *          a string or character datatype.
+ *
+ *          Valid values for cset include the following:
+ *          \csets
+ *          For example, if the character set for the datatype \p type_id is set
+ *          to #H5T_CSET_UTF8, string or character data of datatype dtype_id
+ *          will be encoded using the UTF-8 Unicode character set.
+ *
+ *          ASCII and UTF-8 Unicode are the only currently supported character
+ *          encodings. Extended ASCII encodings (for example, ISO 8859) are
+ *          not supported. This encoding policy is not enforced by the HDF5
+ *          library. Using encodings other than ASCII and UTF-8 can lead to
+ *          compatibility and usability problems.
+ *
+ *          Note that H5Tset_cset()  sets the character set for a character or
+ *          string datatype while H5Pset_char_encoding()  sets the character
+ *          set used for an HDF5 link or attribute name.
+ *
+ * \since 1.2.0
+ *
+ */
 H5_DLL herr_t H5Tset_cset(hid_t type_id, H5T_cset_t cset);
 H5_DLL herr_t H5Tset_strpad(hid_t type_id, H5T_str_t strpad);
 
 /* Type conversion database */
+/**
+ * \ingroup CONV
+ *
+ * \brief Registers a datatype conversion function
+ *
+ * \param[in] pers Conversion function type
+ * \param[in] name Name displayed in diagnostic output
+ * \type_id{src_id} of source datatype
+ * \type_id{dst_id} of destination datatype
+ * \param[in] func Function to convert between source and destination datatypes
+ *
+ * \return \herr_t
+ *
+ * \details H5Tregister() registers a hard or soft conversion function for a
+ *          datatype conversion path. The parameter \p pers indicates whether a
+ *          conversion function is hard (#H5T_PERS_HARD) or soft
+ *          (#H5T_PERS_SOFT). User-defined functions employing compiler casting
+ *          are designated as \Emph{hard}; other user-defined conversion
+ *          functions registered with the HDF5 library (with H5Tregister() )
+ *          are designated as \Emph{soft}. The HDF5 library also has its own
+ *          hard and soft conversion functions.
+ *
+ *          A conversion path can have only one hard function. When type is
+ *          #H5T_PERS_HARD, \p func replaces any previous hard function.
+ *
+ *          When type is #H5T_PERS_SOFT, H5Tregister() adds the function to the
+ *          end of the master soft list and replaces the soft function in all
+ *          applicable existing conversion paths. Soft functions are used when
+ *          determining which conversion function is appropriate for this path.
+ *
+ *          The \p name is used only for debugging and should be a short
+ *          identifier for the function.
+ *
+ *          The path is specified by the source and destination datatypes \p
+ *          src_id and \p dst_id. For soft conversion functions, only the class
+ *          of these types is important.
+ *
+ *          The type of the conversion function pointer is declared as:
+ *          \snippet this H5T_conv_t_snip
+ *
+ *          The \ref H5T_cdata_t \c struct is declared as:
+ *          \snippet this H5T_cdata_t_snip
+ *
+ * \since 1.6.3 The following change occurred in the \ref H5T_conv_t function:
+ *              the \c nelmts parameter type changed to size_t.
+ *
+ */
 H5_DLL herr_t H5Tregister(H5T_pers_t pers, const char *name, hid_t src_id, hid_t dst_id, H5T_conv_t func);
+/**
+ * \ingroup CONV
+ *
+ * \brief Removes a conversion function
+ *
+ * \param[in] pers Conversion function type
+ * \param[in] name Name displayed in diagnostic output
+ * \type_id{src_id} of source datatype
+ * \type_id{dst_id} of destination datatype
+ * \param[in] func Function to convert between source and destination datatypes
+ *
+ * \return \herr_t
+ *
+ * \details H5Tunregister() removes a conversion function matching criteria
+ *          such as soft or hard conversion, source and destination types, and
+ *          the conversion function.
+ *
+ *          If a user is trying to remove a conversion function he registered,
+ *          all parameters can be used. If he is trying to remove a library’s
+ *          default conversion function, there is no guarantee the \p name and
+ *          \p func parameters will match the user’s chosen values. Passing in
+ *          some values may cause this function to fail. A good practice is to
+ *          pass in NULL as their values.
+ *
+ *          All parameters are optional. The missing parameters will be used to
+ *          generalize the search criteria.
+ *
+ *          The conversion function pointer type declaration is described in
+ *          H5Tregister().
+ *
+ * \version 1.6.3 The following change occurred in the \ref H5T_conv_t function:
+ *                the \c nelmts parameter type changed to size_t.
+ *
+ */
 H5_DLL herr_t H5Tunregister(H5T_pers_t pers, const char *name, hid_t src_id, hid_t dst_id, H5T_conv_t func);
+/**
+ * \ingroup CONV
+ *
+ * \brief Finds a conversion function
+ *
+ * \type_id{src_id} of source datatype
+ * \type_id{dst_id} of destination datatype
+ * \param[out] pcdata Pointer to type conversion data
+ *
+ * \return Returns a pointer to a suitable conversion function if successful.
+ *         Otherwise returns NULL.
+ *
+ * \details H5Tfind() finds a conversion function that can handle a conversion
+ *          from type \p src_id to type \p dst_id. The \p pcdata argument is a
+ *          pointer to a pointer to type conversion data which was created and
+ *          initialized by the soft type conversion function of this path when
+ *          the conversion function was installed on the path.
+ *
+ */
 H5_DLL H5T_conv_t H5Tfind(hid_t src_id, hid_t dst_id, H5T_cdata_t **pcdata);
+/**
+ * \ingroup CONV
+ *
+ * \brief Check whether the library’s default conversion is hard conversion
+ *
+ * \type_id{src_id} of source datatype
+ * \type_id{dst_id} of destination datatype
+ *
+ * \return \htri_t
+ *
+ * \details H5Tcompiler_conv() determines whether the library’s conversion
+ *          function from type \p src_id to type \p dst_id is a compiler (hard)
+ *          conversion or not. A compiler conversion uses compiler’s casting; a
+ *          library (soft) conversion uses the library’s own conversion
+ *          function.
+ *
+ * \since 1.8.0
+ *
+ */
 H5_DLL htri_t     H5Tcompiler_conv(hid_t src_id, hid_t dst_id);
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup CONV
+ *
+ * \brief Converts data from one specified datatype to another
+ *
+ * \type_id{src_id} of source datatype
+ * \type_id{dst_id} of destination datatype
+ * \param[in] nelmts Size of array \p buf
+ * \param[in,out] buf Array containing pre- and post-conversion values
+ * \param[in] background Optional background buffer
+ * \dxpl_id{plist_id}
+ *
+ * \return \herr_t
+ *
+ * \details H5Tconvert() converts \p nelmts elements from a source datatype,
+ *          specified by \p src_id, to a destination datatype, \p dst_id. The
+ *          source elements are packed in \p buf and on return the destination
+ *          elements will be packed in \p buf. That is, the conversion is
+ *          performed in place.
+ *
+ *          The optional background buffer is for use with compound datatypes.
+ *          It is an array of \p nelmts values for the destination datatype
+ *          which can then be merged with the converted values to recreate the
+ *          compound datatype. For instance, background might be an array of
+ *          structs with the \c a and \c b fields already initialized and the
+ *          conversion of buf supplies the \c c and \c d field values.
+ *
+ *          The parameter \p plist_id contains the dataset transfer property list
+ *          identifier which is passed to the conversion functions. As of
+ *          Release 1.2, this parameter is only used to pass along the
+ *          variable-length datatype custom allocation information.
+ *
+ * \note H5Tconvert() will not resize the buffer \p buf; it must be large
+ *       enough to hold the larger of the input and output data.
+ *
+ * \version 1.6.3 \p nelmts parameter type changed to size_t.
+ * \version 1.4.0 \p nelmts parameter type changed to \ref hsize_t.
+ *
+ */
 H5_DLL herr_t     H5Tconvert(hid_t src_id, hid_t dst_id, size_t nelmts, void *buf, void *background,
                              hid_t plist_id);
 H5_DLL herr_t     H5Treclaim(hid_t type_id, hid_t space_id, hid_t plist_id, void *buf);

From 48a717579666f9fd12d00fea5da57fa2b2722d1f Mon Sep 17 00:00:00 2001
From: Gerd Heber <gheber@hdfgroup.org>
Date: Tue, 17 Nov 2020 16:44:25 -0600
Subject: [PATCH 10/16] Final installment of Elena's H5T batch.

---
 src/H5Tpublic.h | 715 +++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 714 insertions(+), 1 deletion(-)

diff --git a/src/H5Tpublic.h b/src/H5Tpublic.h
index 26beef391eb..8bebb988b4c 100644
--- a/src/H5Tpublic.h
+++ b/src/H5Tpublic.h
@@ -1447,25 +1447,304 @@ H5_DLL herr_t H5Tflush(hid_t type_id);
 H5_DLL herr_t H5Trefresh(hid_t type_id);
 
 /* Operations defined on compound datatypes */
+/**
+ * \ingroup COMPOUND
+ *
+ * \brief Adds a new member to a compound datatype.
+ *
+ * \type_id{parent_id}
+ * \param[in] name      Name of the field to insert
+ * \param[in] offset    Offset in memory structure of the field to insert
+ * \param[in] member_id  Datatype identifier of the field to insert
+ *
+ * \return \herr_t
+ *
+ * \details H5Tinsert() adds another member to the compound datatype, specified
+ *          \p type_id.
+ *
+ *          The new member has a \p name which must be unique within the
+ *          compound datatype. The \p offset argument defines the start of the
+ *          member in an instance of the compound datatype, and \p member_id
+ *          is the datatype identifier of the new member.
+ *
+ *          \note Members of a compound datatype do not have to be atomic
+ *          datatypes; a compound datatype can have a member which is a
+ *          compound datatype.
+ *
+ * \since 1.2.0
+ *
+ * \todo Create example for  H5Tinsert
+ *
+ */
 H5_DLL herr_t H5Tinsert(hid_t parent_id, const char *name, size_t offset, hid_t member_id);
+/**
+ * \ingroup COMPOUND
+ *
+ * \brief Recursively removes padding from within a compound datatype
+ *
+ * \type_id
+ *
+ * \return \herr_t
+ *
+ * \details H5Tpack() recursively removes padding from within a compound
+ *          datatype to make it more efficient (space-wise) to store that data.
+ *
+ * \since 1.2.0
+ *
+ */
 H5_DLL herr_t H5Tpack(hid_t type_id);
 
 /* Operations defined on enumeration datatypes */
+/**
+ * \ingroup ENUM
+ *
+ * \brief Creates a new enumeration datatype
+ *
+ * \param[in] base_id Datatype identifier for the base datatype.  Must be an
+ *            integer datatype
+ *
+ * \return \hid_t{enumeration datatype}
+ *
+ * \details H5Tenum_create() creates a new enumeration datatype based on the
+ *          specified base datatype, dtype_id, which must be an integer datatype.
+ *
+ *          If a particular architecture datatype is required, a little endian
+ *          or big endian datatype for example, use a native datatype as the
+ *          base datatype and use H5Tconvert()  on values as they are read
+ *          from or written to a dataset.
+ *
+ * \since 1.2.0
+ *
+ */
 H5_DLL hid_t  H5Tenum_create(hid_t base_id);
+/**
+ * \ingroup ENUM
+ *
+ * \brief Inserts a new enumeration datatype member
+ *
+ * \type_id{type}
+ * \param[in] name  Name of the new member
+ * \param[in] value Pointer to the value of the new member
+ *
+ * \return \herr_t
+ *
+ * \details H5Tenum_insert() inserts a new enumeration datatype member into an
+ *          enumeration datatype.
+ *
+ *          \p type_id is the datatype identifier for the enumeration datatype,
+ *          \p name is the name of the new member, and \p value points to the
+ *           value of the new member.
+ *
+ *          \p name and \p value must both be unique within \p dtype_id.
+ *
+ *          \p value points to data which must be of the integer base datatype
+ *          used when the enumeration datatype was created. If a particular
+ *          architecture datatype is required, a little endian or big endian
+ *          datatype for example, use a native datatype as the base datatype
+ *          and use H5Tconvert() on values as they are read from or written
+ *          to a dataset.
+ *
+ * \since 1.2.0
+ *
+ */
 H5_DLL herr_t H5Tenum_insert(hid_t type, const char *name, const void *value);
+/**
+ * \ingroup ENUM
+ *
+ * \brief Returns the symbol name corresponding to a specified member of an
+ *        enumeration datatype
+ *
+ * \type_id{type}
+ * \param[in] value Value of the enumeration datatype
+ * \param[out] name Buffer for output of the symbol name
+ * \param[in] size Anticipated size of the symbol name, in bytes
+ *
+ * \return Returns a non-negative value if successful. Otherwise returns a
+ *         negative value
+ *
+ * \details H5Tenum_nameof() finds the symbol name that corresponds to the
+ *          specified \p value of the enumeration datatype \p type.
+ *
+ *          At most \p size characters of the symbol \p name are copied into
+ *          the \p name buffer. If the entire symbol name and null terminator
+ *          do not fit in the name buffer, then as many characters as possible
+ *          are copied (not null terminated) and the function fails.
+ *
+ * \since 1.2.0
+ *
+ */
 H5_DLL herr_t H5Tenum_nameof(hid_t type, const void *value, char *name /*out*/, size_t size);
+/**
+ * \ingroup ENUM
+ *
+ * \brief Returns the value corresponding to a specified member of an
+ *        enumeration datatype
+ *
+ * \type_id{type}
+ * \param[in] name Symbol name of the enumeration datatype
+ * \param[out] value Buffer for the value of the enumeration datatype
+ *
+ * \return \herr_t
+ *
+ * \details H5Tenum_valueof() finds the value that corresponds to the
+ *          specified name of the enumeration datatype \p dtype_id.
+ *
+ *          Values returned in \p value will be of the enumerated type’s
+ *          base type, that is, the datatype used by H5Tenum_create() when
+ *          the enumerated type was created.
+ *
+ *          The \p value buffer must be at least large enough to hold a value
+ *          of that base type. If the size is unknown, you can determine it
+ *          with H5Tget_size().
+ *
+ * \since 1.2.0
+ *
+ */
 H5_DLL herr_t H5Tenum_valueof(hid_t type, const char *name, void *value /*out*/);
 
 /* Operations defined on variable-length datatypes */
+/**
+ * \ingroup VLEN
+ *
+ * \brief Creates a new variable-length array datatype
+ *
+ * \type_id{base_id}, the element type of the datatype to create
+ *
+ * \return \hid_t{variable-length datatype}
+ *
+ * \details H5Tvlen_create() creates a new one-dimensional array datatype of
+ *          variable-length (VL) with the base datatype \p base_id.
+ *
+ *          This one-dimensional array often represents a data sequence of the
+ *          base datatype, such as characters for character sequences or vertex
+ *          coordinates for polygon lists. The base type specified for the VL
+ *          datatype can be any HDF5 datatype, including another VL datatype, a
+ *          compound datatype, or an atomic datatype.
+ *
+ *          When necessary, use H5Tget_super() to determine the base type of
+ *          the VL datatype.
+ *
+ *          The datatype identifier returned from this function should be
+ *          released with H5Tclose() or resource leaks will result. Under
+ *          certain circumstances, H5Dvlen_reclaim() must also be used.
+ *
+ * \attention H5Tvlen_create() cannot be used to create a variable-length
+ *            string datatype. H5Tvlen_create() called with a string or
+ *            character base type creates a variable-length sequence of strings
+ *            (a variable-length, 1-dimensional array), with each element of
+ *            the array being of the string or character base type.\n
+ *            To create a variable-length string datatype, see "Creating
+ *            variable-length string datatypes."
+ *
+ * \todo Fix the reference.
+ *
+ */
 H5_DLL hid_t H5Tvlen_create(hid_t base_id);
 
 /* Operations defined on array datatypes */
+/**
+ * \ingroup ARRAY
+ *
+ * \brief Creates an array datatype object
+ *
+ * \param[in] base_id Datatype identifier for the array base datatype
+ * \param[in] ndims Rank of the array
+ * \param[in] dim Size of each array dimension
+ *
+ * \return \hid_t{array datatype}
+ *
+ * \details H5Tarray_create2() creates a new array datatype object.\n\n
+ *          \p base_id is the datatype of every element of the array, i.e.,
+ *          of the number at each position in the array.
+ *
+ *          \p ndims is the number of dimensions and the size of each dimension
+ *          is specified in the array \p dim. The value of \p rank is
+ *          currently limited to #H5S_MAX_RANK and must be greater than 0
+ *          (zero). All dimension sizes specified in \p dim must be greater
+ *          than 0 (zero).
+ *
+ * \since 1.8.0
+ *
+ */
 H5_DLL hid_t H5Tarray_create2(hid_t base_id, unsigned ndims, const hsize_t dim[/* ndims */]);
+/**
+ * \ingroup ARRAY
+ *
+ * \brief Returns the rank of an array datatype
+ *
+ * \type_id
+ *
+ * \return Returns the rank of the array if successful; otherwise returns a
+ *         negative value.
+ *
+ * \details H5Tget_array_ndims() returns the rank, i.e., the number of
+ *          dimensions, of an array datatype object.
+ *
+ * \since 1.2.0
+ *
+ */
 H5_DLL int   H5Tget_array_ndims(hid_t type_id);
+/**
+ * \ingroup ARRAY
+ *
+ * \brief Retrieves sizes of array dimensions
+ *
+ * \type_id
+ * \param[out] dims Sizes of array dimensions
+ *
+ * \return Returns the non-negative number of dimensions of the array type
+ *         if successful; otherwise returns a negative value.
+ *
+ * \details H5Tget_array_dims2() returns the sizes of the dimensions of the
+ *          specified array datatype object in the array \p dims.
+ *
+ * \since 1.2.0
+ *
+ */
 H5_DLL int   H5Tget_array_dims2(hid_t type_id, hsize_t dims[]);
 
 /* Operations defined on opaque datatypes */
+/**
+ * \ingroup OPAQUE
+ *
+ * \brief Tags an opaque datatype
+ *
+ * \type_id{type} of an opaque datatype
+ * \param[in] tag Descriptive ASCII string with which the opaque datatype is
+ *                to be tagged
+ *
+ * \return \herr_t
+ *
+ * \details H5Tset_tag() tags an opaque datatype \p type with a descriptive
+ *          ASCII identifier, \p tag.
+ *
+ *          \p tag is intended to provide a concise description; the maximum
+ *          size is hard-coded in the HDF5 library as 256 bytes
+ *          (#H5T_OPAQUE_TAG_MAX).
+ *
+ * \version 1.6.5 The #H5T_OPAQUE_TAG_MAX macro constant, specifying the
+ *                maximum size of an opaque datatype tag, was added in
+ *                H5Tpublic.h.
+ *
+ */
 H5_DLL herr_t H5Tset_tag(hid_t type, const char *tag);
+/**
+ * \ingroup OPAQUE
+ *
+ * \brief Gets the tag associated with an opaque datatype
+ *
+ * \type_id{type} of an opaque datatype
+ *
+ * \return Returns a pointer to an allocated string if successful; otherwise
+ *         returns NULL.
+ *
+ * \details H5Tget_tag() returns the tag associated with the opaque datatype
+ *         \p type.
+ *
+ * \attention The tag is returned via a pointer to an allocated string, which
+ *            the caller must free.
+ *
+ */
 H5_DLL char * H5Tget_tag(hid_t type);
 
 /* Querying property values */
@@ -1489,7 +1768,6 @@ H5_DLL char * H5Tget_tag(hid_t type);
  */
 H5_DLL hid_t       H5Tget_super(hid_t type);
 /**
- * --------------------------------------------------------------------------
  * \ingroup H5T
  *
  * \brief Returns a datatype class
@@ -1781,12 +2059,164 @@ H5_DLL H5T_pad_t   H5Tget_inpad(hid_t type_id);
  *
  */
 H5_DLL H5T_str_t   H5Tget_strpad(hid_t type_id);
+/**
+ * \ingroup COMPOUND
+ *
+ * \brief Retrieves the number of elements in a compound or enumeration datatype
+ *
+ * \type_id
+ *
+ * \return Returns the number of elements if successful; otherwise returns a
+ *         negative value.
+ *
+ * \details H5Tget_nmembers() retrieves the number of fields in a compound
+ *          datatype or the number of members of an enumeration datatype.
+ *
+ * \since 1.2.0
+ *
+ */
 H5_DLL int         H5Tget_nmembers(hid_t type_id);
+/**
+ * \ingroup COMPOUND
+ *
+ * \brief Retrieves the name of a compound or enumeration datatype member
+ *
+ * \type_id
+ * \param[in] membno Zero-based index of the field or element
+ *
+ * \return Returns a valid pointer to a string allocated with malloc() if
+ *         successful; otherwise returns NULL.
+ *
+ * \details H5Tget_member_name() retrieves the name of a field of a compound
+ *          datatype or an element of an enumeration datatype.
+ *
+ *          The index of the target field or element is specified in \p
+ *          member_no. Compound datatype fields and enumeration datatype
+ *          elements are stored in no particular order with index values of
+ *          0 through N-1, where N is the value returned by H5Tget_nmembers().
+ *
+ *          The HDF5 library allocates a buffer to receive the name of
+ *          the field. The caller must subsequently free the buffer with
+ *          H5free_memory().
+ *
+ * \since 1.2.0
+ *
+ */
 H5_DLL char *      H5Tget_member_name(hid_t type_id, unsigned membno);
+/**
+ * \ingroup COMPOUND
+ *
+ * \brief Retrieves the index of a compound or enumeration datatype member
+ *
+ * \type_id
+ * \param[in] name Name of the field or member
+ *
+ * \return \herr_t
+ *
+ * \details H5Tget_member_index() retrieves the index of a field of a compound
+ *          datatype or an element of an enumeration datatype.
+ *
+ *          The name of the target field or element is specified by \p name.
+ *
+ *          Fields are stored in no particular order with index values of 0
+ *          through N-1, where N is the value returned by H5Tget_nmembers() .
+ *
+ * \since 1.2.0
+ *
+ */
 H5_DLL int         H5Tget_member_index(hid_t type_id, const char *name);
+/**
+ * \ingroup COMPOUND
+ *
+ * \brief Retrieves the offset of a field of a compound datatype
+ *
+ * \type_id
+ * \param[in] membno Zero-based index of the field or element
+ *
+ * \return Returns the byte offset of the field if successful; otherwise
+ *         returns 0 (zero).
+ *
+ * \details H5Tget_member_offset() retrieves the byte offset of the beginning
+ *          of a field within a compound datatype with respect to the beginning
+ *          of the compound datatype datum.
+ *
+ *          Note that zero is a valid offset and that this function will fail
+ *          only if a call to H5Tget_member_class() fails with the same arguments.
+ *
+ * \version 1.6.4 \p member_no parameter type changed to unsigned.
+ *
+ * \since 1.2.0
+ *
+ */
 H5_DLL size_t      H5Tget_member_offset(hid_t type_id, unsigned membno);
+/**
+ * \ingroup COMPOUND
+ *
+ * \brief Returns datatype class of compound datatype member
+ *
+ * \type_id
+ * \param[in] membno Zero-based index of the field or element
+ *
+ * \return Returns the datatype class, a non-negative value, if successful;
+ *         otherwise returns a negative value.
+ *
+ * \details Given a compound datatype, \p dtype_id, H5Tget_member_class()
+ *          returns the datatype class of the member specified by \p member_no.
+ *
+ *          Valid class identifiers, as defined in H5Tpublic.h, are:
+ *          \snippet this H5T_class_t_snip
+ *
+ * \since 1.2.0
+ *
+ */
 H5_DLL H5T_class_t H5Tget_member_class(hid_t type_id, unsigned membno);
+/**
+ * \ingroup COMPOUND
+ *
+ * \brief Returns the datatype of the specified member
+ *
+ * \type_id
+ * \param[in] membno Zero-based index of the field or element
+ *
+ * \return Returns the identifier of a copy of the datatype of the field if
+ *         successful; otherwise returns a negative value.
+ *
+ * \details H5Tget_member_type() returns the datatype of the specified member.
+ *          The caller should invoke H5Tclose() to release resources associated
+ *          with the type.
+ *
+ * \version 1.6.4 \p membno parameter type changed to unsigned.
+ *
+ * \since 1.2.0
+ *
+ */
 H5_DLL hid_t       H5Tget_member_type(hid_t type_id, unsigned membno);
+/**
+ * \ingroup ENUM
+ *
+ * \brief Returns the value of an enumeration datatype member
+ *
+ * \type_id
+ * \param[in] membno Number of the enumeration datatype member
+ * \param[out] value Buffer for the value of the enumeration datatype member
+ *
+ * \return \herr_t
+ *
+ * \details H5Tget_member_value() returns the value of the enumeration datatype
+ *          member \p member_no.
+ *
+ *          The member value is returned in a user-supplied buffer pointed to
+ *          by \p value. Values returned in \p value will be of the enumerated
+ *          type’s base type, that is, the datatype used by H5Tenum_create()
+ *          when the enumerated type was created.
+ *
+ *          The value buffer must be at least large enough to hold a value
+ *          of that base type. If the size is unknown, you can determine it
+ *          with H5Tget_size().
+ *
+ * \since 1.2.0
+ *
+ */
 H5_DLL herr_t      H5Tget_member_value(hid_t type_id, unsigned membno, void *value /*out*/);
 /**
  * \ingroup ATOM
@@ -1965,7 +2395,74 @@ H5_DLL hid_t       H5Tget_native_type(hid_t type_id, H5T_direction_t direction);
  *
  */
 H5_DLL herr_t H5Tset_size(hid_t type_id, size_t size);
+/**
+ * \ingroup ATOM
+ *
+ * \brief Sets the byte order of a datatype
+ *
+ * \type_id
+ * \param[in] order Byte order constant
+ *
+ * \return \herr_t
+ *
+ * \details H5Tset_order() sets the byte order of a datatype.\n
+ *          Byte order can currently be set to any of the following:
+ *          \snippet this H5T_order_t_snip
+ *          #H5T_ORDER_MIXED (3) is a valid value for order only when
+ *          returned by the function H5Tget_order(); it cannot be set with
+ *          H5Tset_order().
+ *
+ *          #H5T_ORDER_NONE (4) is a valid value for order, but it has no
+ *          effect. It is valid only for fixed-length strings and object and
+ *          region references and specifies “no particular order.”
+ *
+ *          The byte order of a derived datatype is initially the same as
+ *          that of the parent type, but can be changed with H5Tset_order().
+ *
+ *          This function cannot be used with a datatype after it has been
+ *          committed.
+ *
+ * \note    Special considerations:
+ *          \li ENUM datatypes: Byte order must be set before any member on
+ *              an ENUM is defined.
+ *          \li Compound datatypes: Byte order is set individually on each member
+ *              of a compound datatype; members of a compound datatype need not
+ *              have the same byte order.
+ *          \li Opaque datatypes: Byte order can be set but has no effect.
+ *
+ * \since 1.2.0
+ *
+ */
 H5_DLL herr_t H5Tset_order(hid_t type_id, H5T_order_t order);
+/**
+ * \ingroup ATOM
+ *
+ * \brief Sets the precision of an atomic datatype
+ *
+ * \type_id
+ * \param[in] prec Number of bits of precision for datatype
+ *
+ * \return \herr_t
+ *
+ * \details H5Tset_precision() sets the precision of an atomic datatype. The
+ *          precision is the number of significant bits which, unless
+ *          padding is present, is 8 times larger than the value returned
+ *          by H5Tget_size().
+ *
+ *          If the precision is increased then the offset is decreased and
+ *          then the size is increased to insure that significant bits do not
+ *          "hang over" the edge of the datatype.
+ *
+ *          Changing the precision of an #H5T_STRING automatically changes
+ *          the size as well. The precision must be a multiple of 8.
+ *
+ *          When decreasing the precision of a floating point type, set the
+ *          locations and sizes of the sign, mantissa, and exponent fields
+ *          first.
+ *
+ * \since 1.2.0
+ *
+ */
 H5_DLL herr_t H5Tset_precision(hid_t type_id, size_t prec);
 /**
  * \ingroup ATOM
@@ -2001,7 +2498,41 @@ H5_DLL herr_t H5Tset_precision(hid_t type_id, size_t prec);
  *
  */
 H5_DLL herr_t H5Tset_offset(hid_t type_id, size_t offset);
+/**
+ * \ingroup ATOM
+ *
+ * \brief Sets the least and most-significant bits padding types
+ *
+ * \type_id
+ * \param[in] lsb Padding type for least-significant bits
+ * \param[in] msb Padding type for most-significant bits
+ *
+ * \return \herr_t
+ *
+ * \details H5Tset_pad() sets the least and most-significant bits padding types.
+ *          Available values are:
+ * \padding_type
+ *
+ * \since 1.2.0
+ *
+ */
 H5_DLL herr_t H5Tset_pad(hid_t type_id, H5T_pad_t lsb, H5T_pad_t msb);
+/**
+ * \ingroup ATOM
+ *
+ * \brief Sets the sign property for an integer type
+ *
+ * \type_id
+ * \param[in] sign Sign type
+ *
+ * \return \herr_t
+ *
+ * \details H5Tset_sign() sets the sign property for an integer type:
+ * \sign_prop
+ *
+ * \since 1.2.0
+ *
+ */
 H5_DLL herr_t H5Tset_sign(hid_t type_id, H5T_sign_t sign);
 /**
  * \ingroup ATOM
@@ -2118,6 +2649,37 @@ H5_DLL herr_t H5Tset_inpad(hid_t type_id, H5T_pad_t pad);
  *
  */
 H5_DLL herr_t H5Tset_cset(hid_t type_id, H5T_cset_t cset);
+/**
+ * \ingroup ATOM
+ *
+ * \brief Defines the type of padding used for character strings
+ *
+ * \type_id
+ * \param[in] strpad String padding type
+ *
+ * \return \herr_t
+ *
+ * \details H5Tset_strpad() defines the type of padding used for a string
+ *          datatype.
+ *
+ *          The method used to store character strings differs with the
+ *          programming language.  C usually null terminates strings while
+ *          Fortran left-justifies and space-pads strings.
+ *
+ *          Valid values of \p strpad are as follows:
+ *          \str_pad_type
+ *          When converting from a longer string to a shorter string, the
+ *          behavior is as follows. If the shorter string is #H5T_STR_NULLPAD
+ *          or #H5T_STR_SPACEPAD, then the string is simply truncated. If
+ *          the short string is #H5T_STR_NULLTERM, it is truncated and a null
+ *          terminator is appended.
+ *
+ *          When converting from a shorter string to a longer string, the
+ *          longer string is padded on the end by appending nulls or spaces.
+ *
+ * \since 1.2.0
+ *
+ */
 H5_DLL herr_t H5Tset_strpad(hid_t type_id, H5T_str_t strpad);
 
 /* Type conversion database */
@@ -2286,6 +2848,28 @@ H5_DLL htri_t     H5Tcompiler_conv(hid_t src_id, hid_t dst_id);
  */
 H5_DLL herr_t     H5Tconvert(hid_t src_id, hid_t dst_id, size_t nelmts, void *buf, void *background,
                              hid_t plist_id);
+/**
+ * \ingroup VLEN
+ *
+ * \brief Reclaims the variable length (VL) datatype memory buffers
+ *
+ * \type_id
+ * \space_id
+ * \dxpl_id{plist_id} used to create the buffer
+ * \param[in] buf Pointer to the buffer to be reclaimed
+ *
+ * \return \herr_t
+ *
+ * \details H5Treclaim() reclaims memory buffers created to store VL datatypes.
+ *          It only frees the variable length data in the selection defined in
+ *          the dataspace specified by \p space_id. The dataset transfer
+ *          property list \p plist_id is required to find the correct
+ *          allocation and/or free methods for the variable-length data in the
+ *          buffer.
+ *
+ * \since 1.12.0
+ *
+ */
 H5_DLL herr_t     H5Treclaim(hid_t type_id, hid_t space_id, hid_t plist_id, void *buf);
 
 /* Symbols defined for compatibility with previous versions of the HDF5 API.
@@ -2299,10 +2883,139 @@ H5_DLL herr_t     H5Treclaim(hid_t type_id, hid_t space_id, hid_t plist_id, void
 /* Typedefs */
 
 /* Function prototypes */
+/**
+ * \ingroup H5T
+ *
+ * \brief Commits a transient datatype to a file, creating a new named datatype
+ *
+ * \fg_loc_id
+ * \param[in] name Name given to committed datatype
+ * \param[in] type_id Identifier of datatype to be committed
+ *
+ * \return \herr_t
+ *
+ * \deprecated This function has been renamed from H5Tcommit() and is
+ *             deprecated in favor of the macro #H5Tcommit or the function
+ *             H5Tcommit2().
+ *
+ * \details H5Tcommit1() commits the transient datatype (not immutable) to
+ *          a file, turning it into a named datatype.
+ *
+ *          The datatype \p dtype_id is committed as a named datatype at the
+ *          location \p loc_id, which is either a file or group identifier,
+ *          with the name \p name.
+ *
+ *          \p name can be a relative path based at \p loc_id or an absolute
+ *          path from the root of the file. Use of this function requires
+ *          that any intermediate groups specified in the path already exist.
+ *
+ *          As is the case for any object in a group, the length of the name
+ *          of a named datatype is not limited.
+ *
+ *          See H5Tcommit_anon() for a discussion of the differences between
+ *          H5Tcommit() and H5Tcommit_anon().
+ *
+ *          This function will not accept a datatype that cannot actually
+ *          hold data. This currently includes compound datatypes with no
+ *          fields and enumerated datatypes with no members.
+ *
+ * \version 1.8.7 Function modified in this release to reject datatypes that
+ *          will not accommodate actual data, such as a compound datatype with
+ *          no fields or an enumerated datatype with no members.
+ * \version 1.8.0 C function H5Tcommit() renamed to H5Tcommit1() and deprecated
+ *          in this release.
+ * \since 1.2.0
+ *
+ */
 H5_DLL herr_t H5Tcommit1(hid_t loc_id, const char *name, hid_t type_id);
+/**
+ * \ingroup H5T
+ *
+ * \brief Opens a named datatype
+ *
+ * \fg_loc_id
+ * \param[in] name A datatype name, defined within the specified file or group
+ *
+ * \return \herr_t
+ *
+ * \deprecated This function has been renamed from H5Topen() and is
+ *             deprecated in favor of the macro #H5Topen or the function
+ *             H5Topen2().
+ *
+ * \details H5Topen1() opens a named datatype at the location specified by
+ *          \p loc_id and returns an identifier for the datatype. \p loc_id
+ *          can be either a file or group identifier. The identifier should
+ *          eventually be closed by calling H5Tclose()  to release resources.
+ *
+ * \version 1.8.0 Function H5Topen() renamed to H5Topen1() and deprecated in
+ *          this release.
+ *
+ * \since 1.2.0
+ *
+ */
 H5_DLL hid_t  H5Topen1(hid_t loc_id, const char *name);
+/**
+ * \ingroup ARRAY
+ *
+ * \brief Creates an array datatype object
+ *
+ * \param[in] base_id Datatype identifier for the array base datatype
+ * \param[in] ndims Rank of the array
+ * \param[in] dim Size of each array dimension
+ * \param[in] perm Dimension permutation   (Currently not implemented.)
+ *
+ * \return \hid_t{array datatype}
+ *
+ * \deprecated This function has been renamed from H5Tarray_create() and is
+ *             deprecated in favor of the macro #H5Tarray_create or the function
+ *             H5Tarray_create2().
+ *
+ * \details H5Tarray_create1() creates a new array datatype object.\n\n
+ *          \p base_id is the datatype of every element of the array, i.e.,
+ *          of the number at each position in the array.
+ *
+ *          \p rank is the number of dimensions and the size of each dimension
+ *          is specified in the array dims. The value of rank is currently
+ *          limited to #H5S_MAX_RANK and must be greater than 0 (zero). All
+ *          dimension sizes specified in dims must be greater than 0 (zero).
+ *
+ *          The array \p perm is designed to contain the dimension permutation,
+ *          i.e. C versus FORTRAN array order.   (The parameter perm is
+ *          currently unused and is not yet implemented.)
+ *
+ * \version 1.8.0 Function H5Tarray_create() renamed to H5Tarray_create1()
+ *          and deprecated in this release.
+ * \since 1.4.0
+ *
+ */
 H5_DLL hid_t  H5Tarray_create1(hid_t base_id, int ndims, const hsize_t dim[/* ndims */],
                                const int perm[/* ndims */]);
+/**
+ * \ingroup ARRAY
+ *
+ * \brief Retrieves sizes of array dimensions
+ *
+ * \type_id
+ * \param[out] dims Sizes of array dimensions
+ * \param[out] perm Dimension permutations (This parameter is not used.)
+ *
+ * \return Returns the non-negative number of dimensions of the array type
+ *         if successful; otherwise, returns a negative value.
+ *
+ * \deprecated This function has been renamed from H5Tget_array_dims() and is
+ *             deprecated in favor of the macro #H5Tget_array_dims or the
+ *             function H5Tget_array_dims2().
+ *
+ * \details H5Tget_array_dims1() returns the sizes of the dimensions and
+ *          the dimension permutations of the specified array datatype object.
+ *
+ *          The sizes of the dimensions are returned in the array \p dims.
+ *
+ * \version 1.8.0 Function H5Tarray_create() renamed to H5Tarray_create1()
+ *          and deprecated in this release.
+ * \since 1.2.0
+ *
+ */
 H5_DLL int    H5Tget_array_dims1(hid_t type_id, hsize_t dims[], int perm[]);
 
 #endif /* H5_NO_DEPRECATED_SYMBOLS */

From 339c0a6c79d1a4d6f1fb644757d4ccd3f744a554 Mon Sep 17 00:00:00 2001
From: Gerd Heber <gheber@hdfgroup.org>
Date: Wed, 18 Nov 2020 14:16:20 -0600
Subject: [PATCH 11/16] Migrated documentation for SWMR functions.

---
 src/H5Fpublic.h | 111 +++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 109 insertions(+), 2 deletions(-)

diff --git a/src/H5Fpublic.h b/src/H5Fpublic.h
index be8eced254f..060eeb21b54 100644
--- a/src/H5Fpublic.h
+++ b/src/H5Fpublic.h
@@ -226,6 +226,7 @@ typedef enum H5F_file_space_type_t {
     H5F_FILE_SPACE_NTYPES           /**< Sentinel */
 } H5F_file_space_type_t;
 
+//! [H5F_retry_info_t_snip]
 #define H5F_NUM_METADATA_READ_RETRY_TYPES 21
 
 /**
@@ -236,6 +237,7 @@ typedef struct H5F_retry_info_t {
     unsigned  nbins;
     uint32_t *retries[H5F_NUM_METADATA_READ_RETRY_TYPES];
 } H5F_retry_info_t;
+//! [H5F_retry_info_t_snip]
 
 /**
  * Callback for H5Pset_object_flush_cb() in a file access property list
@@ -1068,13 +1070,118 @@ H5_DLL herr_t   H5Fget_info2(hid_t obj_id, H5F_info2_t *file_info);
 /**
  * \ingroup SWMR
  *
- * \todo Finish this!
+ * \brief Retrieves the collection of read retries for metadata entries with checksum
+ *
+ * \file_id
+ * \param[out] info Struct containing the collection of read retries for metadata
+ *                  entries with checksum
+ * \return \herr_t\n
+ *
+ * \details \Bold{Failure Modes:}
+ *       \li When the input identifier is not a file identifier.
+ *       \li When the pointer to the output structure is NULL.
+ *       \li When the memory allocation for \p retries failed.
+ *
+ * \details H5Fget_metadata_read_retry_info() retrieves information regarding the number
+ *          of read retries for metadata entries with checksum for the file \p file_id.
+ *          This information is reported in the H5F_retry_info_t struct defined in
+ *          H5Fpublic.h as follows:
+ *          \snippet this H5F_retry_info_t_snip
+ *          \c nbins is the number of bins for each \c retries[i] of metadata entry \c i.
+ *          It is calculated based on the current number of read attempts used in the
+ *          library and logarithmic base 10.
+ *
+ *          If read retries are incurred for a metadata entry \c i, the library will
+ *          allocate memory for \Code{retries[i] (nbins * sizeof(uint32_t)} and store
+ *          the collection of retries there. If there are no retries for a metadata entry
+ *          \c i, \Code{retries[i]} will be NULL. After a call to this routine, users should
+ *          free each \Code{retries[i]} that is non-NULL, otherwise resource leak will occur.
+ *
+ *          For the library default read attempts of 100 for SWMR access, nbins will be 2
+ *          as depicted below:
+ *          \li \Code{retries[i][0]} is the number of 1 to 9 read retries.
+ *          \li \Code{retries[i][1]} is the number of 10 to 99 read retries.
+ *          For the library default read attempts of 1 for non-SWMR access, \c nbins will
+ *          be 0 and each \Code{retries[i]} will be NULL.
+ *
+ *          The following table lists the 21 metadata entries of \Code{retries[]}:
+ *          <table>
+ *          <tr>
+ *          <th>Index for \Code{retries[]}</th>
+ *          <th>Metadata entries<sup>*</sup></th>
+ *          </tr>
+ *          <tr><td>0</td><td>Object header (version 2)</td></tr>
+ *          <tr><td>1</td><td>Object header chunk (version 2)</td></tr>
+ *          <tr><td>2</td><td>B-tree header (version 2)</td></tr>
+ *          <tr><td>3</td><td>B-tree internal node (version 2)</td></tr>
+ *          <tr><td>4</td><td>B-tree leaf node (version 2)</td></tr>
+ *          <tr><td>5</td><td>Fractal heap header</td></tr>
+ *          <tr><td>6</td><td>Fractal heap direct block (optional checksum)</td></tr>
+ *          <tr><td>7</td><td>Fractal heap indirect block</td></tr>
+ *          <tr><td>8</td><td>Free-space header</td></tr>
+ *          <tr><td>9</td><td>Free-space sections</td></tr>
+ *          <tr><td>10</td><td>Shared object header message table</td></tr>
+ *          <tr><td>11</td><td>Shared message record list</td></tr>
+ *          <tr><td>12</td><td>Extensive array header</td></tr>
+ *          <tr><td>13</td><td>Extensive array index block</td></tr>
+ *          <tr><td>14</td><td>Extensive array super block</td></tr>
+ *          <tr><td>15</td><td>Extensive array data block</td></tr>
+ *          <tr><td>16</td><td>Extensive array data block page</td></tr>
+ *          <tr><td>17</td><td>Fixed array super block</td></tr>
+ *          <tr><td>18</td><td>Fixed array data block</td></tr>
+ *          <tr><td>19</td><td>Fixed array data block page</td></tr>
+ *          <tr><td>20</td><td>File's superblock (version 2)</td></tr>
+ *          <tr><td colspan=2><sup>*</sup> All entries are of version 0 (zero) unless indicated otherwise.</td></tr>
+ *          </table>
+ *
+ * \note   On a system that is not atomic, the library might possibly read inconsistent
+ *         metadata with checksum when performing single-writer/multiple-reader (SWMR)
+ *         operations for an HDF5 file. Upon encountering such situations, the library
+ *         will try reading the metadata again for a set number of times to attempt to
+ *         obtain consistent data. The maximum number of read attempts used by the library
+ *         will be either the value set via H5Pset_metadata_read_attempts() or the library
+ *         default value when a value is not set.\n
+ *         When the current number of metadata read attempts used in the library is unable
+ *         to remedy the reading of inconsistent metadata on a system, the user can assess
+ *         the information obtained via this routine to derive a different maximum value.
+ *         The information can also be helpful for debugging purposes to identify potential
+ *         issues with metadata flush dependencies and SWMR implementation in general.
+ *
+ * \since 1.10.0
+ *
  */
 H5_DLL herr_t   H5Fget_metadata_read_retry_info(hid_t file_id, H5F_retry_info_t *info);
 /**
  * \ingroup SWMR
  *
- * \todo Finish this!
+ * \brief Retrieves free-space section information for a file
+ *
+ * \file_id
+ *
+ * \return \herr_t
+ *
+ * \details H5Fstart_swmr_write() will activate SWMR writing mode for a file
+ *          associated with \p file_id. This routine will prepare and ensure
+ *          the file is safe for SWMR writing as follows:
+ *          \li Check that the file is opened with write access (#H5F_ACC_RDWR).
+ *          \li Check that the file is opened with the latest library format to
+ *              ensure data structures with check-summed metadata are used.
+ *          \li Check that the file is not already marked in SWMR writing mode.
+ *          \li Enable reading retries for check-summed metadata to remedy
+ *              possible checksum failures from reading inconsistent metadata
+ *              on a system that is not atomic.
+ *          \li Turn off usage of the library's accumulator to avoid possible
+ *              ordering problem on a system that is not atomic.
+ *          \li Perform a flush of the file’s data buffers and metadata to set
+ *              a consistent state for starting SWMR write operations.
+ *
+ *          Library objects are groups, datasets, and committed datatypes. For
+ *          the current implementation, groups and datasets can remain open when
+ *          activating SWMR writing mode, but not committed datatypes. Attributes
+ *          attached to objects cannot remain open either.
+ *
+ * \since 1.10.0
+ *
  */
 H5_DLL herr_t   H5Fstart_swmr_write(hid_t file_id);
 /**

From 776fea8db9be48c574a7d403911e30835bd1df33 Mon Sep 17 00:00:00 2001
From: Gerd Heber <gheber@hdfgroup.org>
Date: Wed, 18 Nov 2020 17:15:23 -0600
Subject: [PATCH 12/16] Catching up on MDC functions.

---
 doxygen/dox/H5AC_cache_config_t.dox | 415 ++++++++++++++++++++++++++++
 src/H5Fpublic.h                     | 155 ++++++++++-
 2 files changed, 566 insertions(+), 4 deletions(-)
 create mode 100644 doxygen/dox/H5AC_cache_config_t.dox

diff --git a/doxygen/dox/H5AC_cache_config_t.dox b/doxygen/dox/H5AC_cache_config_t.dox
new file mode 100644
index 00000000000..9b9862b6c1e
--- /dev/null
+++ b/doxygen/dox/H5AC_cache_config_t.dox
@@ -0,0 +1,415 @@
+/**
+ * \page H5AC-cache-config-t Metadata Cache Configuration
+ * \tableofcontents
+ *
+ * \section gcf General configuration fields
+ *
+ * \par version
+ *      Integer field containing the version number of this version
+ *      of the H5AC_cache_config_t structure.  Any instance of
+ *      H5AC_cache_config_t passed to the cache must have a known
+ *      version number, or an error will be flagged.
+ *
+ * \par rpt_fcn_enabled
+ * \parblock
+ *    Boolean field used to enable and disable the default
+ *    reporting function.  This function is invoked every time the
+ *    automatic cache resize code is run, and reports on its activities.
+ *
+ *    This is a debugging function, and should normally be turned off.
+ * \endparblock
+ *
+ * \par open_trace_file
+ * \parblock
+ *     Boolean field indicating whether the trace_file_name
+ *     field should be used to open a trace file for the cache.
+ *
+ *     \Emph{*** DEPRECATED ***} Use \Code{H5Fstart/stop} logging functions instead
+ *
+ *     The trace file is a debuging feature that allow the capture of
+ *     top level metadata cache requests for purposes of debugging and/or
+ *     optimization.  This field should normally be set to \c FALSE, as
+ *     trace file collection imposes considerable overhead.
+ *
+ *     This field should only be set to \c TRUE when the trace_file_name
+ *     contains the full path of the desired trace file, and either
+ *     there is no open trace file on the cache, or the \c close_trace_file
+ *     field is also \c TRUE.
+ * \endparblock
+ *
+ * \par close_trace_file
+ * \parblock
+ *     Boolean field indicating whether the current trace
+ *     file (if any) should be closed.
+ *
+ *     \Emph{*** DEPRECATED ***} Use \Code{H5Fstart/stop} logging functions instead
+ *
+ *     See the above comments on the open_trace_file field.  This field
+ *     should be set to \c FALSE unless there is an open trace file on the
+ *     cache that you wish to close.
+ * \endparblock
+ *
+ * \par trace_file_name
+ * \parblock
+ *     Full path of the trace file to be opened if the
+ *     open_trace_file field is \c TRUE.
+ *
+ *     \Emph{*** DEPRECATED ***} Use \Code{H5Fstart/stop} logging functions instead
+ *
+ *     In the parallel case, an ascii representation of the mpi rank of
+ *     the process will be appended to the file name to yield a unique
+ *     trace file name for each process.
+ *
+ *     The length of the path must not exceed #H5AC__MAX_TRACE_FILE_NAME_LEN
+ *     characters.
+ * \endparblock
+ *
+ * \par evictions_enabled
+ * \parblock
+ *     Boolean field used to either report the current
+ *     evictions enabled status of the cache, or to set the cache's
+ *     evictions enabled status.
+ *
+ *     In general, the metadata cache should always be allowed to
+ *     evict entries.  However, in some cases it is advantageous to
+ *     disable evictions briefly, and thereby postpone metadata
+ *     writes.  However, this must be done with care, as the cache
+ *     can grow quickly.  If you do this, re-enable evictions as
+ *     soon as possible and monitor cache size.
+ *
+ *     At present, evictions can only be disabled if automatic
+ *     cache resizing is also disabled (that is, \Code{(incr_mode ==
+ *     H5C_incr__off ) && ( decr_mode == H5C_decr__off )}).  There
+ *     is no logical reason why this should be so, but it simplifies
+ *     implementation and testing, and I can't think of any reason
+ *     why it would be desireable.  If you can think of one, I'll
+ *     revisit the issue. (JM)
+ * \endparblock
+ *
+ * \par set_initial_size
+ *      Boolean flag indicating whether the size of the
+ *      initial size of the cache is to be set to the value given in
+ *      the initial_size field.  If set_initial_size is \c FALSE, the
+ *      initial_size field is ignored.
+ *
+ * \par initial_size
+ *      If enabled, this field contain the size the cache is
+ *      to be set to upon receipt of this structure.  Needless to say,
+ *      initial_size must lie in the closed interval \Code{[min_size, max_size]}.
+ *
+ * \par min_clean_fraction
+ *      \c double in the range 0 to 1 indicating the fraction
+ *      of the cache that is to be kept clean.  This field is only used
+ *      in parallel mode. Typical values are 0.1 to 0.5.
+ *
+ * \par max_size
+ *      Maximum size to which the cache can be adjusted.  The
+ *      supplied value must fall in the closed interval
+ *      \Code{[MIN_MAX_CACHE_SIZE, MAX_MAX_CACHE_SIZE]}.  Also, \c max_size must
+ *      be greater than or equal to \c min_size.
+ *
+ * \par min_size
+ *      Minimum size to which the cache can be adjusted.  The
+ *      supplied value must fall in the closed interval
+ *      \Code{[H5C__MIN_MAX_CACHE_SIZE, H5C__MAX_MAX_CACHE_SIZE]}.  Also, \c min_size
+ *      must be less than or equal to \c max_size.
+ *
+ * \par epoch_length
+ * \parblock
+ *      Number of accesses on the cache over which to collect
+ *      hit rate stats before running the automatic cache resize code,
+ *      if it is enabled.
+ *
+ *      At the end of an epoch, we discard prior hit rate data and start
+ *      collecting afresh.  The epoch_length must lie in the closed
+ *      interval \Code{[H5C__MIN_AR_EPOCH_LENGTH, H5C__MAX_AR_EPOCH_LENGTH]}.
+ * \endparblock
+ *
+ *
+ * \section csicf Cache size increase control fields
+ *
+ * \par incr_mode
+ *      Instance of the \c H5C_cache_incr_mode enumerated type whose
+ *      value indicates how we determine whether the cache size should be
+ *      increased.  At present there are two possible values:
+ *      \li \c H5C_incr__off:  Don't attempt to increase the size of the cache
+ *              automatically.\n
+ *              When this increment mode is selected, the remaining fields
+ *              in the cache size increase section ar ignored.
+ *      \li \c H5C_incr__threshold: Attempt to increase the size of the cache
+ *              whenever the average hit rate over the last epoch drops
+ *              below the value supplied in the \c lower_hr_threshold
+ *              field.\n
+ *              Note that this attempt will fail if the cache is already
+ *              at its maximum size, or if the cache is not already using
+ *              all available space.
+ *
+ *      Note that you must set \c decr_mode to \c H5C_incr__off if you
+ *      disable metadata cache entry evictions.
+ *
+ * \par lower_hr_threshold
+ * \parblock
+ *      Lower hit rate threshold.  If the increment mode
+ *      (\c incr_mode) is \c H5C_incr__threshold and the hit rate drops below the
+ *      value supplied in this field in an epoch, increment the cache size by
+ *      \c size_increment.  Note that cache size may not be incremented above
+ *      \c max_size, and that the increment may be further restricted by the
+ *      \c max_increment field if it is enabled.
+ *
+ *      When enabled, this field must contain a value in the range [0.0, 1.0].
+ *      Depending on the \c incr_mode selected, it may also have to be less than
+ *      \c upper_hr_threshold.
+ * \endparblock
+ *
+ * \par increment
+ * \parblock
+ *      Double containing the multiplier used to derive the new
+ *      cache size from the old if a cache size increment is triggered.
+ *      The increment must be greater than 1.0, and should not exceed 2.0.
+ *
+ *      The new cache size is obtained my multiplying the current max cache
+ *      size by the increment, and then clamping to \c max_size and to stay
+ *      within the \c max_increment as necessary.
+ * \endparblock
+ *
+ * \par apply_max_increment
+ *      Boolean flag indicating whether the \c max_increment
+ *      field should be used to limit the maximum cache size increment.
+ *
+ * \par max_increment
+ *      If enabled by the \c apply_max_increment field described
+ *      above, this field contains the maximum number of bytes by which the
+ *      cache size can be increased in a single re-size.
+ *
+ * \par flash_incr_mode
+ * \parblock
+ *      Instance of the \c H5C_cache_flash_incr_mode enumerated
+ *      type whose value indicates whether and by which algorithm we should
+ *      make flash increases in the size of the cache to accommodate insertion
+ *      of large entries and large increases in the size of a single entry.
+ *
+ *      The addition of the flash increment mode was occasioned by performance
+ *      problems that appear when a local heap is increased to a size in excess
+ *      of the current cache size.  While the existing re-size code dealt with
+ *      this eventually, performance was very bad for the remainder of the
+ *      epoch.
+ *
+ *      At present, there are two possible values for the \c flash_incr_mode:
+ *
+ *      \li \c H5C_flash_incr__off:  Don't perform flash increases in the size of the cache.
+ *
+ *      \li \c H5C_flash_incr__add_space:  Let \c x be either the size of a newly
+ *          newly inserted entry, or the number of bytes by which the
+ *          size of an existing entry has been increased.\n
+ *          If \Code{x > flash_threshold * current max cache size},
+ *          increase the current maximum cache size by \Code{x * flash_multiple}
+ *          less any free space in the cache, and star a new epoch.  For
+ *          now at least, pay no attention to the maximum increment.
+ *
+ *      In both of the above cases, the flash increment pays no attention to
+ *      the maximum increment (at least in this first incarnation), but DOES
+ *      stay within max_size.
+ *
+ *      With a little thought, it should be obvious that the above flash
+ *      cache size increase algorithm is not sufficient for all circumstances
+ *      -- for example, suppose the user round robins through
+ *      \Code{(1/flash_threshold) +1} groups, adding one data set to each on each
+ *      pass.  Then all will increase in size at about the same time, requiring
+ *      the max cache size to at least double to maintain acceptable
+ *      performance, however the above flash increment algorithm will not be
+ *      triggered.
+ *
+ *      Hopefully, the add space algorithms detailed above will be sufficient
+ *      for the performance problems encountered to date.  However, we should
+ *      expect to revisit the issue.
+ * \endparblock
+ *
+ * \par flash_multiple
+ *      Double containing the multiple described above in the
+ *      \c H5C_flash_incr__add_space section of the discussion of the
+ *      \c flash_incr_mode section.  This field is ignored unless \c flash_incr_mode
+ *      is \c H5C_flash_incr__add_space.
+ *
+ * \par flash_threshold
+ *      Double containing the factor by which current max cache
+ *      size is multiplied to obtain the size threshold for the add_space flash
+ *      increment algorithm.  The field is ignored unless \c flash_incr_mode is
+ *      \c H5C_flash_incr__add_space.
+ *
+ *
+ * \section csdcf Cache size decrease control fields
+ *
+ * \par decr_mode
+ * \parblock
+ *      Instance of the \c H5C_cache_decr_mode enumerated type whose
+ *      value indicates how we determine whether the cache size should be
+ *      decreased.  At present there are four possibilities.
+ *
+ *      \li \c H5C_decr__off:  Don't attempt to decrease the size of the cache
+ *              automatically.\n
+ *              When this increment mode is selected, the remaining fields
+ *              in the cache size decrease section are ignored.
+ *      \li \c H5C_decr__threshold: Attempt to decrease the size of the cache
+ *              whenever the average hit rate over the last epoch rises
+ *              above the value supplied in the \c upper_hr_threshold
+ *              field.
+ *      \li \c H5C_decr__age_out:  At the end of each epoch, search the cache for
+ *              entries that have not been accessed for at least the number
+ *              of epochs specified in the epochs_before_eviction field, and
+ *              evict these entries.  Conceptually, the maximum cache size
+ *              is then decreased to match the new actual cache size.  However,
+ *              this reduction may be modified by the \c min_size, the
+ *              \c max_decrement, and/or the \c empty_reserve.
+ *      \li \c H5C_decr__age_out_with_threshold:  Same as age_out, but we only
+ *              attempt to reduce the cache size when the hit rate observed
+ *              over the last epoch exceeds the value provided in the
+ *              \c upper_hr_threshold field.
+ *
+ *      Note that you must set \c decr_mode to \c H5C_decr__off if you
+ *      disable metadata cache entry evictions.
+ * \endparblock
+ *
+ * \par upper_hr_threshold
+ * \parblock
+ *      Upper hit rate threshold.  The use of this field
+ *      varies according to the current \c decr_mode :
+ *
+ *      \c H5C_decr__off or \c H5C_decr__age_out:  The value of this field is
+ *              ignored.
+ *
+ *      \li \c H5C_decr__threshold:  If the hit rate exceeds this threshold in any
+ *              epoch, attempt to decrement the cache size by size_decrement.\n
+ *              Note that cache size may not be decremented below \c min_size.\n
+ *              Note also that if the \c upper_threshold is 1.0, the cache size\n
+ *              will never be reduced.
+ *
+ *      \li \c H5C_decr__age_out_with_threshold:  If the hit rate exceeds this
+ *              threshold in any epoch, attempt to reduce the cache size
+ *              by evicting entries that have not been accessed for more
+ *              than the specified number of epochs.
+ * \endparblock
+ *
+ * \par decrement
+ * \parblock
+ *      This field is only used when the decr_mode is
+ *      \c H5C_decr__threshold.
+ *
+ *      The field is a double containing the multiplier used to derive the
+ *      new cache size from the old if a cache size decrement is triggered.
+ *      The decrement must be in the range 0.0 (in which case the cache will
+ *      try to contract to its minimum size) to 1.0 (in which case the
+ *      cache will never shrink).
+ * \endparblock
+ *
+ * \par apply_max_decrement
+ *      Boolean flag used to determine whether decrements
+ *      in cache size are to be limited by the \c max_decrement field.
+ *
+ * \par max_decrement
+ *      Maximum number of bytes by which the cache size can be
+ *      decreased in a single re-size.  Note that decrements may also be
+ *      restricted by the \c min_size of the cache, and (in age out modes) by
+ *      the \c empty_reserve field.
+ *
+ * \par epochs_before_eviction
+ * \parblock
+ *      Integer field used in \c H5C_decr__age_out and
+ *      \c H5C_decr__age_out_with_threshold decrement modes.
+ *
+ *      This field contains the number of epochs an entry must remain
+ *      unaccessed before it is evicted in an attempt to reduce the
+ *      cache size.  If applicable, this field must lie in the range
+ *      \Code{[1, H5C__MAX_EPOCH_MARKERS]}.
+ * \endparblock
+ *
+ * \par apply_empty_reserve
+ *      Boolean field controlling whether the empty_reserve
+ *      field is to be used in computing the new cache size when the
+ *      decr_mode is H5C_decr__age_out or H5C_decr__age_out_with_threshold.
+ *
+ * \par empty_reserve
+ * \parblock
+ *      To avoid a constant racheting down of cache size by small
+ *      amounts in the \c H5C_decr__age_out and \c H5C_decr__age_out_with_threshold
+ *      modes, this field allows one to require that any cache size
+ *      reductions leave the specified fraction of unused space in the cache.
+ *
+ *      The value of this field must be in the range [0.0, 1.0].  I would
+ *      expect typical values to be in the range of 0.01 to 0.1.
+ * \endparblock
+ *
+ *
+ * \section pcf Parallel Configuration Fields
+ *
+ * In PHDF5, all operations that modify metadata must be executed collectively.
+ *
+ * We used to think that this was enough to ensure consistency across the
+ * metadata caches, but since we allow processes to read metadata individually,
+ * the order of dirty entries in the LRU list can vary across processes,
+ * which can result in inconsistencies between the caches.
+ *
+ * PHDF5 uses several strategies to prevent such inconsistencies in metadata,
+ * all of which use the fact that the same stream of dirty metadata is seen
+ * by all processes for purposes of synchronization.  This is done by
+ * having each process count the number of bytes of dirty metadata generated,
+ * and then running a "sync point" whenever this count exceeds a user
+ * specified threshold (see \c dirty_bytes_threshold below).
+ *
+ * The current metadata write strategy is indicated by the
+ * \c metadata_write_strategy field.  The possible values of this field, along
+ * with the associated metadata write strategies are discussed below.
+ *
+ * \par dirty_bytes_threshold
+ * \parblock
+ *    Threshold of dirty byte creation used to
+ *    synchronize updates between caches. (See above for outline and
+ *    motivation.)
+ *
+ *    This value MUST be consistent across all processes accessing the
+ *    file.  This field is ignored unless HDF5 has been compiled for
+ *    parallel.
+ * \endparblock
+ *
+ * \par metadata_write_strategy
+ *    Integer field containing a code indicating the
+ *    desired metadata write strategy.  The valid values of this field
+ *    are enumerated and discussed below:
+ *
+ *    \li #H5AC_METADATA_WRITE_STRATEGY__PROCESS_0_ONLY\n
+ *    When metadata_write_strategy is set to this value, only process
+ *    zero is allowed to write dirty metadata to disk.  All other
+ *    processes must retain dirty metadata until they are informed at
+ *    a sync point that the dirty metadata in question has been written
+ *    to disk.\n
+ *    When the sync point is reached (or when there is a user generated
+ *    flush), process zero flushes sufficient entries to bring it into
+ *    complience with its min clean size (or flushes all dirty entries in
+ *    the case of a user generated flush), broad casts the list of
+ *    entries just cleaned to all the other processes, and then exits
+ *    the sync point.\n
+ *    Upon receipt of the broadcast, the other processes mark the indicated
+ *    entries as clean, and leave the sync point as well.
+ *
+ *    \li #H5AC_METADATA_WRITE_STRATEGY__DISTRIBUTED\n
+ *    In the distributed metadata write strategy, process zero still makes
+ *    the decisions as to what entries should be flushed, but the actual
+ *    flushes are distributed across the processes in the computation to
+ *    the extent possible.\n
+ *    In this strategy, when a sync point is triggered (either by dirty
+ *    metadata creation or manual flush), all processes enter a barrier.\n
+ *    On the other side of the barrier, process 0 constructs an ordered
+ *    list of the entries to be flushed, and then broadcasts this list
+ *    to the caches in all the processes.\n
+ *    All processes then scan the list of entries to be flushed, flushing
+ *    some, and marking the rest as clean.  The algorithm for this purpose
+ *    ensures that each entry in the list is flushed exactly once, and
+ *    all are marked clean in each cache.\n
+ *    Note that in the case of a flush of the cache, no message passing
+ *    is necessary, as all processes have the same list of dirty entries,
+ *    and all of these entries must be flushed.  Thus in this case it is
+ *    sufficient for each process to sort its list of dirty entries after
+ *    leaving the initial barrier, and use this list as if it had been
+ *    received from process zero.\n
+ *    To avoid possible messages from the past/future, all caches must
+ *    wait until all caches are done before leaving the sync point.
+ */
\ No newline at end of file
diff --git a/src/H5Fpublic.h b/src/H5Fpublic.h
index 060eeb21b54..16697975c28 100644
--- a/src/H5Fpublic.h
+++ b/src/H5Fpublic.h
@@ -955,7 +955,32 @@ H5_DLL ssize_t  H5Fget_file_image(hid_t file_id, void *buf_ptr, size_t buf_len);
 /**
  * \ingroup MDC
  *
- * \todo Finish this!
+ * \brief Obtains current metadata cache configuration for target file
+ *
+ * \file_id
+ * \param[in,out] config_ptr Pointer to the H5AC_cache_config_t instance in which
+ *                        the current metadata cache configuration is to be
+ *                        reported. The fields of this structure are discussed
+ *                        \ref H5AC-cache-config-t "here".
+ * \return \herr_t
+ *
+ * \details H5Fget_mdc_config() loads the current metadata cache configuration
+ *          into the instance of H5AC_cache_config_t pointed to by the \p config_ptr
+ *          parameter.
+ *
+ *          Note that the \c version field of \p config_ptr must be initialized
+ *          --this allows the library to support old versions of the H5AC_cache_config_t
+ *          structure.
+ *
+ *          See the overview of the metadata cache in the special topics section of
+ *          the user manual for details on metadata cache configuration. If you haven't
+ *          read and understood that documentation, the results of this call will not
+ *          make much sense.
+ *
+ * \since 1.8.0
+ *
+ * \todo Fix the reference!
+ *
  */
 H5_DLL herr_t   H5Fget_mdc_config(hid_t file_id, H5AC_cache_config_t *config_ptr);
 /**
@@ -1282,19 +1307,141 @@ H5_DLL herr_t   H5Fset_libver_bounds(hid_t file_id, H5F_libver_t low, H5F_libver
 /**
  * \ingroup MDC
  *
- * \todo Finish this!
+ * \brief Starts logging metadata cache events if logging was previously enabled
+ *
+ * \file_id
+ *
+ * \return \herr_t
+ *
+ * \details The metadata cache is a central part of the HDF5 library through
+ *          which all \Emph{file metadata} reads and writes take place. File
+ *          metadata is normally invisible to the user and is used by the
+ *          library for purposes such as locating and indexing data. File
+ *          metadata should not be confused with user metadata, which consists
+ *          of attributes created by users and attached to HDF5 objects such
+ *          as datasets via H5A API calls.
+ *
+ *          Due to the complexity of the cache, a trace/logging feature has been
+ *          created that can be used by HDF5 developers for debugging and performance
+ *          analysis. The functions that control this functionality will normally be
+ *          of use to a very limited number of developers outside of The HDF Group.
+ *          The functions have been documented to help users create logs that can
+ *          be sent with bug reports.
+ *
+ *          Control of the log functionality is straightforward. Logging is enabled
+ *          via the H5Pset_mdc_log_options() function, which will modify the file
+ *          access property list used to open or create a file. This function has
+ *          a flag that determines whether logging begins at file open or starts
+ *          in a paused state. Log messages can then be controlled via the
+ *          H5Fstart_mdc_logging() and H5Fstop_mdc_logging() functions.
+ *          H5Pget_mdc_log_options() can be used to examine a file access property
+ *          list, and H5Fget_mdc_logging_status() will return the current state of
+ *          the logging flags.
+ *
+ *          The log format is described in the \Emph{Metadata Cache Logging} document.
+ *
+ * \note Logging can only be started or stopped if metadata cache logging was enabled
+ *       via H5Pset_mdc_log_options().\n
+ *       When enabled and currently logging, the overhead of the logging feature will
+ *       almost certainly be significant.\n
+ *       The log file is opened when the HDF5 file is opened or created and not when
+ *       this function is called for the first time.\n
+ *       This function opens the log file and starts logging metadata cache operations
+ *       for a particular file. Calling this function when logging has already been
+ *       enabled will be considered an error.
+ *
+ * \since 1.10.0
+ *
+ * \todo Fix the document reference!
+ *
  */
 H5_DLL herr_t   H5Fstart_mdc_logging(hid_t file_id);
 /**
  * \ingroup MDC
  *
- * \todo Finish this!
+ * \brief Stops logging metadata cache events if logging was previously enabled and is currently ongoing
+ *
+ * \file_id
+ *
+ * \return \herr_t
+ *
+ * \details The metadata cache is a central part of the HDF5 library through
+ *          which all \Emph{file metadata} reads and writes take place. File
+ *          metadata is normally invisible to the user and is used by the
+ *          library for purposes such as locating and indexing data. File
+ *          metadata should not be confused with user metadata, which consists
+ *          of attributes created by users and attached to HDF5 objects such
+ *          as datasets via H5A API calls.
+ *
+ *          Due to the complexity of the cache, a trace/logging feature has been
+ *          created that can be used by HDF5 developers for debugging and performance
+ *          analysis. The functions that control this functionality will normally be
+ *          of use to a very limited number of developers outside of The HDF Group.
+ *          The functions have been documented to help users create logs that can
+ *          be sent with bug reports.
+ *
+ *          Control of the log functionality is straightforward. Logging is enabled
+ *          via the H5Pset_mdc_log_options() function, which will modify the file
+ *          access property list used to open or create a file. This function has
+ *          a flag that determines whether logging begins at file open or starts
+ *          in a paused state. Log messages can then be controlled via the
+ *          H5Fstart_mdc_logging() and H5Fstop_mdc_logging() functions.
+ *          H5Pget_mdc_log_options() can be used to examine a file access property
+ *          list, and H5Fget_mdc_logging_status() will return the current state of
+ *          the logging flags.
+ *
+ *          The log format is described in the \Emph{Metadata Cache Logging} document.
+ *
+ * \note Logging can only be started or stopped if metadata cache logging was enabled
+ *       via H5Pset_mdc_log_options().\n
+ *       This function only suspends the logging operations. The log file will remain
+ *       open and will not be closed until the HDF5 file is closed.
+ *
+ * \since 1.10.0
+ *
  */
 H5_DLL herr_t   H5Fstop_mdc_logging(hid_t file_id);
 /**
  * \ingroup MDC
  *
- * \todo Finish this!
+ * \brief Gets the current metadata cache logging status
+ *
+ * \file_id
+ * \param[out] is_enabled Whether logging is enabled
+ * \param[out] is_currently_logging Whether events are currently being logged
+ * \return \herr_t
+ *
+ * \details The metadata cache is a central part of the HDF5 library through
+ *          which all \Emph{file metadata} reads and writes take place. File
+ *          metadata is normally invisible to the user and is used by the
+ *          library for purposes such as locating and indexing data. File
+ *          metadata should not be confused with user metadata, which consists
+ *          of attributes created by users and attached to HDF5 objects such
+ *          as datasets via H5A API calls.
+ *
+ *          Due to the complexity of the cache, a trace/logging feature has been
+ *          created that can be used by HDF5 developers for debugging and performance
+ *          analysis. The functions that control this functionality will normally be
+ *          of use to a very limited number of developers outside of The HDF Group.
+ *          The functions have been documented to help users create logs that can
+ *          be sent with bug reports.
+ *
+ *          Control of the log functionality is straightforward. Logging is enabled
+ *          via the H5Pset_mdc_log_options() function, which will modify the file
+ *          access property list used to open or create a file. This function has
+ *          a flag that determines whether logging begins at file open or starts
+ *          in a paused state. Log messages can then be controlled via the
+ *          H5Fstart_mdc_logging() and H5Fstop_mdc_logging() functions.
+ *          H5Pget_mdc_log_options() can be used to examine a file access property
+ *          list, and H5Fget_mdc_logging_status() will return the current state of
+ *          the logging flags.
+ *
+ *          The log format is described in the \Emph{Metadata Cache Logging} document.
+ *
+ * \note Unlike H5Fstart_mdc_logging() and H5Fstop_mdc_logging(), this function can
+ *       be called on any open file identifier.
+ *
+ * \since 1.10.0
  */
 H5_DLL herr_t   H5Fget_mdc_logging_status(hid_t            file_id,
                                           /*OUT*/ hbool_t *is_enabled,

From 63e4fc719891c9dd144889b2ce6c0c7d509974b2 Mon Sep 17 00:00:00 2001
From: Gerd Heber <gheber@hdfgroup.org>
Date: Thu, 19 Nov 2020 16:21:10 -0600
Subject: [PATCH 13/16] Integrated the H5F MDC function documentation.

---
 src/H5Fpublic.h | 528 +++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 519 insertions(+), 9 deletions(-)

diff --git a/src/H5Fpublic.h b/src/H5Fpublic.h
index 16697975c28..bfe2b57c6da 100644
--- a/src/H5Fpublic.h
+++ b/src/H5Fpublic.h
@@ -972,10 +972,182 @@ H5_DLL ssize_t  H5Fget_file_image(hid_t file_id, void *buf_ptr, size_t buf_len);
  *          --this allows the library to support old versions of the H5AC_cache_config_t
  *          structure.
  *
- *          See the overview of the metadata cache in the special topics section of
- *          the user manual for details on metadata cache configuration. If you haven't
- *          read and understood that documentation, the results of this call will not
- *          make much sense.
+ * \par General configuration section
+ *  <table>
+ *    <tr>
+ *      <td><em>int</em> <code>version</code> </td>
+ *      <td>IN: Integer field indicating the the version of the H5AC_cache_config_t in use. This field should
+ *        be set to #H5AC__CURR_CACHE_CONFIG_VERSION (defined in H5ACpublic.h).</td>
+ *    </tr>
+ *    <tr>
+ *      <td><em>hbool_t</em> <code>rpt_fcn_enabled</code> </td>
+ *      <td><p>OUT: Boolean flag indicating whether the adaptive cache resize report function is enabled. This
+ *          field should almost always be set to disabled (<code>0</code>). Since resize algorithm activity is
+ *          reported via stdout, it MUST be set to disabled (<code>0</code>) on Windows machines.</p><p>The
+ *          report function is not supported code, and can be expected to change between versions of the
+ *          library. Use it at your own risk.</p></td>
+ *    </tr>
+ *    <tr>
+ *      <td><em>hbool_t</em> <code>open_trace_file</code> </td>
+ *      <td>OUT: Boolean field indicating whether the <code>trace_file_name</code> field should be used to open
+ *        a trace file for the cache. This field will always be set to <code>0</code> in this context.</td>
+ *    </tr>
+ *    <tr>
+ *      <td><em>hbool_t</em> <code>close_trace_file</code> </td>
+ *      <td>OUT: Boolean field indicating whether the current trace file (if any) should be closed. This field
+ *        will always be set to <code>0</code> in this context.</td></tr>
+ *    <tr>
+ *      <td><em>char*</em><code>trace_file_name</code> </td>
+ *      <td>OUT: Full path name of the trace file to be opened if the <code>open_trace_file</code> field is set
+ *        to <code>1</code>. This field will always be set to the empty string in this context.</td></tr>
+ *    <tr>
+ *      <td><em>hbool_t</em> <code>evictions_enabled</code> </td>
+ *      <td>OUT: Boolean flag indicating whether metadata cache entry evictions are
+ *        enabled.</td>
+ *    </tr>
+ *    <tr>
+ *      <td><em>hbool_t</em> <code>set_initial_size</code> </td>
+ *      <td>OUT: Boolean flag indicating whether the cache should be created with a user specified initial
+ *        maximum size.<p>If the configuration is loaded from the cache, this flag will always be set
+ *          to <code>0</code>.</p></td>
+ *    </tr>
+ *    <tr>
+ *      <td><em>size_t</em> <code>initial_size</code> </td>
+ *      <td>OUT: Initial maximum size of the cache in bytes, if applicable.<p>If the configuration is loaded
+ *        from the cache, this field will contain the cache maximum size as of the time of the
+ *          call.</p></td>
+ *    </tr>
+ *    <tr>
+ *      <td><em>double</em> <code>min_clean_fraction</code> </td>
+ *      <td>OUT: Float value specifying the minimum fraction of the cache that must be kept either clean or
+ *        empty when possible.</td>
+ *    </tr>
+ *    <tr>
+ *      <td><em>size_t</em> <code>max_size</code> </td>
+ *      <td>OUT: Upper bound (in bytes) on the range of values that the adaptive cache resize code can select
+ *        as the maximum cache size.</td>
+ *    </tr>
+ *    <tr>
+ *      <td><em>size_t</em> <code>min_size</code> </td>
+ *      <td>OUT: Lower bound (in bytes) on the range of values that the adaptive cache resize code can select
+ *        as the maximum cache size.</td>
+ *    </tr>
+ *    <tr>
+ *      <td><em>long int</em> <code>epoch_length</code> </td>
+ *      <td>OUT: Number of cache accesses between runs of the adaptive cache resize
+ *        code.</td>
+ *    </tr>
+ *  </table>
+ *
+ * \par Increment configuration section
+ *  <table>
+ *    <tr>
+ *      <td><em>enum H5C_cache_incr_mode</em> <code>incr_mode</code> </td>
+ *      <td>OUT: Enumerated value indicating the operational mode of the automatic cache size increase code. At
+ *        present, only the following values are legal:<p>\c H5C_incr__off: Automatic cache size increase is
+ *        disabled.</p><p>\c H5C_incr__threshold: Automatic cache size increase is enabled using the hit rate
+ *        threshold algorithm.</p></td>
+ *    </tr>
+ *    <tr>
+ *      <td><em>double</em> <code>lower_hr_threshold</code> </td>
+ *      <td>OUT: Hit rate threshold used in the hit rate threshold cache size increase algorithm.</td>
+ *    </tr>
+ *    <tr>
+ *      <td><em>double</em> <code>increment</code> </td>
+ *      <td>OUT: The factor by which the current maximum cache size is multiplied to obtain an initial new
+ *        maximum cache size if a size increase is triggered in the hit rate threshold cache size increase
+ *        algorithm.</td>
+ *    </tr>
+ *    <tr>
+ *      <td><em>hbool_t</em> <code>apply_max_increment</code> </td>
+ *      <td>OUT: Boolean flag indicating whether an upper limit will be applied to the size of cache size
+ *        increases.</td>
+ *    </tr>
+ *    <tr>
+ *      <td><em>size_t</em> <code>max_increment</code> </td>
+ *      <td>OUT: The maximum number of bytes by which the maximum cache size can be increased in a single step
+ *        -- if applicable.</td>
+ *    </tr>
+ *    <tr>
+ *      <td><em>enum H5C_cache_flash_incr_mode</em> <code>flash_incr_mode</code> </td>
+ *      <td>OUT: Enumerated value indicating the operational mode of the flash cache size increase code. At
+ *        present, only the following values are legal:<p>\c H5C_flash_incr__off: Flash cache size increase is
+ *        disabled.</p><p>\c H5C_flash_incr__add_space: Flash cache size increase is enabled using the add space
+ *        algorithm.</p></td>
+ *    </tr>
+ *    <tr>
+ *      <td><em>double</em> <code>flash_threshold</code> </td>
+ *      <td>OUT: The factor by which the current maximum cache size is multiplied to obtain the minimum size
+ *        entry / entry size increase which may trigger a flash cache size
+ *        increase.</td>
+ *    </tr>
+ *    <tr>
+ *      <td><em>double</em> <code>flash_multiple</code> </td>
+ *      <td>OUT: The factor by which the size of the triggering entry / entry size increase is multiplied to
+ *        obtain the initial cache size increment. This increment may be reduced to reflect existing free space
+ *        in the cache and the <code>max_size</code> field above.</td>
+ *    </tr>
+ * </table>
+ *
+ * \par Decrement configuration section
+ *  <table>
+ *    <tr><td colspan="2"><strong>Decrement configuration
+ *          section:</strong></td>
+ *    </tr>
+ *    <tr>
+ *      <td><em>enum H5C_cache_decr_mode</em> <code>decr_mode</code> </td>
+ *      <td>OUT: Enumerated value indicating the operational mode of the automatic cache size decrease code. At
+ *        present, the following values are legal:<p>H5C_decr__off: Automatic cache size decrease is disabled,
+ *        and the remaining decrement fields are ignored.</p><p>H5C_decr__threshold: Automatic cache size
+ *        decrease is enabled using the hit rate threshold algorithm.</p><p>H5C_decr__age_out: Automatic cache
+ *        size decrease is enabled using the ageout algorithm.</p><p>H5C_decr__age_out_with_threshold:
+ *        Automatic cache size decrease is enabled using the ageout with hit rate threshold
+ *          algorithm</p></td>
+ *    </tr>
+ *    <tr><td><em>double</em> <code>upper_hr_threshold</code> </td>
+ *      <td>OUT: Upper hit rate threshold. This value is only used if the decr_mode is either
+ *        H5C_decr__threshold or H5C_decr__age_out_with_threshold.</td>
+ *    </tr>
+ *    <tr>
+ *      <td><em>double</em> <code>decrement</code> </td>
+ *      <td>OUT: Factor by which the current max cache size is multiplied to obtain an initial value for the
+ *        new cache size when cache size reduction is triggered in the hit rate threshold cache size reduction
+ *        algorithm.</td>
+ *    </tr>
+ *    <tr>
+ *      <td><em>hbool_t</em> <code>apply_max_decrement</code> </td>
+ *      <td>OUT: Boolean flag indicating whether an upper limit should be applied to the size of cache size
+ *        decreases.</td>
+ *    </tr>
+ *    <tr>
+ *      <td><em>size_t</em> <code>max_decrement</code> </td>
+ *      <td>OUT: The maximum number of bytes by which cache size can be decreased if any single step, if
+ *        applicable.</td>
+ *    </tr>
+ *    <tr>
+ *      <td><em>int</em> <code>epochs_before_eviction</code> </td>
+ *      <td>OUT: The minimum number of epochs that an entry must reside unaccessed in cache before being
+ *        evicted under either of the ageout cache size reduction algorithms.</td>
+ *    </tr>
+ *    <tr>
+ *      <td><em>hbool_t</em> <code>apply_empty_reserve</code> </td>
+ *      <td>OUT: Boolean flag indicating whether an empty reserve should be maintained under either of the
+ *        ageout cache size reduction algorithms.</td>
+ *    </tr>
+ *    <tr>
+ *      <td><em>double</em> <code>empty_reserve</code> </td>
+ *      <td>OUT: Empty reserve for use with the ageout cache size reduction algorithms, if applicable.</td>
+ *    </tr>
+ *  </table>
+ *
+ * \par Parallel configuration section
+ *  <table>
+ *    <tr><td><em>int</em> <code>dirty_bytes_threshold</code> </td>
+ *      <td>OUT: Threshold number of bytes of dirty metadata generation for triggering synchronizations of the
+ *        metadata caches serving the target file in the parallel case.<p>Synchronization occurs whenever the
+ *        number of bytes of dirty metadata created since the last synchronization exceeds this limit.</p></td>
+ *    </tr>
+ *  </table>
  *
  * \since 1.8.0
  *
@@ -986,26 +1158,339 @@ H5_DLL herr_t   H5Fget_mdc_config(hid_t file_id, H5AC_cache_config_t *config_ptr
 /**
  * \ingroup MDC
  *
- * \todo Finish this!
+ * \brief Attempts to configure metadata cache of target file
+ *
+ * \file_id
+ * \param[in,out] config_ptr Pointer to the H5AC_cache_config_t instance
+ *                           containing the desired configuration.
+ *                           The fields of this structure are discussed
+ *                           \ref H5AC-cache-config-t "here".
+ * \return \herr_t
+ *
+ * \details H5Fset_mdc_config() attempts to configure the file's metadata cache
+ *          according configuration supplied in \p config_ptr.
+ *
+ * \par General configuration fields
+ *  <table>
+ *    <tr>
+ *      <td><em>int</em> <code>version</code></td>
+ *      <td>IN: Integer field indicating the the version of the H5AC_cache_config_t in use. This
+ *        field should be set to #H5AC__CURR_CACHE_CONFIG_VERSION (defined
+ *        in H5ACpublic.h).</td>
+ *    </tr>
+ *    <tr>
+ *      <td><em>hbool_t</em> <code>rpt_fcn_enabled</code></td>
+ *      <td>IN: Boolean flag indicating whether the adaptive cache resize report function is enabled. This
+ *        field should almost always be set to disabled (<code>0</code>). Since resize algorithm activity is reported
+ *        via stdout, it MUST be set to disabled (<code>0</code>) on Windows machines.<p>The report function is not
+ *          supported code, and can be expected to change between versions of the library. Use it at your own
+ *          risk.</p></td>
+ *    </tr>
+ *    <tr>
+ *      <td><em>hbool_t</em> <code>open_trace_File</code></td>
+ *      <td>IN: Boolean field indicating whether the <code>trace_file_name</code> field should be used to open
+ *        a trace file for the cache.<p>The trace file is a debuging feature that allows the capture of top level
+ *          metadata cache requests for purposes of debugging and/or optimization. This field should normally be set
+ *          to <code>0</code>, as trace file collection imposes considerable overhead.</p><p>This field should only be
+ *          set to <code>1</code> when the <code>trace_file_name</code> contains the full path of the desired trace
+ *          file, and either there is no open trace file on the cache, or the <code>close_trace_file</code> field is
+ *          also <code>1</code>.</p><p>The trace file feature is unsupported unless used at the direction of The HDF
+ *          Group. It is intended to allow The HDF Group to collect a trace of cache activity in cases of occult
+ *          failures and/or poor performance seen in the field, so as to aid in reproduction in the lab. If you use it
+ *          absent the direction of The HDF Group, you are on your
+ *          own.</p></td>
+ *    </tr>
+ *    <tr><td><em>hbool_t</em> <code>close_trace_file</code></td>
+ *      <td>IN: Boolean field indicating whether the current trace file (if any) should be closed.<p>See the
+ *          above comments on the <code>open_trace_file</code> field. This field should be set to <code>0</code> unless
+ *          there is an open trace file on the cache that you wish to close.</p><p>The trace file feature is
+ *          unsupported unless used at the direction of The HDF Group. It is intended to allow The HDF Group to collect
+ *          a trace of cache activity in cases of occult failures and/or poor performance seen in the field, so as to
+ *          aid in reproduction in the lab. If you use it absent the direction of The HDF Group, you are on your
+ *          own.</p></td>
+ *    </tr>
+ *    <tr>
+ *      <td><em>char</em> <code>trace_file_name[]</code></td>
+ *      <td>IN: Full path of the trace file to be opened if the <code>open_trace_file</code> field is set
+ *        to <code>1</code>.<p>In the parallel case, an ascii representation of the mpi rank of the process will be
+ *          appended to the file name to yield a unique trace file name for each process.</p><p>The length of the path
+ *          must not exceed #H5AC__MAX_TRACE_FILE_NAME_LEN characters.</p><p>The trace file feature is
+ *          unsupported unless used at the direction of The HDF Group. It is intended to allow The HDF Group to collect
+ *          a trace of cache activity in cases of occult failures and/or poor performance seen in the field, so as to
+ *          aid in reproduction in the lab. If you use it absent the direction of The HDF Group, you are on your
+ *          own.</p></td>
+ *    </tr>
+ *    <tr>
+ *      <td><em>hbool_t</em> <code>evictions_enabled</code></td>
+ *      <td>IN: A boolean flag indicating whether evictions from the metadata cache are enabled. This flag is
+ *        initially set to enabled (<code>1</code>).<p>In rare circumstances, the raw data throughput requirements
+ *          may be so high that the user wishes to postpone metadata writes so as to reserve I/O throughput for raw
+ *          data. The <code>evictions_enabled</code> field exists to allow this. However, this is an extreme step, and
+ *          you have no business doing it unless you have read the User Guide section on metadata caching, and have
+ *          considered all other options carefully.</p><p>The <code>evictions_enabled</code> field may not be set to
+ *          disabled (<code>0</code>) unless all adaptive cache resizing code is disabled via
+ *          the <code>incr_mode</code>, <code>flash_incr_mode</code>, and <code>decr_mode</code> fields.</p><p>When
+ *          this flag is set to disabled (<code>0</code>), the metadata cache will not attempt to evict entries to make
+ *          space for new entries, and thus will grow without bound.</p><p>Evictions will be re-enabled when this field
+ *          is set back to <code>1</code>. This should be done as soon as
+ *          possible.</p></td>
+ *    </tr>
+ *    <tr>
+ *      <td><em>hbool_t</em> <code>set_initial_size</code></td>
+ *      <td>IN: Boolean flag indicating whether the cache should be forced to the user specified initial
+ *        size.</td>
+ *    </tr>
+ *    <tr>
+ *      <td><em>size_t</em> <code>initial_size</code></td>
+ *      <td>IN: If <code>set_initial_size</code> is set to <code>1</code>, then <code>initial_size</code> must
+ *        contain the desired initial size in bytes. This value must lie in the closed interval <code>[min_size,
+ *          max_size]</code>. (see below)</td>
+ *    </tr>
+ *    <tr><td><em>double</em> <code>min_clean_fraction</code></td>
+ *      <td>IN: This field specifies the minimum fraction of the cache that must be kept either clean or
+ *        empty.<p>The value must lie in the interval [0.0, 1.0]. 0.01 is a good place to start in the serial case.
+ *          In the parallel case, a larger value is needed --
+ *          see <a href="/display/HDF5/Metadata+Caching+in+HDF5">Metadata Caching in HDF5</a> in the collection
+ *          "Advanced Topics in HDF5."</p></td>
+ *    </tr>
+ *    <tr><td><em>size_t</em> <code>max_size</code></td>
+ *      <td>IN: Upper bound (in bytes) on the range of values that the adaptive cache resize code can select as
+ *        the maximum cache size.</td>
+ *    </tr>
+ *    <tr>
+ *      <td><em>size_t</em> <code>min_size</code></td>
+ *      <td>IN: Lower bound (in bytes) on the range of values that the adaptive cache resize code can select as
+ *        the maximum cache size.</td>
+ *    </tr>
+ *    <tr><td><em>long int</em> <code>epoch_length</code></td>
+ *      <td>IN: Number of cache accesses between runs of the adaptive cache resize code. 50,000 is a good
+ *        starting number.</td>
+ *    </tr>
+ *  </table>
+ *
+ * \par Increment configuration fields
+ *  <table>
+ *    <tr>
+ *      <td><em>enum H5C_cache_incr_mode</em> <code>incr_mode</code></td>
+ *      <td>IN: Enumerated value indicating the operational mode of the automatic cache size increase code. At
+ *        present, only two values are legal:<p>\c H5C_incr__off: Automatic cache size increase is disabled, and the
+ *          remaining increment fields are ignored.</p><p>\c H5C_incr__threshold: Automatic cache size increase is enabled
+ *          using the hit rate threshold
+ *          algorithm.</p></td>
+ *    </tr>
+ *    <tr>
+ *      <td><em>double</em> <code>lower_hr_threshold</code></td>
+ *      <td>IN: Hit rate threshold used by the hit rate threshold cache size increment algorithm.<p>When the
+ *          hit rate over an epoch is below this threshold and the cache is full, the maximum size of the cache is
+ *          multiplied by increment (below), and then clipped as necessary to stay within max_size, and possibly
+ *          max_increment.</p><p>This field must lie in the interval [0.0, 1.0]. 0.8 or 0.9 is a good starting
+ *          point.</p></td>
+ *    </tr>
+ *    <tr>
+ *      <td><em>double</em> <code>increment</code></td>
+ *      <td>IN: Factor by which the hit rate threshold cache size increment algorithm multiplies the current
+ *        maximum cache size to obtain a tentative new cache size.<p>The actual cache size increase will be clipped
+ *          to satisfy the max_size specified in the general configuration, and possibly max_increment below.</p><p>The
+ *          parameter must be greater than or equal to 1.0 -- 2.0 is a reasonable value.</p><p>If you set it to 1.0,
+ *          you will effectively disable cache size
+ *          increases.</p></td>
+ *    </tr>
+ *    <tr>
+ *      <td><em>hbool_t</em> <code>apply_max_increment</code></td>
+ *      <td>IN: Boolean flag indicating whether an upper limit should be applied to the size of cache size
+ *        increases.</td>
+ *    </tr>
+ *    <tr>
+ *      <td><em>size_t</em> <code>max_increment</code></td>
+ *      <td>IN: Maximum number of bytes by which cache size can be increased in a single step -- if
+ *        applicable.</td>
+ *    </tr>
+ *    <tr>
+ *      <td><em>enum H5C_cache_flash_incr_mode</em> <code>flash_incr_mode</code></td>
+ *      <td>IN: Enumerated value indicating the operational mode of the flash cache size increase code. At
+ *        present, only the following values are legal:<p>\c H5C_flash_incr__off: Flash cache size increase is
+ *          disabled.</p><p>\c H5C_flash_incr__add_space: Flash cache size increase is enabled using the add space
+ *          algorithm.</p></td>
+ *    </tr>
+ *    <tr>
+ *      <td><em>double</em> <code>flash_threshold</code></td>
+ *      <td>IN: The factor by which the current maximum cache size is multiplied to obtain the minimum size
+ *        entry / entry size increase which may trigger a flash cache size increase.<p>At present, this value must
+ *          lie in the range [0.1, 1.0].</p></td>
+ *    </tr>
+ *    <tr>
+ *      <td><em>double</em> <code>flash_multiple</code></td>
+ *      <td>IN: The factor by which the size of the triggering entry / entry size increase is multiplied to
+ *        obtain the initial cache size increment. This increment may be reduced to reflect existing free space in
+ *        the cache and the <code>max_size</code> field above.<p>At present, this field must lie in the range [0.1,
+ *          10.0].</p></td>
+ *    </tr>
+ *  </table>
+ *
+ * \par Decrement configuration fields
+ *  <table>
+ *    <tr>
+ *      <td><em>enum H5C_cache_decr_mode</em> <code>decr_mode</code></td>
+ *      <td>IN: Enumerated value indicating the operational mode of the automatic cache size decrease code. At
+ *        present, the following values are legal:<p>\c H5C_decr__off: Automatic cache size decrease is
+ *          disabled.</p><p>\c H5C_decr__threshold: Automatic cache size decrease is enabled using the hit rate threshold
+ *          algorithm.</p><p>\c H5C_decr__age_out: Automatic cache size decrease is enabled using the ageout
+ *          algorithm.</p><p>\c H5C_decr__age_out_with_threshold: Automatic cache size decrease is enabled using the
+ *          ageout with hit rate threshold
+ *          algorithm</p></td>
+ *    </tr>
+ *    <tr>
+ *      <td><em>double</em> <code>upper_hr_threshold</code></td>
+ *      <td>IN: Hit rate threshold for the hit rate threshold and ageout with hit rate threshold cache size
+ *        decrement algorithms.<p>When \c decr_mode is \c H5C_decr__threshold, and the hit rate over a given epoch exceeds
+ *          the supplied threshold, the current maximum cache size is multiplied by decrement to obtain a tentative new
+ *          (and smaller) maximum cache size.</p><p>When \c decr_mode is \c H5C_decr__age_out_with_threshold, there is no
+ *          attempt to find and evict aged out entries unless the hit rate in the previous epoch exceeded the supplied
+ *          threshold.</p><p>This field must lie in the interval [0.0, 1.0].</p><p>For \c H5C_incr__threshold, .9995 or
+ *          .99995 is a good place to start.</p><p>For \c H5C_decr__age_out_with_threshold, .999 might be more
+ *          useful.</p></td>
+ *    </tr>
+ *    <tr>
+ *      <td><em>double</em> <code>decrement</code></td>
+ *      <td>IN: In the hit rate threshold cache size decrease algorithm, this parameter contains the factor by
+ *        which the current max cache size is multiplied to produce a tentative new cache size.<p>The actual cache
+ *          size decrease will be clipped to satisfy the min_size specified in the general configuration, and possibly
+ *          max_decrement below.</p><p>The parameter must be be in the interval [0.0, 1.0].</p><p>If you set it to 1.0,
+ *          you will effectively disable cache size decreases. 0.9 is a reasonable starting
+ *          point.</p></td>
+ *    </tr>
+ *    <tr>
+ *      <td><em>hbool_t</em> <code>apply_max_decrement</code></td>
+ *      <td>IN: Boolean flag indicating whether an upper limit should be applied to the size of cache size
+ *        decreases.</td>
+ *    </tr>
+ *    <tr>
+ *      <td><em>size_t</em> <code>max_decrement</code></td>
+ *      <td>IN: Maximum number of bytes by which the maximum cache size can be decreased in any single step --
+ *        if applicable.</td>
+ *    </tr>
+ *    <tr>
+ *      <td><em>int</em> <code>epochs_before_eviction</code></td>
+ *      <td>IN: In the ageout based cache size reduction algorithms, this field contains the minimum number of
+ *        epochs an entry must remain unaccessed in cache before the cache size reduction algorithm tries to evict
+ *        it. 3 is a reasonable value.</td>
+ *    </tr>
+ *    <tr>
+ *      <td><em>hbool_t</em> <code>apply_empty_reserve</code></td>
+ *      <td>IN: Boolean flag indicating whether the ageout based decrement algorithms will maintain a empty
+ *        reserve when decreasing cache size.</td>
+ *    </tr>
+ *    <tr>
+ *      <td><em>double</em> <code>empty_reserve</code></td>
+ *      <td>IN: Empty reserve as a fraction of maximum cache size if applicable.<p>When so directed, the ageout
+ *          based algorithms will not decrease the maximum cache size unless the empty reserve can be met.</p><p>The
+ *          parameter must lie in the interval [0.0, 1.0]. 0.1 or 0.05 is a good place to
+ *          start.</p></td>
+ *    </tr>
+ *  </table>
+ *
+ * \par Parallel configuration fields
+ *  <table>
+ *    <tr>
+ *      <td><em>int</em> <code>dirty_bytes_threshold</code></td>
+ *      <td>IN: Threshold number of bytes of dirty metadata generation for triggering synchronizations of the
+ *        metadata caches serving the target file in the parallel case.<p>Synchronization occurs whenever the number
+ *          of bytes of dirty metadata created since the last synchronization exceeds this limit.</p><p>This field only
+ *          applies to the parallel case. While it is ignored elsewhere, it can still draw a value out of bounds
+ *          error.</p><p>It must be consistant across all caches on any given file.</p><p>By default, this field is set
+ *          to 256 KB. It shouldn't be more than half the current maximum cache size times the minimum clean
+ *          fraction.</p></td>
+ *    </tr>
+ *  </table>
+ *
+ * \since 1.8.0
+ *
+ * \todo Fix the MDC document reference!
  */
 H5_DLL herr_t   H5Fset_mdc_config(hid_t file_id, H5AC_cache_config_t *config_ptr);
 /**
  * \ingroup MDC
  *
- * \todo Finish this!
+ * \brief Obtains target file's metadata cache hit rate
+ *
+ * \file_id
+ * \param[out] hit_rate_ptr Pointer to the double in which the hit rate is returned. Note that
+ *                          \p hit_rate_ptr is undefined if the API call fails
+ * \return \herr_t
+ *
+ * \details H5Fget_mdc_hit_rate() queries the metadata cache of the target file to obtain its hit rate
+ *          \Code{(cache hits / (cache hits + cache misses))} since the last time hit rate statistics
+ *          were reset. If the cache has not been accessed since the last time the hit rate stats were
+ *          reset, the hit rate is defined to be 0.0.
+ *
+ *          The hit rate stats can be reset either manually (via H5Freset_mdc_hit_rate_stats()), or
+ *          automatically. If the cache's adaptive resize code is enabled, the hit rate stats will be
+ *          reset once per epoch. If they are reset manually as well, the cache may behave oddly.
+ *
+ *          See the overview of the metadata cache in the special topics section of the user manual for
+ *          details on the metadata cache and its adaptive resize algorithms.
+ *
  */
 H5_DLL herr_t   H5Fget_mdc_hit_rate(hid_t file_id, double *hit_rate_ptr);
 /**
  * \ingroup MDC
  *
- * \todo Finish this!
+ * \brief Obtains current metadata cache size data for specified file
+ *
+ * \file_id
+ * \param[out] max_size_ptr Pointer to the location in which the current cache maximum size is to be
+ *                          returned, or NULL if this datum is not desired
+ * \param[out] min_clean_size_ptr Pointer to the location in which the current cache minimum clean
+ *                                size is to be returned, or NULL if that datum is not desired
+ * \param[out] cur_size_ptr Pointer to the location in which the current cache size is to be returned,
+ *                          or NULL if that datum is not desired
+ * \param[out] cur_num_entries_ptr Pointer to the location in which the current number of entries in
+ *                                 the cache is to be returned, or NULL if that datum is not desired
+ * \returns \herr_t
+ *
+ * \details H5Fget_mdc_size()  queries the metadata cache of the target file for the desired size
+ *          information, and returns this information in the locations indicated by the pointer
+ *          parameters. If any pointer parameter is NULL, the associated data is not returned.
+ *
+ *          If the API call fails, the values returned via the pointer parameters are undefined.
+ *
+ *          If adaptive cache resizing is enabled, the cache maximum size and minimum clean size
+ *          may change at the end of each epoch. Current size and current number of entries can
+ *          change on each cache access.
+ *
+ *          Current size can exceed maximum size under certain conditions. See the overview of the
+ *          metadata cache in the special topics section of the user manual for a discussion of this.
+ *
  */
 H5_DLL herr_t   H5Fget_mdc_size(hid_t file_id, size_t *max_size_ptr, size_t *min_clean_size_ptr,
                                 size_t *cur_size_ptr, int *cur_num_entries_ptr);
 /**
  * \ingroup MDC
  *
- * \todo Finish this!
+ * \brief Resets hit rate statistics counters for the target file
+ *
+ * \file_id
+ * \returns \herr_t
+ *
+ * \details
+ * \parblock
+ * H5Freset_mdc_hit_rate_stats() resets the hit rate statistics counters in the metadata cache
+ * associated with the specified file.
+ *
+ * If the adaptive cache resizing code is enabled, the hit rate statistics are reset at the beginning
+ * of each epoch. This API call allows you to do the same thing from your program.
+ *
+ * The adaptive cache resizing code may behave oddly if you use this call when adaptive cache resizing
+ * is enabled. However, the call should be useful if you choose to control metadata cache size from your
+ * program.
+ *
+ * See "Metadata Caching in HDF5" for details about the metadata cache and the adaptive cache resizing
+ * algorithms. If you have not read, understood, and thought about the material covered in that
+ * documentation,
+ * you should not be using this API call.
+ * \endparblock
+ *
+ * \todo Fix the MDC document reference!
  */
 H5_DLL herr_t   H5Freset_mdc_hit_rate_stats(hid_t file_id);
 /**
@@ -1500,7 +1985,32 @@ H5_DLL herr_t   H5Fget_page_buffering_stats(hid_t file_id, unsigned accesses[2],
 /**
  * \ingroup MDC
  *
- * \todo Finish this!
+ * \brief Obtains information about a cache image if it exists
+ *
+ * \file_id
+ * \param[out] image_addr Offset of the cache image if it exists, or #HADDR_UNDEF if it does not
+ * \param[out] image_size Length of the cache image if it exists, or 0 if it does not
+ * \returns \herr_t
+ *
+ * \details
+ * \parblock
+ * H5Fget_mdc_image_info() returns information about a cache image if it exists.
+ *
+ * When an HDF5 file is opened in Read/Write mode, any metadata cache image will
+ * be read and deleted from the file on the first metadata cache access (or, if
+ * persistent free space managers are enabled, on the first file space
+ * allocation / deallocation, or read of free space manager status, whichever
+ * comes first).
+ *
+ * Thus, if the file is opened Read/Write, H5Fget_mdc_image_info() should be called
+ * immediately after file open and before any other operation. If H5Fget_mdc_image_info()
+ * is called after the cache image is loaded, it will correctly report that no cache image
+ * exists, as the image will have already been read and deleted from the file. In the Read Only
+ * case, the function may be called at any time, as any cache image will not be deleted
+ * from the file.
+ * \endparblock
+ *
+ * \since 1.10.1
  */
 H5_DLL herr_t   H5Fget_mdc_image_info(hid_t file_id, haddr_t *image_addr, hsize_t *image_size);
 /**

From e3ce85e6e01294b0f65e30e9675ad1329651d4f5 Mon Sep 17 00:00:00 2001
From: Gerd Heber <gheber@hdfgroup.org>
Date: Thu, 19 Nov 2020 17:37:00 -0600
Subject: [PATCH 14/16] Added MDC and parallel H5F functions.

---
 doxygen/Doxyfile.in |  1 +
 src/H5Fpublic.h     | 82 +++++++++++++++++++++++++++++++++++++++++++--
 2 files changed, 81 insertions(+), 2 deletions(-)

diff --git a/doxygen/Doxyfile.in b/doxygen/Doxyfile.in
index 711fa7a2196..24fc4ba12e0 100644
--- a/doxygen/Doxyfile.in
+++ b/doxygen/Doxyfile.in
@@ -854,6 +854,7 @@ INPUT_ENCODING         = UTF-8
 
 FILE_PATTERNS          = H5*public.h \
                          H5*module.h \
+                         H5FDmpio.h \
                          H5VLconnector.h \
                          H5VLconnector_passthru.h \
                          H5VLnative.h \
diff --git a/src/H5Fpublic.h b/src/H5Fpublic.h
index bfe2b57c6da..82895a8dd89 100644
--- a/src/H5Fpublic.h
+++ b/src/H5Fpublic.h
@@ -2072,13 +2072,91 @@ H5_DLL herr_t   H5Fset_dset_no_attrs_hint(hid_t file_id, hbool_t minimize);
 /**
  * \ingroup PH5F
  *
- * \todo Finish this!
+ * \brief Sets the MPI atomicity mode
+ *
+ * \file_id
+ * \param[in] flag Logical flag for atomicity setting. Valid values are:
+ *                 \li \c 1 -- Sets MPI file access to atomic mode.
+ *                 \li \c 0 -- Sets MPI file access to nonatomic mode.
+ * \returns \herr_t
+ *
+ * \par Motivation
+ * H5Fset_mpi_atomicity() is applicable only in parallel environments using MPI I/O.
+ * The function is one of the tools used to ensure sequential consistency. This means
+ * that a set of operations will behave as though they were performed in a serial
+ * order consistent with the program order.
+ *
+ * \details
+ * \parblock
+ * H5Fset_mpi_atomicity() sets MPI consistency semantics for data access to the file,
+ * \p file_id.
+ *
+ * If \p flag is set to \c 1, all file access operations will appear atomic, guaranteeing
+ * sequential consistency. If \p flag is set to \c 0, enforcement of atomic file access
+ * will be turned off.
+ *
+ * H5Fset_mpi_atomicity() is a collective function and all participating processes must
+ * pass the same values for \p file_id and \p flag.
+ *
+ * This function is available only when the HDF5 library is configured with parallel support
+ * (\Code{--enable-parallel}). It is useful only when used with the #H5FD_MPIO driver
+ * (see H5Pset_fapl_mpio()).
+ * \endparblock
+ *
+ * \attention
+ * \parblock
+ * H5Fset_mpi_atomicity() calls \Code{MPI_File_set_atomicity} underneath and is not supported
+ * if the execution platform does not support \Code{MPI_File_set_atomicity}. When it is
+ * supported and used, the performance of data access operations may drop significantly.
+ *
+ * In certain scenarios, even when \Code{MPI_File_set_atomicity} is supported, setting
+ * atomicity with H5Fset_mpi_atomicity() and \p flag set to 1 does not always yield
+ * strictly atomic updates. For example, some H5Dwrite() calls translate to multiple
+ * \Code{MPI_File_write_at} calls. This happens in all cases where the high-level file
+ * access routine translates to multiple lower level file access routines.
+ * The following scenarios will raise this issue:
+ * \li Non-contiguous file access using independent I/O
+ * \li Partial collective I/O using chunked access
+ * \li Collective I/O using filters or when data conversion is required
+ *
+ * This issue arises because MPI atomicity is a matter of MPI file access operations rather
+ * than HDF5 access operations. But the user is normally seeking atomicity at the HDF5 level.
+ * To accomplish this, the application must set a barrier after a write, H5Dwrite(), but before
+ * the next read, H5Dread(), in addition to calling H5Fset_mpi_atomicity().The barrier will
+ * guarantee that all underlying write operations execute atomically before the read
+ * operations starts. This ensures additional ordering semantics and will normally produce
+ * the desired behavior.
+ * \endparblock
+ *
+ * \see Enabling a Strict Consistency Semantics Model in Parallel HDF5
+ *
+ * \since 1.8.9
+ *
+ * \todo Fix the reference!
  */
 H5_DLL herr_t H5Fset_mpi_atomicity(hid_t file_id, hbool_t flag);
 /**
  * \ingroup PH5F
  *
- * \todo Finish this!
+ * \brief Retrieves the atomicity mode in use
+ *
+ * \file_id
+ * \param[out] flag Logical flag for atomicity setting. Valid values are:
+ *                  \li 1 -- MPI file access is set to atomic mode.
+ *                  \li 0 -- MPI file access is set to nonatomic mode.
+ * \returns \herr_t
+ *
+ * \details H5Fget_mpi_atomicity() retrieves the current consistency semantics mode for
+ *          data access for the file \p file_id.
+ *
+ *          Upon successful return, \p flag will be set to \c 1 if file access is set
+ *          to atomic mode and \c 0 if file access is set to nonatomic mode.
+ *
+ * \see Enabling a Strict Consistency Semantics Model in Parallel HDF5
+ *
+ * \since 1.8.9
+ *
+ * \todo Fix the reference!
  */
 H5_DLL herr_t H5Fget_mpi_atomicity(hid_t file_id, hbool_t *flag);
 #endif /* H5_HAVE_PARALLEL */

From 2b6e6ece7bfd8b2023618d37d7a1f2819cd44075 Mon Sep 17 00:00:00 2001
From: Gerd Heber <gheber@hdfgroup.org>
Date: Thu, 19 Nov 2020 17:38:02 -0600
Subject: [PATCH 15/16] Slightly updated main page.

---
 doxygen/dox/mainpage.dox | 70 ++++++++++++++++++++++------------------
 1 file changed, 39 insertions(+), 31 deletions(-)

diff --git a/doxygen/dox/mainpage.dox b/doxygen/dox/mainpage.dox
index 83fc323de0c..eda967b421b 100644
--- a/doxygen/dox/mainpage.dox
+++ b/doxygen/dox/mainpage.dox
@@ -1,36 +1,44 @@
-/*! \mainpage API Documentation for HDF5 Version 1.13 (Draft)
+/*! \mainpage HDF5 C-API Reference
+ *
+ * The HDF5 C-API provides applications with fine-grained control over all
+ * aspects HDF5 functionality. This functionality is grouped into the following
+ * \Emph{modules}:
+ * \li \ref H5A "Attributes" — Management of HDF5 attributes (\ref H5A)
+ * \li \ref H5D "Datasets" — Management of HDF5 datasets (\ref H5D)
+ * \li \ref H5S "Dataspaces" — Management of HDF5 dataspaces which describe the shape of datasets and attributes (\ref H5S)
+ * \li \ref H5T "Datatypes" — Management of datatypes which describe elements of datasets and attributes (\ref H5T)
+ * \li \ref H5E "Error Handling" — Functions for handling errors that occur within HDF5 (\ref H5E)
+ * \li \ref H5F "Files" — Management of HDF5 files (\ref H5F)
+ * \li \ref H5Z "Filters" — Configuration of filters that process data during I/O operation (\ref H5Z)
+ * \li \ref H5G "Groups" — Management of groups in HDF5 files (\ref H5G)
+ * \li \ref H5I "Identifiers" — Management of object identifiers and object names (\ref H5I)
+ * \li \ref H5 "Library" — General purpose library functions (\ref H5)
+ * \li \ref H5L "Links" — Management of links in HDF5 groups (\ref H5L)
+ * \li \ref H5O "Objects" — Management of objects in HDF5 files (\ref H5O)
+ * \li \ref H5PL "Plugins" — Programmatic control over dynamically loaded plugins (\ref H5PL)
+ * \li \ref H5P "Property Lists" — Management of property lists to control HDF5 library behavior (\ref H5P)
+ * \li \ref H5R "References" — Management of references to specific objects and data regions in an HDF5 file (\ref H5R)
+ * \li \ref H5VL "Virtual Object Layer" — Management of the Virtual Object Layer (\ref H5VL)
+ *
+ * Here are a few simple rules to follow:
+ *
+ * \li \Bold{Handle discipline:} If you acquire a handle (by creation or coopy), \Emph{you own it!} (..., i.e., you have to close it.)
+ * \li \Bold{Dynamic memory allocation:} ...
+ * \li \Bold{Use of locations:} Identifier + name combo
+ *
+ * \attention \Bold{C++ Developers using HDF5 C-API functions beware:}\n
+ *       If a C routine that takes a function pointer as an argument is called from
+ *       within C++ code, the C routine should be returned from normally.
+ *       Examples of this kind of routine include callbacks such as H5Pset_elink_cb()
+ *       and H5Pset_type_conv_cb() and functions such as H5Tconvert() and H5Ewalk2().\n
+ *       Exiting the routine in its normal fashion allows the HDF5 C library to clean
+ *       up its work properly. In other words, if the C++ application jumps out of
+ *       the routine back to the C++ \c catch statement, the library is not given the
+ *       opportunity to close any temporary data structures that were set up when the
+ *       routine was called. The C++ application should save some state as the
+ *       routine is started so that any problem that occurs might be diagnosed.
  *
  * \todo Fix the search form for server deployments.
  * \todo Make it mobile-friendly
  *
- * \section intro_sec Introduction
- *
- * \todo Write an introduction.
- *
- * \section quick_links Quick Links
- *
- * <ul>
- * <li>\ref PDT "Predefined Datatypes"</li>
- * <li>\ref api-compat-macros "API Compatibility Macros"</li>
- * <li><a href="https://hdf5.wiki/">HDF5 Wiki</a></li>
- * </ul>
- *
- * \section using_locations The Use of Locations (Identifier + Name) in the HDF5 API
- *
- * \todo Make this crystal clear!
- *
- * \section cpp_note Programming Note for C++ Developers Using C Functions
- *
- * If a C routine that takes a function pointer as an argument is called from
- * within C++ code, the C routine should be returned from normally.
- *
- * Examples of this kind of routine include callbacks such as H5Pset_elink_cb()
- * and H5Pset_type_conv_cb() and functions such as H5Tconvert() and H5Ewalk2().
- *
- * Exiting the routine in its normal fashion allows the HDF5 C library to clean
- * up its work properly. In other words, if the C++ application jumps out of
- * the routine back to the C++ \c catch statement, the library is not given the
- * opportunity to close any temporary data structures that were set up when the
- * routine was called. The C++ application should save some state as the
- * routine is started so that any problem that occurs might be diagnosed.
  */
\ No newline at end of file

From 097ad530ed49b09d34f99d6ae77e13deb7169fa8 Mon Sep 17 00:00:00 2001
From: Gerd Heber <gheber@hdfgroup.org>
Date: Fri, 20 Nov 2020 06:59:19 -0600
Subject: [PATCH 16/16] Added doxygen/dox/H5AC_cache_config_t.dox to MANIFEST.

---
 MANIFEST | 1 +
 1 file changed, 1 insertion(+)

diff --git a/MANIFEST b/MANIFEST
index 28b6826a815..f6094e9de5c 100644
--- a/MANIFEST
+++ b/MANIFEST
@@ -197,6 +197,7 @@
 ./doxygen/aliases
 ./doxygen/Doxyfile.in
 ./doxygen/dox/api-compat-macros.dox
+./doxygen/dox/H5AC_cache_config_t.dox
 ./doxygen/dox/H5Acreate.dox
 ./doxygen/dox/H5Aiterate.dox
 ./doxygen/dox/H5Fget_info.dox