1.10 Merge A batch of life-cycle examples for different modules #654 (#988)

* Merge A batch of life-cycle examples for different modules #654

* Change doxygen generated file location

28 files changed, 1198 insertions, 1069 deletions

diff --git a/src/CMakeLists.txt b/src/CMakeLists.txt
index fbde308..aaff5e4 100644
--- a/src/CMakeLists.txt
+++ b/src/CMakeLists.txt
@@ -1325,15 +1325,17 @@ if (DOXYGEN_FOUND)
   set (DOXYGEN_OPTIMIZE_OUTPUT_FOR_C YES)
   set (DOXYGEN_MACRO_EXPANSION YES)
   set (DOXYGEN_OUTPUT_DIRECTORY ${HDF5_BINARY_DIR}/hdf5lib_docs)
-  set (DOXYGEN_EXAMPLES_DIRECTORY "${HDF5_DOXYGEN_DIR}/examples ${HDF5_SRC_DIR} ${HDF5_SOURCE_DIR}/examples ${HDF5_TEST_SRC_DIR}")
+  set (DOXYGEN_EXAMPLES_DIRECTORY "${HDF5_DOXYGEN_DIR}/dox/cookbook ${HDF5_DOXYGEN_DIR}/examples ${HDF5_SRC_DIR} ${HDF5_SOURCE_DIR}/examples ${HDF5_TEST_SRC_DIR}")
   set (DOXYGEN_LAYOUT_FILE ${HDF5_DOXYGEN_DIR}/hdf5doxy_layout.xml)
   set (DOXYGEN_HTML_HEADER ${HDF5_DOXYGEN_DIR}/hdf5_header.html)
   set (DOXYGEN_HTML_FOOTER ${HDF5_DOXYGEN_DIR}/hdf5_footer.html)
   set (DOXYGEN_HTML_EXTRA_STYLESHEET ${HDF5_DOXYGEN_DIR}/hdf5doxy.css)
   set (DOXYGEN_HTML_EXTRA_FILES "${HDF5_DOXYGEN_DIR}/hdf5_navtree_hacks.js ${HDF5_DOXYGEN_DIR}/img/ftv2node.png ${HDF5_DOXYGEN_DIR}/img/ftv2pnode.png")
+  set (DOXYGEN_TAG_FILE ${HDF5_BINARY_DIR}/hdf5.tag)
   set (DOXYGEN_SERVER_BASED_SEARCH NO)
   set (DOXYGEN_EXTERNAL_SEARCH NO)
   set (DOXYGEN_SEARCHENGINE_URL)
+  set (DOXYGEN_PREDEFINED H5_HAVE_DIRECT H5_HAVE_LIBHDFS H5_HAVE_MAP_API H5_HAVE_PARALLEL H5_HAVE_ROS3_VFD)
 
 # This configure and custom target work together
   # Replace variables inside @@ with the current values
diff --git a/src/H5Amodule.h b/src/H5Amodule.h
index c89c93f..9f86ddd 100644
--- a/src/H5Amodule.h
+++ b/src/H5Amodule.h
@@ -33,33 +33,29 @@
  *
  * Use the functions in this module to manage HDF5 attributes.
  *
- * The Attribute Interface, H5A, provides a mechanism for attaching additional
- * information to a dataset, group, or named datatype.
- *
- * Attributes are accessed by opening the object that they are attached to and
- * are not independent objects. Typically an attribute is small in size and
- * contains user metadata about the object that it is attached to.
- *
- * Attributes look similar to HDF5 datasets in that they have a datatype and
- * dataspace. However, they do not support partial I/O operations and cannot be
- * compressed or extended.
+ * Like HDF5 datasets, HDF5 attributes are array variables which have an element
+ * datatype and a shape (dataspace). However, they perform a different function:
+ * Attributes decorate other HDF5 objects, and are typically used to
+ * represent application metadata. Unlike datasets, the HDF5 library does not
+ * support partial I/O operations for attributes and they cannot be compressed
+ * or extended.
  *
  * <table>
  * <tr><th>Create</th><th>Read</th></tr>
  * <tr valign="top">
  *   <td>
- *   \snippet H5A_examples.c create
+ *   \snippet{lineno} H5A_examples.c create
  *   </td>
  *   <td>
- *   \snippet H5A_examples.c read
+ *   \snippet{lineno} H5A_examples.c read
  *   </td>
  * <tr><th>Update</th><th>Delete</th></tr>
  * <tr valign="top">
  *   <td>
- *   \snippet H5A_examples.c update
+ *   \snippet{lineno} H5A_examples.c update
  *   </td>
  *   <td>
- *   \snippet H5A_examples.c delete
+ *   \snippet{lineno} H5A_examples.c delete
  *   </td>
  * </tr>
  * </table>
diff --git a/src/H5Apublic.h b/src/H5Apublic.h
index 0198668..410eb1e 100644
--- a/src/H5Apublic.h
+++ b/src/H5Apublic.h
@@ -78,11 +78,11 @@ extern "C" {
  *
  * \return \herr_t
  *
- * \details H5Aclose() terminates access to the attribute specified by
- *          \p attr_id by releasing the identifier.
+ * \details H5Aclose() terminates access to the attribute through
+ *          \p attr_id and releases the identifier.
  *
- * \attention Further use of a released attribute identifier is illegal; a
- *            function using such an identifier will generate an error.
+ * \par Example
+ * \snippet H5A_examples.c create
  *
  * \since 1.0.0
  *
@@ -110,27 +110,19 @@ H5_DLL herr_t H5Aclose(hid_t attr_id);
  *          The attribute name, \p attr_name, must be unique for the object.
  *
  *          The attribute is created with the specified datatype and dataspace,
- *          \p type_id and \p space_id, which are created with the H5T and
- *          H5S interfaces, respectively.
+ *          \p type_id and \p space_id.
  *
- *          If \p type_id is either a fixed-length or variable-length string,
- *          it is important to set the string length when defining the
- *          datatype. String datatypes are derived from #H5T_C_S1 (or
- *          #H5T_FORTRAN_S1 for Fortran), which defaults to 1 character in
- *          size. See H5Tset_size() and Creating variable-length string
- *          datatypes.
- *
- *          The access property list is currently unused, but will be used in
- *          the future. This property list should currently be #H5P_DEFAULT.
+ *          \plist_unused{acpl}
  *
  *          The attribute identifier returned by this function must be released
  *          with H5Aclose() resource leaks will develop.
  *
- * \note The \p aapl parameter is currently not used; specify #H5P_DEFAULT.
- *
  * \note If \p loc_id is a file identifier, the attribute will be attached
  *       that file’s root group.
  *
+ * \par Example
+ * \snippet H5A_examples.c create
+ *
  * \since 1.8.0
  *
  * \see H5Aclose()
@@ -160,28 +152,19 @@ H5_DLL hid_t H5Acreate2(hid_t loc_id, const char *attr_name, hid_t type_id, hid_
  *          attached to the object specified by \p loc_id and \p obj_name.
  *
  *          \p loc_id is a location identifier; \p obj_name is the object
- *          name relative to \p loc_id. If \p loc_id fully specifies the
- *          object to which the attribute is to be attached, \p obj_name
- *          should be '.' (a dot).
+ *          name relative to \p loc_id.
  *
  *          The attribute name, \p attr_name, must be unique for the object.
  *
  *          The attribute is created with the specified datatype and
- *          dataspace, \p type_id and \p space_id, which are created with
- *          the H5T and H5S interfaces respectively.
+ *          dataspace, \p type_id and \p space_id.
  *
- *          The attribute creation and access property lists are currently
- *          unused, but will be used in the future for optional attribute
- *          creation and access properties. These property lists should
- *          currently be #H5P_DEFAULT.
+ *          \plist_unused{aapl}
  *
  *          The link access property list, \p lapl_id, may provide
  *          information regarding the properties of links required to access
  *          the object, \p obj_name.
  *
- *          The attribute identifier returned by this function must be
- *          released with H5close() or resource leaks will develop.
- *
  * \since 1.8.0
  *
  */
@@ -200,10 +183,14 @@ H5_DLL hid_t H5Acreate_by_name(hid_t loc_id, const char *obj_name, const char *a
  *
  * \details H5Adelete() removes the attribute specified by its name,
  *          \p attr_name, from a file, dataset, group, or named datatype.
- *          This function should not be used when attribute identifiers
- *          are open on \p loc_id as it may cause the internal indexes of
- *          the attributes to change and future writes to the open
- *          attributes to produce incorrect results.
+ *
+ * \attention This function should not be used when other attribute identifiers
+ *            are open on \p loc_id. This may cause the internal indexes of
+ *            the attributes to change and future writes to the open
+ *            attributes to produce incorrect results.
+ *
+ * \par Example
+ * \snippet H5A_examples.c delete
  *
  * \since 1.0.0
  *
@@ -230,27 +217,16 @@ H5_DLL herr_t H5Adelete(hid_t loc_id, const char *attr_name);
  *
  *          The object from which the attribute is to be removed is
  *          specified by a location identifier and name, \p loc_id and
- *          \p obj_name, respectively. If \p loc_id fully specifies the
- *          object from which the attribute is to be removed, \p obj_name
- *          should be '.' (a dot).
+ *          \p obj_name, respectively.
  *
  *          The attribute to be removed is specified by a position in an
- *          index, \p n. The type of index is specified by \p idx_type and
- *          may be #H5_INDEX_NAME, for an alpha-numeric index by name, or
- *          #H5_INDEX_CRT_ORDER, for an index by creation order. The order
- *          in which the index is to be traversed is specified by \p order
- *          and may be #H5_ITER_INC (increment) for top-down iteration,
- *          #H5_ITER_DEC (decrement) for bottom-up iteration, or
- *          #H5_ITER_NATIVE, in which case HDF5 will iterate in the
- *          fastest-available order. For example, if \p idx_type, \p order,
+ *          index, \p n. The type of index is specified by \p idx_type.
+ *          The order in which the index is to be traversed is specified by
+ *          \p order. For example, if \p idx_type, \p order,
  *          and \p n are set to #H5_INDEX_NAME, #H5_ITER_INC, and 5,
- *          respectively, the fifth attribute by alpha-numeric order of
+ *          respectively, the fifth attribute in lexicographic order of
  *          attribute names will be removed.
  *
- *          For a discussion of \p idx_type and \p order, the valid values
- *          of those parameters, and the use of \p n, see the description
- *          of H5Aiterate2().
- *
  *          The link access property list, \p lapl_id, may provide
  *          information regarding the properties of links required to access
  *          the object, \p obj_name.
@@ -278,9 +254,6 @@ H5_DLL herr_t H5Adelete_by_idx(hid_t loc_id, const char *obj_name, H5_index_t id
  *          from an object specified by location and name, \p loc_id and
  *          \p obj_name, respectively.
  *
- *          If \p loc_id fully specifies the object from which the
- *          attribute is to be removed, \p obj_name should be '.' (a dot).
- *
  *          The link access property list, \p lapl_id, may provide
  *          information regarding the properties of links required to
  *          access the object, \p obj_name.
@@ -329,9 +302,7 @@ H5_DLL htri_t H5Aexists(hid_t obj_id, const char *attr_name);
  *          \p loc_id specifies a location in the file containing the object.
  *          \p obj_name is the name of the object to which the attribute is
  *          attached and can be a relative name, relative to \p loc_id,
- *          or an absolute name, based in the root group of the file. If
- *          \p loc_id fully specifies the object, \p obj_name should be '.'
- *          (a dot).
+ *          or an absolute name, based in the root group of the file.
  *
  *          The link access property list, \p lapl_id, may provide
  *          information regarding the properties of links required to access
@@ -355,9 +326,6 @@ H5_DLL htri_t H5Aexists_by_name(hid_t obj_id, const char *obj_name, const char *
  *          creation property list associated with the attribute specified
  *          by \p attr_id.
  *
- *          The creation property list identifier should be released with
- *          H5Pclose().
- *
  * \since 1.8.0
  *
  */
@@ -374,32 +342,9 @@ H5_DLL hid_t H5Aget_create_plist(hid_t attr_id);
  * \return \herr_t
  *
  * \details H5Aget_info() retrieves attribute information, locating the
- *          attribute with an attribute identifier, \p attr_id, which is
- *          the identifier returned by H5Aopen() or H5Aopen_by_idx(). The
+ *          attribute with an attribute identifier, \p attr_id. The
  *          attribute information is returned in the \p ainfo struct.
  *
- *          The \p ainfo struct is defined as follows:
- *          \snippet this H5A_info_t_snip
- *
- *          \p corder_valid indicates whether the creation order data is
- *          valid for this attribute. Note that if creation order is not
- *          being tracked, no creation order data will be valid. Valid
- *          values are \c TRUE and \c FALSE.
- *
- *          \p corder is a positive integer containing the creation
- *          order of the attribute. This value is 0-based, so, for
- *          example, the third attribute created will have a \p corder
- *          value of 2.
- *
- *          \p cset indicates the character set used for the attribute’s
- *          name; valid values are defined in H5Tpublic.h and include
- *          the following:
- *          \csets
- *          This value is set with H5Pset_char_encoding().
- *
- *          \p data_size indicates the size, in the number of characters,
- *          of the attribute.
- *
  * \since 1.8.0
  *
  */
@@ -427,16 +372,9 @@ H5_DLL herr_t H5Aget_info(hid_t attr_id, H5A_info_t *ainfo /*out*/);
  *          The attribute is located by its index position and the attribute
  *          information is returned in the \p ainfo struct.
  *
- *          If \p loc_id fully specifies the object to which the attribute
- *          is attached, \p obj_name should be '.' (a dot).
- *
  *          The attribute is located by means of an index type, an index
  *          traversal order, and a position in the index, \p idx_type,
- *          \p order and \p n, respectively. These parameters and their
- *          valid values are discussed in the description of H5Aiterate2().
- *
- *          The \p ainfo struct, which will contain the returned attribute
- *          information, is described in H5Aget_info().
+ *          \p order and \p n, respectively.
  *
  *          The link access property list, \p lapl_id, may provide
  *          information regarding the properties of links required to access
@@ -454,8 +392,7 @@ H5_DLL herr_t H5Aget_info_by_idx(hid_t loc_id, const char *obj_name, H5_index_t
  * \brief Retrieves attribute information, by attribute name
  *
  * \fgdt_loc_id
- *
- * \param[in] obj_name   Name of object to which attribute is attached,
+ * \param[in] obj_name   Name of the object to which an attribute is attached,
  *                       relative to location
  * \param[in] attr_name  Attribute name
  * \param[out] ainfo     Struct containing returned attribute information
@@ -468,11 +405,6 @@ H5_DLL herr_t H5Aget_info_by_idx(hid_t loc_id, const char *obj_name, H5_index_t
  *          location and name, \p loc_id and \p obj_name, respectively.
  *          The attribute information is returned in the \p ainfo struct.
  *
- *          If \p loc_id fully specifies the object to which the attribute
- *          is attached, \p obj_name should be '.' (a dot).
- *
- *          The \p ainfo struct is described in H5Aget_info().
- *
  *          The link access property list, \p lapl_id, may provide
  *          information regarding the properties of links required to
  *          access the object, \p obj_name.
@@ -503,8 +435,8 @@ H5_DLL herr_t H5Aget_info_by_name(hid_t loc_id, const char *obj_name, const char
  *          string terminator is stored in the last position of the buffer
  *          to properly terminate the string.
  *
- *          If the user only wants to find out the size of this name, the
- *          values 0 and NULL can be passed in for the parameters
+ *          If the user only wants to retrieve the name length, the
+ *          values 0 and NULL should be passed for the parameters
  *          \p bufsize and \p buf.
  *
  * \since 1.0.0
@@ -515,7 +447,7 @@ H5_DLL ssize_t H5Aget_name(hid_t attr_id, size_t buf_size, char *buf);
 /**
  * \ingroup H5A
  *
- * \brief Gets an attribute name, by attribute index position
+ * \brief Gets an attribute name by attribute index position
  *
  * \fgdt_loc_id
  * \param[in]  obj_name   Name of object to which attribute is attached,
@@ -536,13 +468,9 @@ H5_DLL ssize_t H5Aget_name(hid_t attr_id, size_t buf_size, char *buf);
  *          located by its index position, the size of the name is specified
  *          in \p size, and the attribute name is returned in \p name.
  *
- *          If \p loc_id fully specifies the object to which the attribute
- *          is attached, \p obj_name should be '.' (a dot).
- *
  *          The attribute is located by means of an index type, an index
  *          traversal order, and a position in the index, \p idx_type,
- *          \p order and \p n, respectively. These parameters and their
- *          valid values are discussed in the description of H5Aiterate2().
+ *          \p order and \p n, respectively.
  *
  *          If the attribute name’s size is unknown, the values 0 and NULL
  *          can be passed in for the parameters \p size and \p name. The
@@ -582,7 +510,7 @@ H5_DLL hid_t H5Aget_space(hid_t attr_id);
 /**
  * \ingroup H5A
  *
- * \brief Returns the amount of storage required for an attribute
+ * \brief Returns the amount of storage used to store an attribute
  *
  * \attr_id
  *
@@ -600,17 +528,16 @@ H5_DLL hsize_t H5Aget_storage_size(hid_t attr_id);
 /**
  * \ingroup H5A
  *
- * \brief Gets an attribute datatype
+ * \brief Gets an attribute's datatype
  *
  * \attr_id
  *
  * \return \hid_t{datatype}
  *
- * \details H5Aget_type() retrieves a copy of the datatype for an attribute.
+ * \details H5Aget_type() retrieves a copy of the attribute's datatype.
  *          The datatype is reopened if it is a named type before returning
  *          it to the application. The datatypes returned by this function
- *          are always read-only. If an error occurs when atomizing the
- *          return datatype, then the datatype is closed.
+ *          are always read-only.
  *
  *          The datatype identifier returned from this function must be
  *          released with H5Tclose() or resource leaks will develop.
@@ -623,7 +550,7 @@ H5_DLL hid_t H5Aget_type(hid_t attr_id);
 /**
  * \ingroup H5A
  *
- * \brief Calls user-defined function for each attribute on an object
+ * \brief Calls a user-defined function for each attribute on an object
  *
  * \fgdt_loc_id
  * \param[in]     idx_type Type of index
@@ -650,17 +577,6 @@ H5_DLL hid_t H5Aget_type(hid_t attr_id);
  *          are specified by three parameters: the index type,
  *          \p idx_type; the order in which the index is to be traversed,
  *          \p order; and the attribute’s position in the index, \p idx.
- *
- *          The type of index specified by \p idx_type can be one of the
- *          following:
- *
- *          \indexes
- *
- *          The order in which the index is to be traversed, as specified
- *          by \p order, can be one of the following:
- *
- *          \orders
- *
  *          The next attribute to be operated on is specified by \p idx,
  *          a position in the index.
  *
@@ -677,11 +593,6 @@ H5_DLL hid_t H5Aget_type(hid_t attr_id);
  *          the value returned identifies the parameter to be operated on
  *          in the next step of the iteration.
  *
- *          \p op is a user-defined function whose prototype is defined
- *          as follows:
- *          \snippet this H5A_operator2_t_snip
- *          \click4more
- *
  * \note This function is also available through the H5Aiterate() macro.
  *
  * \since 1.8.0
@@ -717,24 +628,10 @@ H5_DLL herr_t H5Aiterate2(hid_t loc_id, H5_index_t idx_type, H5_iter_order_t ord
  *          additional information as defined below, is passed to a
  *          user-defined function, \p op, which operates on that attribute.
  *
- *          If \p loc_id fully specifies the object to which these
- *          attributes are attached, \p obj_name should be '.' (a dot).
- *
  *          The order of the iteration and the attributes iterated over
  *          are specified by three parameters: the index type, \p idx_type;
  *          the order in which the index is to be traversed, \p order;
  *          and the attribute’s position in the index, \p idx.
- *
- *          The type of index specified by \p idx_type can be one of the
- *          following:
- *
- *          \indexes
- *
- *          The order in which the index is to be traversed, as specified
- *          by \p order, can be one of the following:
- *
- *          \orders
- *
  *          The next attribute to be operated on is specified by \p idx,
  *          a position in the index.
  *
@@ -751,25 +648,6 @@ H5_DLL herr_t H5Aiterate2(hid_t loc_id, H5_index_t idx_type, H5_iter_order_t ord
  *          the value returned identifies the parameter to be operated on in
  *          the next step of the iteration.
  *
- *          \p op is a user-defined function whose prototype is defined
- *          as follows:
- *          \snippet this H5A_operator2_t_snip
- *          \click4more
- *
- *          Valid return values from an operator and the resulting
- *          H5Aiterate_by_name() and \p op behavior are as follows:
- *
- *          \li Zero causes the iterator to continue, returning zero when
- *              all attributes have been processed.
- *          \li A positive value causes the iterator to immediately return
- *              that positive value, indicating short-circuit success.
- *              The iterator can be restarted at the next attribute, as
- *              indicated by the return value of \p idx.
- *          \li A negative value causes the iterator to immediately return
- *              that value, indicating failure. The iterator can be
- *              restarted at the next attribute, as indicated by the return
- *              value of \p idx.
- *
  *          The link access property list, \p lapl_id, may provide
  *          information regarding the properties of links required to access
  *          the object, \p obj_name.
@@ -796,8 +674,7 @@ H5_DLL herr_t H5Aiterate_by_name(hid_t loc_id, const char *obj_name, H5_index_t
  * \details H5Aopen() opens an existing attribute, \p attr_name, that is
  *          attached to object specified by an object identifier, \p obj_id.
  *
- *          The attribute access property list, \p aapl_id, is currently unused
- *          and should be #H5P_DEFAULT.
+ *          \plist_unused{aapl_id}
  *
  *          This function, H5Aopen_by_idx() or H5Aopen_by_name() must be called
  *          before the attribute can be accessed for any further purpose,
@@ -806,6 +683,9 @@ H5_DLL herr_t H5Aiterate_by_name(hid_t loc_id, const char *obj_name, H5_index_t
  *          The attribute identifier returned by this function must be released
  *          with H5Aclose() or resource leaks will develop.
  *
+ * \par Example
+ * \snippet H5A_examples.c read
+ *
  * \since 1.8.0
  *
  * \see H5Aclose(), H5Acreate()
@@ -830,17 +710,13 @@ H5_DLL hid_t H5Aopen(hid_t obj_id, const char *attr_name, hid_t aapl_id);
  *
  * \details H5Aopen_by_idx() opens an existing attribute that is attached
  *          to an object specified by location and name, \p loc_id and
- *          \p obj_name, respectively. If \p loc_id fully specifies the
- *          object to which the attribute is attached, \p obj_name, should
- *          be  '.'  (a dot).
+ *          \p obj_name, respectively.
  *
  *          The attribute is identified by an index type, an index traversal
  *          order, and a position in the index, \p idx_type, \p order and
- *          \p n, respectively. These parameters and their valid values are
- *          discussed in the description of H5Aiterate2().
+ *          \p n, respectively.
  *
- *          The attribute access property list, \p aapl_id, is currently
- *          unused and should currently be #H5P_DEFAULT.
+ *          \plist_unused{aapl_id}
  *
  *          The link access property list, \p lapl_id, may provide
  *          information regarding the properties of links required to access
@@ -879,11 +755,9 @@ H5_DLL hid_t H5Aopen_by_idx(hid_t loc_id, const char *obj_name, H5_index_t idx_t
  *
  *          \p loc_id specifies a location from which the target object can
  *          be located and \p obj_name is an object name relative to
- *          \p loc_id. If \p loc_id fully specifies the object to which the
- *          attribute is attached, \p obj_name should be '.' (a dot).
+ *          \p loc_id.
  *
- *          The attribute access property list, \p aapl_id, is currently
- *          unused and should currently be #H5P_DEFAULT.
+ *          \plist_unused{aapl_id}
  *
  *          The link access property list, \p lapl_id, may provide
  *          information regarding the properties of links required to access
@@ -920,6 +794,9 @@ H5_DLL hid_t H5Aopen_by_name(hid_t loc_id, const char *obj_name, const char *att
  *          Datatype conversion takes place at the time of a read or write and
  *          is automatic.
  *
+ * \par Example
+ * \snippet H5A_examples.c read
+ *
  * \version 1.8.8  Fortran updated to Fortran2003.
  * \version 1.4.2  The \p dims parameter was added to the Fortran API in this
  *                 release.
@@ -967,15 +844,12 @@ H5_DLL herr_t H5Arename(hid_t loc_id, const char *old_name, const char *new_name
  *          attribute's in-memory datatype is specified with \p type_id.
  *          The entire attribute is written from \p buf to the file.
  *
- *          If \p type_id is either a fixed-length or variable-length string,
- *          it is important to set the string length when defining the datatype.
- *          String datatypes are derived from #H5T_C_S1 (or #H5T_FORTRAN_S1 for
- *          Fortran codes), which defaults to 1 character in size.
- *          See H5Tset_size() and Creating variable-length string datatypes.
- *
  *          Datatype conversion takes place at the time of a read or write and
  *          is automatic.
  *
+ * \par Example
+ * \snippet H5A_examples.c update
+ *
  * \version 1.8.8   Fortran updated to Fortran2003.
  * \version 1.4.2   Fortran \p dims parameter added in this release
  * \since 1.0.0
@@ -1057,9 +931,9 @@ typedef herr_t (*H5A_operator1_t)(hid_t location_id /*in*/, const char *attr_nam
  *
  * \return \hid_tv{attribute}
  *
- * \note The \p acpl parameters is currently not used; specify #H5P_DEFAULT.
+ * \deprecation_note{H5Acreate2()}
  *
- * \deprecated Deprecated in favor of H5Acreate2()
+ * \plist_unused{acpl}
  *
  * \details H5Acreate1() creates an attribute, \p name, which is attached
  *          to the object specified by the identifier \p loc_id.
@@ -1067,18 +941,7 @@ typedef herr_t (*H5A_operator1_t)(hid_t location_id /*in*/, const char *attr_nam
  *          The attribute name, \p name, must be unique for the object.
  *
  *          The attribute is created with the specified datatype and dataspace,
- *          \p type_id and \p space_id, which are created with the H5T and
- *          H5S interfaces, respectively.
- *
- *          If \p type_id is either a fixed-length or variable-length string,
- *          it is important to set the string length when defining the
- *          datatype. String datatypes are derived from #H5T_C_S1 (or
- *          #H5T_FORTRAN_S1 for Fortran), which defaults to 1 character in
- *          size. See H5Tset_size() and Creating variable-length string
- *          datatypes.
- *
- *          The attribute identifier returned by this function must be released
- *          with H5Aclose() resource leaks will develop.
+ *          \p type_id and \p space_id.
  *
  * \since 1.8.0
  *
@@ -1100,8 +963,7 @@ H5_DLL hid_t H5Acreate1(hid_t loc_id, const char *name, hid_t type_id, hid_t spa
  * \return Returns the number of attributes if successful; otherwise returns
  *         a negative value.
  *
- * \deprecated This function is deprecated in favor of the functions
- *             H5Oget_info(), H5Oget_info_by_name(), and H5Oget_info_by_idx().
+ * \deprecation_note{H5Oget_info(), H5Oget_info_by_name(), and H5Oget_info_by_idx()}
  *
  * \details H5Aget_num_attrs() returns the number of attributes attached to
  *          the object specified by its identifier, \p loc_id.
@@ -1124,8 +986,7 @@ H5_DLL int H5Aget_num_attrs(hid_t loc_id);
  *
  * \return \herr_t
  *
- * \deprecated This function is deprecated in favor of the function
- *             H5Aiterate2().
+ * \deprecation_note{H5Aiterate2()}
  *
  * \details H5Aiterate1() iterates over the attributes of the object
  *          specified by its identifier, \p loc_id. The object can be a
@@ -1137,10 +998,6 @@ H5_DLL int H5Aget_num_attrs(hid_t loc_id);
  *          \p op, is returned in \p idx. If \p idx is the null pointer,
  *          then all attributes are processed.
  *
- *          \p op is a user-defined function whose prototype is defined as follows:
- *          \snippet this H5A_operator1_t_snip
- *          \click4more
- *
  * \version 1.8.0 The function \p H5Aiterate was renamed to H5Aiterate1()
  *                and deprecated in this release.
  * \since 1.0.0
@@ -1158,8 +1015,7 @@ H5_DLL herr_t H5Aiterate1(hid_t loc_id, unsigned *idx, H5A_operator1_t op, void
  *
  * \return \hid_tv{attribute}
  *
- * \deprecated This function is deprecated in favor of the function
- *             H5Aopen_by_idx().
+ * \deprecation_note{H5Aopen_by_idx()}
  *
  * \details H5Aopen_idx() opens an attribute which is attached to the
  *          object specified with \p loc_id . The location object may be
@@ -1185,8 +1041,7 @@ H5_DLL hid_t H5Aopen_idx(hid_t loc_id, unsigned idx);
  *
  * \return \hid_tv{attribute}
  *
- * \deprecated This function is deprecated in favor of the function
- *             H5Aopen_by_name().
+ * \deprecation_note{H5Aopen_by_name()}
  *
  * \details H5Aopen_name() opens an attribute specified by its name,
  *          \p name, which is attached to the object specified with
diff --git a/src/H5Dmodule.h b/src/H5Dmodule.h
index 595c714..596fd48 100644
--- a/src/H5Dmodule.h
+++ b/src/H5Dmodule.h
@@ -44,18 +44,18 @@
  * <tr><th>Create</th><th>Read</th></tr>
  * <tr valign="top">
  *   <td>
- *   \snippet H5D_examples.c create
+ *   \snippet{lineno} H5D_examples.c create
  *   </td>
  *   <td>
- *   \snippet H5D_examples.c read
+ *   \snippet{lineno} H5D_examples.c read
  *   </td>
  * <tr><th>Update</th><th>Delete</th></tr>
  * <tr valign="top">
  *   <td>
- *   \snippet H5D_examples.c update
+ *   \snippet{lineno} H5D_examples.c update
  *   </td>
  *   <td>
- *   \snippet H5D_examples.c delete
+ *   \snippet{lineno} H5D_examples.c delete
  *   </td>
  * </tr>
  * </table>
diff --git a/src/H5Dpublic.h b/src/H5Dpublic.h
index b708422..a4de5b2 100644
--- a/src/H5Dpublic.h
+++ b/src/H5Dpublic.h
@@ -32,7 +32,9 @@
 #define H5D_CHUNK_CACHE_NBYTES_DEFAULT ((size_t)-1)
 #define H5D_CHUNK_CACHE_W0_DEFAULT     (-1.0)
 
-/* Bit flags for the H5Pset_chunk_opts() and H5Pget_chunk_opts() */
+/**
+ * Bit flags for the H5Pset_chunk_opts() and H5Pget_chunk_opts()
+ */
 #define H5D_CHUNK_DONT_FILTER_PARTIAL_CHUNKS (0x0002u)
 
 /*******************/
@@ -44,13 +46,12 @@
  * Values for the H5D_LAYOUT property
  */
 typedef enum H5D_layout_t {
-    H5D_LAYOUT_ERROR = -1,
-
-    H5D_COMPACT    = 0, /**< raw data is very small */
-    H5D_CONTIGUOUS = 1, /**< the default */
-    H5D_CHUNKED    = 2, /**< slow and fancy */
-    H5D_VIRTUAL    = 3, /**< actual data is stored in other datasets */
-    H5D_NLAYOUTS   = 4  /**< this one must be last! */
+    H5D_LAYOUT_ERROR = -1, /**< error */
+    H5D_COMPACT      = 0,  /**< raw data is small (< 64KB) */
+    H5D_CONTIGUOUS   = 1,  /**< contiguous layout */
+    H5D_CHUNKED      = 2,  /**< chunked or tiled layout */
+    H5D_VIRTUAL      = 3,  /**< actual data is stored in other datasets */
+    H5D_NLAYOUTS     = 4   /**< this one must be last! */
 } H5D_layout_t;
 //! <!-- [H5D_layout_t_snip] -->
 
@@ -75,11 +76,11 @@ typedef enum H5D_chunk_index_t {
  * Values for the space allocation time property
  */
 typedef enum H5D_alloc_time_t {
-    H5D_ALLOC_TIME_ERROR   = -1,
-    H5D_ALLOC_TIME_DEFAULT = 0,
-    H5D_ALLOC_TIME_EARLY   = 1,
-    H5D_ALLOC_TIME_LATE    = 2,
-    H5D_ALLOC_TIME_INCR    = 3
+    H5D_ALLOC_TIME_ERROR   = -1, /**< Error */
+    H5D_ALLOC_TIME_DEFAULT = 0,  /**< \todo Define this! */
+    H5D_ALLOC_TIME_EARLY   = 1,  /**< Allocate on creation */
+    H5D_ALLOC_TIME_LATE    = 2,  /**< Allocate on first write */
+    H5D_ALLOC_TIME_INCR    = 3   /**< Allocate incrementally (by chunk) */
 } H5D_alloc_time_t;
 //! <!-- [H5D_alloc_time_t_snip] -->
 
@@ -88,10 +89,11 @@ typedef enum H5D_alloc_time_t {
  * Values for the status of space allocation
  */
 typedef enum H5D_space_status_t {
-    H5D_SPACE_STATUS_ERROR          = -1,
-    H5D_SPACE_STATUS_NOT_ALLOCATED  = 0,
-    H5D_SPACE_STATUS_PART_ALLOCATED = 1,
-    H5D_SPACE_STATUS_ALLOCATED      = 2
+    H5D_SPACE_STATUS_ERROR          = -1, /**< Error */
+    H5D_SPACE_STATUS_NOT_ALLOCATED  = 0,  /**< Space has not been allocated for this dataset. */
+    H5D_SPACE_STATUS_PART_ALLOCATED = 1,  /**< Space has been allocated for this dataset. */
+    H5D_SPACE_STATUS_ALLOCATED = 2 /**< Space has been partially allocated for this dataset. (Used only for
+                                      datasets with chunked storage.) */
 } H5D_space_status_t;
 //! <!-- [H5D_space_status_t_snip] -->
 
@@ -100,10 +102,10 @@ typedef enum H5D_space_status_t {
  * Values for time of writing fill value property
  */
 typedef enum H5D_fill_time_t {
-    H5D_FILL_TIME_ERROR = -1,
-    H5D_FILL_TIME_ALLOC = 0,
-    H5D_FILL_TIME_NEVER = 1,
-    H5D_FILL_TIME_IFSET = 2
+    H5D_FILL_TIME_ERROR = -1, /**< Error */
+    H5D_FILL_TIME_ALLOC = 0,  /**< Fill on allocation */
+    H5D_FILL_TIME_NEVER = 1,  /**< Never write fill values */
+    H5D_FILL_TIME_IFSET = 2   /**< Fill if fill-value was set */
 } H5D_fill_time_t;
 //! <!-- [H5D_fill_time_t_snip] -->
 
@@ -112,10 +114,10 @@ typedef enum H5D_fill_time_t {
  * Values for fill value status
  */
 typedef enum H5D_fill_value_t {
-    H5D_FILL_VALUE_ERROR        = -1,
-    H5D_FILL_VALUE_UNDEFINED    = 0,
-    H5D_FILL_VALUE_DEFAULT      = 1,
-    H5D_FILL_VALUE_USER_DEFINED = 2
+    H5D_FILL_VALUE_ERROR        = -1, /**< Error */
+    H5D_FILL_VALUE_UNDEFINED    = 0,  /**< No fill value defined */
+    H5D_FILL_VALUE_DEFAULT      = 1,  /**< Default fill-value */
+    H5D_FILL_VALUE_USER_DEFINED = 2   /**< User-defined fill-value */
 } H5D_fill_value_t;
 //! <!-- [H5D_fill_value_t_snip] -->
 
@@ -124,22 +126,40 @@ typedef enum H5D_fill_value_t {
  * Values for VDS bounds option
  */
 typedef enum H5D_vds_view_t {
-    H5D_VDS_ERROR          = -1,
-    H5D_VDS_FIRST_MISSING  = 0,
-    H5D_VDS_LAST_AVAILABLE = 1
+    H5D_VDS_ERROR          = -1, /**< Error */
+    H5D_VDS_FIRST_MISSING  = 0,  /**< \todo Define this! */
+    H5D_VDS_LAST_AVAILABLE = 1   /**< \todo Define this! */
 } H5D_vds_view_t;
 //! <!-- [H5D_vds_view_t_snip] -->
 
 //! <!-- [H5D_append_cb_t_snip] -->
 /**
- * Callback for H5Pset_append_flush() in a dataset access property list
+ * \brief Callback for H5Pset_append_flush()
+ *
+ * \dset_id{dataset_id}
+ * \param[in] cur_dims The current extent of the dataset's dimensions
+ * \param[in,out] op_data User context
+ *
+ * \return \herr_t
+ *
  */
 typedef herr_t (*H5D_append_cb_t)(hid_t dataset_id, hsize_t *cur_dims, void *op_data);
 //! <!-- [H5D_append_cb_t_snip] -->
 
 //! <!-- [H5D_operator_t_snip] -->
 /**
- * Define the operator function pointer for H5Diterate()
+ * \brief Callback for H5Diterate()
+ *
+ * \param[in,out] elem Pointer to the memory buffer containing the current dataset
+ *                     element
+ * \param[in] type_id Datatype identifier of the elements stored in \pelem
+ * \param[in] ndim Number of dimensions for the \p point array
+ * \param[in] point Array containing the location of the element within
+ *                  the original dataspace
+ * \param[in,out] operator_data Pointer to any user-defined data associated with
+ *                the operation
+ * \return \herr_t_iter
+ *
  */
 typedef herr_t (*H5D_operator_t)(void *elem, hid_t type_id, unsigned ndim, const hsize_t *point,
                                  void *operator_data);
@@ -147,7 +167,29 @@ typedef herr_t (*H5D_operator_t)(void *elem, hid_t type_id, unsigned ndim, const
 
 //! <!-- [H5D_scatter_func_t_snip] -->
 /**
- * Define the operator function pointer for H5Dscatter()
+ * \brief Callback for H5Dscatter()
+ *
+ * \param[out] src_buf Pointer to the buffer holding the next set of elements to
+ *                     scatter. On entry, the value of where \p src_buf points to
+ *                     is undefined. The callback function should set \p src_buf
+ *                     to point to the next set of elements.
+ * \param[out] src_buf_bytes_used Pointer to the number of valid bytes in \p src_buf.
+ *                                On entry, the value where \p src_buf_bytes_used points
+ *                                to is undefined. The callback function should set
+ *                                \p src_buf_bytes_used to the of valid bytes in \p src_buf.
+ *                                This number must be a multiple of the datatype size.
+ * \param[in,out] op_data User-defined pointer to data required by the callback
+ *                        function. A pass-through of the \p op_data pointer provided
+ *                        with the H5Dscatter() function call.
+ * \return herr_t
+ *
+ * \details The callback function should always return at least one
+ *          element in \p src_buf, and must not return more elements
+ *          than are remaining to be scattered. This function will be
+ *          repeatedly called until all elements to be scattered have
+ *          been returned. The callback function should return zero (0)
+ *          to indicate success, and a negative value to indicate failure.
+ *
  */
 typedef herr_t (*H5D_scatter_func_t)(const void **src_buf /*out*/, size_t *src_buf_bytes_used /*out*/,
                                      void *op_data);
@@ -155,7 +197,27 @@ typedef herr_t (*H5D_scatter_func_t)(const void **src_buf /*out*/, size_t *src_b
 
 //! <!-- [H5D_gather_func_t_snip] -->
 /**
- * Define the operator function pointer for H5Dgather()
+ * \brief Callback for H5Dgather()
+ *
+ * \param[in] dst_buf Pointer to the destination buffer which has been filled
+ *                    with the next set of elements gathered. This will always
+ *                    be identical to the \p dst_buf passed to H5Dgather()
+ * \param[in] dst_buf_bytes_used  Pointer to the number of valid bytes in
+ *                                \p dst_buf. This number must be a multiple of
+ *                                the datatype size.
+ * \param[in,out] op_data User-defined pointer to data required by the callback
+ *                        function; a pass-through of the \p op_data pointer
+ *                        provided with the H5Dgather() function call.
+ * \returns \herr_t
+ *
+ * \details The callback function should process, store, or otherwise make use
+ *          of the data returned in dst_buf before it returns, because the
+ *          buffer will be overwritten unless it is the last call to the
+ *          callback. This function will be repeatedly called until all gathered
+ *          elements have been passed to the callback in dst_buf. The callback
+ *          function should return zero (0) to indicate success, and a negative
+ *          value to indicate failure.
+ *
  */
 typedef herr_t (*H5D_gather_func_t)(const void *dst_buf, size_t dst_buf_bytes_used, void *op_data);
 //! <!-- [H5D_gather_func_t_snip] -->
@@ -178,7 +240,7 @@ extern "C" {
  * \brief Creates a new dataset and links it into the file
  *
  * \fgdta_loc_id
- * \param[in] name      Name of the dataset to create
+ * \param[in] name Name of the dataset to create
  * \type_id
  * \space_id
  * \lcpl_id
@@ -203,13 +265,6 @@ extern "C" {
  *          \p name may be either an absolute path in the file or a relative
  *          path from \p loc_id naming the dataset.
  *
- *          \p dtype_id specifies the datatype of each data element as stored
- *          in the file.  If \p dtype_id is either a fixed-length or
- *          variable-length string, it is important to set the string length
- *          when defining the datatype. String datatypes are derived from
- *          #H5T_C_S1 (or #H5T_FORTRAN_S1 for Fortran codes), which defaults
- *          to 1 character in size.
- *
  *          If \p dtype_id is a committed datatype, and if the file location
  *          associated with the committed datatype is different from the
  *          file location where the dataset will be created, the datatype
@@ -217,7 +272,7 @@ extern "C" {
  *
  *          The link creation property list, \p lcpl_id, governs creation
  *          of the link(s) by which the new dataset is accessed and the
- *          creation of any * intermediate groups that may be missing.
+ *          creation of any intermediate groups that may be missing.
  *
  *          The datatype and dataspace properties and the dataset creation
  *          and access property lists are attached to the dataset, so the
@@ -228,8 +283,8 @@ extern "C" {
  *          not previously written, the HDF5 library will return default
  *          or user-defined fill values.
  *
- *          To conserve and release resources, the dataset should be closed
- *          when access is no longer required.
+ * \par Example
+ * \snippet H5D_examples.c create
  *
  * \since 1.8.0
  *
@@ -268,34 +323,14 @@ H5_DLL hid_t H5Dcreate2(hid_t loc_id, const char *name, hid_t type_id, hid_t spa
  *          the file, which may differ from the datatype and dataspace
  *          in application memory.
  *
- *          Dataset creation property list and dataset access creation
- *          property list are specified by \p dcpl_id and \p dapl_id.
- *
  *          H5Dcreate_anon() returns a new dataset identifier. Using
  *          this identifier, the new dataset must be linked into the
  *          HDF5 file structure with H5Olink() or it will be deleted
- *          from the file when the file is closed.
- *
- *          See H5Dcreate2() for further details and considerations on
- *          the use of H5Dcreate2() and H5Dcreate_anon().
- *
- *          The differences between this function and H5Dcreate2() are
- *          as follows:
- *          \li H5Dcreate_anon() explicitly includes a dataset access property
- *          list. H5Dcreate() always uses default dataset access properties.
- *
- *          \li H5Dcreate_anon() neither provides the new dataset’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.
- *
- *          A dataset created with this function should be closed with
- *          H5Dclose() when the dataset is no longer needed so that resource
- *          leaks will not develop.
+ *          when the file is closed.
  *
  * \since 1.8.0
  *
- * \see H5Olink(), H5Dcreate(), Using Identifiers
+ * \see H5Olink(), H5Dcreate()
  *
  */
 H5_DLL hid_t H5Dcreate_anon(hid_t loc_id, hid_t type_id, hid_t space_id, hid_t dcpl_id, hid_t dapl_id);
@@ -321,12 +356,6 @@ H5_DLL hid_t H5Dcreate_anon(hid_t loc_id, hid_t type_id, hid_t space_id, hid_t d
  *          specified then the dataset will be opened at the location
  *          where the attribute, dataset, or named datatype is attached.
  *
- *          The dataset access property list, \p dapl_id, provides
- *          information regarding access to the dataset.
- *
- *          To conserve and release resources, the dataset should be closed
- *          when access is no longer required.
- *
  * \since 1.8.0
  *
  * \see H5Dcreate2(), H5Dclose()
@@ -352,6 +381,9 @@ H5_DLL hid_t H5Dopen2(hid_t loc_id, const char *name, hid_t dapl_id);
  *          be released with H5Sclose() when the identifier is no longer
  *          needed so that resource leaks will not occur.
  *
+ * \par Example
+ * \snippet H5D_examples.c update
+ *
  * \see H5Sclose()
  *
  */
@@ -360,7 +392,19 @@ H5_DLL hid_t H5Dget_space(hid_t dset_id);
 /**
  * --------------------------------------------------------------------------
  * \ingroup H5D
- * \todo Document this function!
+ *
+ * \brief Determines whether space has been allocated for a dataset
+ *
+ * \dset_id
+ * \param[out] allocation Space allocation status
+ *
+ * \return \herr_t
+ *
+ * \details H5Dget_space_status() determines whether space has been allocated
+ *          for the dataset \p dset_id.
+ *
+ * \since 1.6.0
+ *
  */
 H5_DLL herr_t H5Dget_space_status(hid_t dset_id, H5D_space_status_t *allocation);
 
@@ -379,27 +423,7 @@ H5_DLL herr_t H5Dget_space_status(hid_t dset_id, H5D_space_status_t *allocation)
  *
  *          If a dataset has a named datatype, then an identifier to the
  *          opened datatype is returned. Otherwise, the returned datatype
- *          is read-only. If atomization of the datatype fails, then the
- *          datatype is closed.
- *
- *          A datatype identifier returned from this function should be
- *          released with H5Tclose() when the identifier is no longer
- *          needed to prevent resource leaks.
- *
- * \note Datatype Identifiers
- *
- *          Please note that the datatype identifier is actually an object
- *          identifier or a handle returned from opening the datatype. It
- *          is not persistent and its value can be different from one HDF5
- *          session to the next.
- *
- *          H5Tequal() can be used to compare datatypes.
- *
- *          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.
+ *          is read-only.
  *
  */
 H5_DLL hid_t H5Dget_type(hid_t dset_id);
@@ -419,9 +443,6 @@ H5_DLL hid_t H5Dget_type(hid_t dset_id);
  *          a copy of the dataset creation property list associated with
  *          the dataset specified by \p dset_id.
  *
- *          The creation property list identifier should be released
- *          with H5Pclose() to prevent resource leaks.
- *
  */
 H5_DLL hid_t H5Dget_create_plist(hid_t dset_id);
 
@@ -455,10 +476,6 @@ H5_DLL hid_t H5Dget_create_plist(hid_t dset_id);
  *          All link access properties in the returned list will be set
  *          to the default values.
  *
- *          The access property list identifier should be released with
- *          H5Pclose() when the identifier is no longer needed so that
- *          resource leaks will not develop.
- *
  * \since 1.8.3
  *
  */
@@ -477,11 +494,8 @@ H5_DLL hid_t H5Dget_access_plist(hid_t dset_id);
  * \details H5Dget_storage_size() returns the amount of storage,
  *          in bytes, that is allocated in the file for the raw data of
  *          the dataset specified by \p dset_id.
- *
- *          \note The amount of storage in this case is the storage
- *          allocated in the written file, which will typically differ
- *          from the space required to hold a dataset in working memory.
- *
+ *          H5Dget_storage_size() reports only the space required to store
+ *          the dataset elements, excluding any metadata.
  *          \li For contiguous datasets, the returned size equals the current
  *          allocated size of the raw data.
  *          \li For unfiltered chunked datasets, the returned size is the
@@ -491,21 +505,19 @@ H5_DLL hid_t H5Dget_access_plist(hid_t dset_id);
  *          compression filter is in use, H5Dget_storage_size() will return
  *          the total space required to store the compressed chunks.
  *
- *          H5Dget_storage_size() reports only the space required to store
- *          the data, not including that of any metadata.
+ * \note Note that H5Dget_storage_size() is not generally an
+ *       appropriate function to use when determining the amount
+ *       of memory required to work with a dataset. In such
+ *       circumstances, you must determine the number of data
+ *       points in a dataset and the size of an individual dataset
+ *       element. H5Sget_simple_extent_npoints() and H5Tget_size()
+ *       can be used to calculate that amount.
  *
- * \attention H5Dget_storage_size() does not differentiate between 0 (zero),
+ * \warning H5Dget_storage_size() does not differentiate between 0 (zero),
  *          the value returned for the storage size of a dataset
  *          with no stored values, and 0 (zero), the value returned to
  *          indicate an error.
  *
- *          \note Note that H5Dget_storage_size() is not generally an
- *          appropriate function to use when determining the amount
- *          of memory required to work with a dataset. In such
- *          circumstances, you must determine the number of data
- *          points in a dataset and the size of an individual data
- *          element. H5Sget_simple_extent_npoints() and H5Tget_size()
- *          can be used to get that information.
  *
  */
 H5_DLL hsize_t H5Dget_storage_size(hid_t dset_id);
@@ -562,7 +574,7 @@ H5_DLL herr_t H5Dget_chunk_storage_size(hid_t dset_id, const hsize_t *offset, hs
  *          effect. Also, the implementation does not handle the #H5S_ALL
  *          macro correctly.  As a workaround, application can get
  *          the dataspace for the dataset using H5Dget_space() and pass that
- *          in for \p fspace_id.  This will be fixed in coming releases.
+ *          in for \p fspace_id.  This will be fixed in a future release.
  *
  * \since 1.10.5
  *
@@ -617,16 +629,16 @@ H5_DLL herr_t H5Dget_chunk_info_by_coord(hid_t dset_id, const hsize_t *offset, u
  *
  * \return \herr_t
  *
- * \details H5Dget_chunk_info() retrieves the offset coordinates
- *          offset, filter mask filter_mask, size size and address addr for
- *          the dataset specified by the identifier dset_id and the chunk
- *          specified by the index index. The chunk belongs to a set of
- *          chunks in the selection specified by fspace_id. If the queried
+ * \details H5Dget_chunk_info() retrieves the offset coordinates,
+ *          \p offset, filter mask, \p filter_mask, size, \p size, and address
+ *          \p addr for the dataset specified by the identifier \p dset_id and the chunk
+ *          specified by the index \p index. The chunk belongs to a set of
+ *          chunks in the selection specified by \p fspace_id. If the queried
  *          chunk does not exist in the file, the size will be set to 0 and
- *          address to \c HADDR_UNDEF. The value pointed to by filter_mask will
- *          not be modified. NULL can be passed in for any \p out parameters.
+ *          address to #HADDR_UNDEF. The value pointed to by filter_mask will
+ *          not be modified. \c NULL can be passed in for any \p out parameters.
  *
- *          \p chk_idx is the chunk index in the selection. Index value
+ *          \p chk_idx is the chunk index in the selection. The index value
  *          may have a value of 0 up to the number of chunks stored in
  *          the file that have a nonempty intersection with the file
  *          dataspace selection
@@ -640,9 +652,9 @@ H5_DLL herr_t H5Dget_chunk_info_by_coord(hid_t dset_id, const hsize_t *offset, u
  *          \note Please be aware that this function currently does not
  *          support non-trivial selections, thus \p fspace_id has no
  *          effect. Also, the implementation does not handle the #H5S_ALL
- *          macro correctly.  As a workaround, application can get
+ *          macro correctly.  As a workaround, an application can get
  *          the dataspace for the dataset using H5Dget_space() and pass that
- *          in for \p fspace_id.  This will be fixed in coming releases.
+ *          in for \p fspace_id.  This will be fixed in a future release.
  *
  * \since 1.10.5
  *
@@ -658,7 +670,7 @@ H5_DLL herr_t H5Dget_chunk_info(hid_t dset_id, hid_t fspace_id, hsize_t chk_idx,
  *
  * \dset_id
  *
- * \return Returns the offset in bytes; otherwise, returns \c HADDR_UNDEF,
+ * \return Returns the offset in bytes; otherwise, returns #HADDR_UNDEF,
  *         a negative value.
  *
  * \details H5Dget_offset() returns the address in the file of
@@ -707,9 +719,8 @@ H5_DLL haddr_t H5Dget_offset(hid_t dset_id);
  *          used for the memory dataspace and the selection defined with \p
  *          file_space_id is used for the selection within that dataspace.
  *
- *          If raw data storage space has not been allocated for the dataset
- *          and a fill value has been defined, the returned buffer \p buf
- *          is filled with the fill value.
+ *          The number of elements selected in the memory dataspace \Emph{must}
+ *          be equal to the number of elements selected in the file dataspace.
  *
  *          The behavior of the library for the various combinations of
  *          valid dataspace identifiers and #H5S_ALL for the \p mem_space_id
@@ -754,14 +765,12 @@ H5_DLL haddr_t H5Dget_offset(hid_t dset_id);
  *            </tr>
  *          </table>
  *
- * \details Setting an #H5S_ALL selection indicates that the entire
- *          dataspace, as defined by the current dimensions of a dataspace,
- *          will be selected. The number of elements selected in the memory
- *          dataspace must match the number of elements selected in the
- *          file dataspace.
+ * \note If no storage space was allocated for the dataset
+ *       and a fill value is defined, the returned buffer \p buf
+ *       is filled with the fill value.
  *
- *          \p dxpl_id can be the constant #H5P_DEFAULT, in which case the
- *          default data transfer properties are used.
+ * \par Example
+ * \snippet H5D_examples.c read
  *
  */
 H5_DLL herr_t H5Dread(hid_t dset_id, hid_t mem_type_id, hid_t mem_space_id, hid_t file_space_id,
@@ -865,6 +874,8 @@ H5_DLL herr_t H5Dread(hid_t dset_id, hid_t mem_type_id, hid_t mem_space_id, hid_
  *          time if the dataset's fill time is set to #H5D_FILL_TIME_IFSET
  *          or #H5D_FILL_TIME_ALLOC.
  *
+ * \par_compr_note
+ *
  * \attention If a dataset's storage layout is 'compact', care must be
  *          taken when writing data to the dataset in parallel. A compact
  *          dataset's raw data is cached in memory and may be flushed
@@ -872,6 +883,9 @@ H5_DLL herr_t H5Dread(hid_t dset_id, hid_t mem_type_id, hid_t mem_space_id, hid_
  *          applications should always attempt to write identical data to
  *          the dataset from all processes.
  *
+ * \par Example
+ * \snippet H5D_examples.c update
+ *
  * \see H5Pset_fill_time(), H5Pset_alloc_time()
  *
  */
@@ -903,11 +917,6 @@ H5_DLL herr_t H5Dwrite(hid_t dset_id, hid_t mem_type_id, hid_t mem_space_id, hid
  *          pipeline, including filters, and will be written directly to
  *          the file. Only one chunk can be written with this function.
  *
- *          H5Dwrite_chunk() replaces the now deprecated H5DOwrite_chunk()
- *          function, which was located in the high level optimization
- *          library. The parameters and behavior are identical to the
- *          original.
- *
  *          \p filters is a mask providing a record of which filters are
  *          used with the the chunk. The default value of the mask is
  *          zero (0), indicating that all enabled filters are applied. A
@@ -935,11 +944,10 @@ H5_DLL herr_t H5Dwrite(hid_t dset_id, hid_t mem_type_id, hid_t mem_space_id, hid
  *          in a file. H5Dwrite_chunk() bypasses hyperslab selection, the
  *          conversion of data from one datatype to another, and the filter
  *          pipeline to write the chunk. Developers should have experience
- *          with these processes before using this function. Please see
- *          Using the Direct Chunk Write Function for more information.
+ *          with these processes before using this function.
  *
- * \note    H5Dread_chunk() and H5Dwrite_chunk() are not supported under
- *          parallel and do not support variable length types.
+ * \note    H5Dread_chunk() and H5Dwrite_chunk() are currently not supported
+ *          with parallel HDF5 and do not support variable-length types.
  *
  * \since 1.10.2
  *
@@ -977,10 +985,10 @@ H5_DLL herr_t H5Dwrite_chunk(hid_t dset_id, hid_t dxpl_id, uint32_t filters, con
  *          the dimension limits and must specify a point that falls on
  *          a dataset chunk boundary.
  *
- *          The mask \p filters indicates which filters are used with the
- *          chunk when written. A zero value indicates that all enabled
- *          filters are applied on the chunk. A filter is skipped if the
- *          bit corresponding to the filter’s position in the pipeline
+ *          The mask \p filters indicates which filters were used when the
+ *          chunk was written. A zero value (all bits 0) indicates that all
+ *          enabled filters are applied on the chunk. A filter is skipped if
+ *          the bit corresponding to the filter’s position in the pipeline
  *          (0 ≤ position < 32) is turned on.
  *
  *          \p buf is the memory buffer containing the chunk read from
@@ -994,8 +1002,8 @@ H5_DLL herr_t H5Dwrite_chunk(hid_t dset_id, hid_t dxpl_id, uint32_t filters, con
  *          with these processes before using this function. Please see
  *          Using the Direct Chunk Write Function for more information.
  *
- * \note H5Dread_chunk() and H5Dwrite_chunk() are not supported under
- *          parallel and do not support variable length types.
+ * \note H5Dread_chunk() and H5Dwrite_chunk() are currently not supported
+ *       with parallel HDF5 and do not support variable-length datatypes.
  *
  * \since 1.10.2
  *
@@ -1025,52 +1033,9 @@ H5_DLL herr_t H5Dread_chunk(hid_t dset_id, hid_t dxpl_id, const hsize_t *offset,
  *          in the memory buffer \p buf, executing the callback function
  *          \p op once for each such data element.
  *
- *          The prototype of the callback function \p op is as follows
- *          (as defined in the source code file H5Lpublic.h):
- *          \snippet this H5D_operator_t_snip
- *          The parameters of this callback function are:
- *
- *          <table>
- *          <tr><td>\c elem</td>
- *              <td><tt>[in,out]</tt></td>
- *              <td>Pointer to the memory buffer containing the current
- *                  data element</td></tr>
- *          <tr><td>\c type_id</td>
- *              <td><tt>[in]</tt></td>
- *              <td>Datatype identifier of the elements stored in elem</td></tr>
- *          <tr><td>\c ndim</td>
- *              <td><tt>[in]</tt></td>
- *              <td>Number of dimensions for the point array</td></tr>
- *          <tr><td>\c point</td>
- *              <td><tt>[in]</tt></td>
- *              <td>Array containing the location of the element within
- *                  the original dataspace</td></tr>
- *          <tr><td>\c operator_data</td>
- *              <td><tt>[in,out]</tt></td>
- *              <td>Pointer to any user-defined data associated with the
- *                  operation</td></tr>
- *          </table>
- *
- *          The possible return values from the callback function, and
- *          the effect ofeach,are as follows:
- *
- *          \li Zero causes the iterator to continue, returning zero
- *          when all data elements have been processed.
- *          \li A positive value causes the iterator to immediately
- *          return that positive value, indicating short-circuit success.
- *          \li A negative value causes the iterator to immediately return
- *          that value, indicating failure.
- *
- *          The \p operator_data parameter is a user-defined pointer to
- *          the data required to process dataset elements in the course
- *          of the iteration. If operator needs to pass data back to the
- *          application, such data can be returned in this same buffer. This
- *          pointer is passed back to each step of the iteration in the
- *          operator callback function’s operator_data parameter.
- *
- *          Unlike other HDF5 iterators, this iteration operation cannot
- *          be restarted at the point of exit; a second H5Diterate()
- *          call will always restart at the beginning.
+ * \attention Unlike other HDF5 iterators, this iteration operation cannot
+ *            be restarted at the point of exit; a second H5Diterate()
+ *            call will always restart at the beginning.
  *
  *
  * \since 1.10.2
@@ -1154,30 +1119,25 @@ H5_DLL herr_t H5Dvlen_get_buf_size(hid_t dset_id, hid_t type_id, hid_t space_id,
  *
  * \return \herr_t
  *
- * \details H5Dfill() fills the dataspace selection in memory, \p space_id,
+ * \details H5Dfill() fills the dataspace selection, \p space_id, in memory
  *          with the fill value specified in \p fill. If \p fill is NULL,
  *          a fill value of 0 (zero) is used.
  *
  *          \p fill_type_id specifies the datatype of the fill value.
- *          \p buf specifies the buffer in which the dataspace elements
- *          will be written.
- *          \p buf_type_id specifies the datatype of those data elements.
+ *          \p buf specifies the buffer in which the fill elements
+ *          will be written. \p buf_type_id specifies the datatype of
+ *          those data elements.
  *
  * \note Note that if the fill value datatype differs from the memory
- *          buffer datatype, the fill value will be converted to the memory
- *          buffer datatype before filling the selection.
+ *       buffer datatype, the fill value will be converted to the memory
+ *       buffer datatype before filling the selection.
  *
  * \note Applications sometimes write data only to portions of an
- *          allocated dataset. It is often useful in such cases to fill
- *          the unused space with a known fill value. See the following
- *          function for more information:
- *          - H5Pset_fill_value()
- *          - H5Pget_fill_value()
- *          - H5Pfill_value_defined()
- *          - H5Pset_fill_time()
- *          - H5Pget_fill_time()
- *          - H5Pcreate()
- *          - H5Pcreate_anon()
+ *       allocated dataset. It is often useful in such cases to fill
+ *       the unused space with a known fill value.
+ *
+ * \see H5Pset_fill_value(), H5Pget_fill_value(), H5Pfill_value_defined(),
+ *      H5Pset_fill_time(), H5Pget_fill_time(), H5Pcreate(), H5Dcreate_anon()
  *
  */
 H5_DLL herr_t H5Dfill(const void *fill, hid_t fill_type_id, void *buf, hid_t buf_type_id, hid_t space_id);
@@ -1224,22 +1184,21 @@ H5_DLL herr_t H5Dfill(const void *fill, hid_t fill_type_id, void *buf, hid_t buf
  *          - If the dataset’s fill time is set to #H5D_FILL_TIME_ALLOC
  *            (see H5Pset_alloc_time())
  *
- *          \note
- *          \li If the sizes specified in \p size array are smaller than
- *          the dataset’s current dimension sizes, H5Dset_extent() will reduce
- *          the dataset’s dimension sizes to the specified values. It is the
- *          user application’s responsibility to ensure that valuable data is
- *          not lost as H5Dset_extent() does not check.
+ * \note If the sizes specified in \p size array are smaller than the dataset’s
+ *       current dimension sizes, H5Dset_extent() will reduce the dataset’s
+ *       dimension sizes to the specified values. It is the user application’s
+ *       responsibility to ensure that valuable data is not lost as
+ *       H5Dset_extent() does not check.
  *
- *          \li Except for external datasets, H5Dset_extent() is for use with
- *          chunked datasets only, not contiguous datasets.
+ * \note Except for external datasets, H5Dset_extent() is for use with
+ *       chunked datasets only, not contiguous datasets.
  *
- *          \li A call to H5Dset_extent() affects the dataspace of a dataset.
- *          If a dataspace handle was opened for a dataset prior to a call to
- *          H5Dset_extent() then that dataspace handle will no longer reflect
- *          the correct dataspace extent of the dataset. H5Dget_space() must
- *          be called (after closing the previous handle) to obtain the current
- *          dataspace extent.
+ * \note A call to H5Dset_extent() affects the dataspace of a dataset.  If a
+ *       dataspace handle was opened for a dataset prior to a call to
+ *       H5Dset_extent() then that dataspace handle will no longer reflect the
+ *       correct dataspace extent of the dataset. H5Dget_space() must be called
+ *       (after closing the previous handle) to obtain the current dataspace
+ *       extent.
  *
  * \since 1.8.0
  *
@@ -1266,6 +1225,8 @@ H5_DLL herr_t H5Dset_extent(hid_t dset_id, const hsize_t size[]);
  *          open files. After that, the OS is responsible for ensuring
  *          that the data is actually flushed to disk.
  *
+ * \since 1.10.0
+ *
  */
 H5_DLL herr_t H5Dflush(hid_t dset_id);
 
@@ -1324,40 +1285,7 @@ H5_DLL herr_t H5Drefresh(hid_t dset_id);
  *
  *          To retrieve the data to be scattered, H5Dscatter() repeatedly
  *          calls \p op, which should return a valid source buffer, until
- *          enough data to fill the selection has been retrieved. The
- *          prototype of the callback function \p op is as follows (as
- *          defined in the source code file H5Dpublic.h):
- *          \snippet this H5D_scatter_func_t_snip
- *          The parameters of this callback function are described below:
- *
- *          <table>
- *          <tr><td>\c src_buf</td>
- *              <td><tt>[out]</tt></td>
- *              <td>Pointer to the buffer holding the next set of elements to
- *                  scatter. On entry, the value of where \c src_buf points to
- *                  is undefined. The callback function should set \c src_buf
- *                  to point to the next set of elements.</td></tr>
- *          <tr><td>\c src_buf_bytes_used</td>
- *              <td><tt>[out]</tt></td>
- *              <td>Pointer to the number of valid bytes in \c src_buf. On
- *                  entry, the value where \c src_buf_bytes_used points to is
- *                  undefined. The callback function should set
- *                  \c src_buf_bytes_used to the of valid bytes in \c src_buf.
- *                  This number must be a multiple of the datatype size.
- *                  </td></tr>
- *          <tr><td>\c op_data</td>
- *              <td><tt>[in,out]</tt></td>
- *              <td>User-defined pointer to data required by the callback
- *                  function. A pass-through of the \c op_data pointer provided
- *                  with the H5Dscatter() function call.</td></tr>
- *          </table>
- *
- *          The callback function should always return at least one
- *          element in \p src_buf, and must not return more elements
- *          than are remaining to be scattered. This function will be
- *          repeatedly called until all elements to be scattered have
- *          been returned. The callback function should return zero (0)
- *          to indicate success, and a negative value to indicate failure.
+ *          enough data to fill the selection has been retrieved.
  *
  * \since 1.10.2
  *
@@ -1409,27 +1337,9 @@ H5_DLL herr_t H5Dscatter(H5D_scatter_func_t op, void *op_data, hid_t type_id, hi
  *          If no callback function is provided, H5Dgather() simply gathers
  *          the data into \p dst_buf and returns. If a callback function is
  *          provided, H5Dgather() repeatedly gathers up to \p dst_buf_size
- *          bytes to process the serialized data. The prototype of the
- *          callback function \p op is as follows (as defined in the source
- *          code file H5Dpublic.h):
- *          \snippet this H5D_gather_func_t_snip
- *          The parameters of this callback function are described in the
- *          table below.
- *          <table>
- *          <tr><td>\c dst_buf</td>
- *              <td>Pointer to the destination buffer which has been filled
- *                  with the next set of elements gathered. This will always be
- *                  identical to the \p dst_buf passed to H5Dgather().</td></tr>
- *          <tr><td>\c dst_buf_bytes_used</td>
- *              <td>Pointer to the number of valid bytes in \p dst_buf.
- *                  This number must be a multiple of the datatype
- *                  size.</td></tr>
- *          <tr><td>\c op_data</td>
- *              <td>User-defined pointer to data required by the callback
- *                  function; a pass-through of the \p op_data pointer
- *                  provided with the H5Dgather() function call.</td></tr>
- *          </table>
- *          The callback function should process, store, or otherwise,
+ *          bytes to process the serialized data.
+ *
+ *          The callback function \p op should process, store, or otherwise,
  *          make use of the data returned in \p dst_buf before it returns,
  *          because the buffer will be overwritten unless it is the last
  *          call to the callback. This function will be repeatedly called
@@ -1453,11 +1363,11 @@ H5_DLL herr_t H5Dgather(hid_t src_space_id, const void *src_buf, hid_t type_id,
  *
  * \return \herr_t
  *
- * \details H5Dclose() ends access to a dataset specified by \p dset_id
- *          and releases resources used by it.
+ * \details H5Dclose() terminates access to a dataset via the identifier
+ *          \p dset_id and releases the underlying resources.
  *
- * \attention Further use of a released dataset identifier is illegal; a
- *          function using such an identifier will generate an error.
+ * \par Example
+ * \snippet H5D_examples.c read
  *
  * \since 1.8.0
  *
@@ -1510,8 +1420,7 @@ H5_DLL herr_t H5Dget_chunk_index_type(hid_t did, H5D_chunk_index_t *idx_type);
  *
  * \return \hid_t{dataset}
  *
- * \deprecated This function is deprecated in favor of the function H5Dcreate2()
- *             or the macro H5Dcreate().
+ * \deprecation_note{H5Dcreate2() or the macro H5Dcreate()}
  *
  * \details H5Dcreate1() creates a data set with a name, \p name, in the
  *          location specified by the identifier \p loc_id. \p loc_id may be a
@@ -1577,8 +1486,7 @@ H5_DLL hid_t H5Dcreate1(hid_t loc_id, const char *name, hid_t type_id, hid_t spa
  *
  * \return \hid_t{dataset}
  *
- * \deprecated This function is deprecated in favor of the function H5Dopen2()
- *             or the macro H5Dopen().
+ * \deprecation_note{H5Dopen2() or the macro H5Dopen()}
  *
  * \details H5Dopen1() opens an existing dataset for access at the location
  *          specified by \p loc_id.  \p loc_id may be a file, group, dataset,
@@ -1608,10 +1516,10 @@ H5_DLL hid_t H5Dopen1(hid_t loc_id, const char *name);
  *
  * \return \herr_t
  *
- * \deprecated This function is deprecated in favor of the function H5Dset_extent().
+ * \deprecation_note{H5Dset_extent()}
  *
  * \details H5Dextend() verifies that the dataset is at least of size \p size,
- *          extending it if necessary. The dimensionality of size is the same as
+ *          extending it if necessary. The length of \p size is the same as
  *          that of the dataspace of the dataset being changed.
  *
  *          This function can be applied to the following datasets:
@@ -1631,7 +1539,7 @@ H5_DLL hid_t H5Dopen1(hid_t loc_id, const char *name);
  *          the sizes specified in size. The function H5Dset_extent() must be
  *          used if the dataset dimension sizes are are to be reduced.
  *
- * \version 1.8.0 Function Function deprecated in this release. Parameter size
+ * \version 1.8.0 Function deprecated in this release. Parameter size
  *                syntax changed to \Code{const hsize_t size[]} in this release.
  *
  */
diff --git a/src/H5Emodule.h b/src/H5Emodule.h
index 1670c03..58a3517 100644
--- a/src/H5Emodule.h
+++ b/src/H5Emodule.h
@@ -29,4 +29,54 @@
 #define H5_MY_PKG_ERR  H5E_ERROR
 #define H5_MY_PKG_INIT YES
 
+/**\defgroup H5E H5E
+ *
+ * Use the functions in this module to manage HDF5 error stacks and error
+ * messages.
+ *
+ * <table>
+ * <tr><th>Create</th><th>Read</th></tr>
+ * <tr valign="top">
+ *   <td>
+ *   \snippet{lineno} H5E_examples.c create
+ *   </td>
+ *   <td>
+ *   \snippet{lineno} H5E_examples.c read
+ *   </td>
+ * <tr><th>Update</th><th>Delete</th></tr>
+ * <tr valign="top">
+ *   <td>
+ *   \snippet{lineno} H5E_examples.c update
+ *   </td>
+ *   <td>
+ *   \snippet{lineno} H5E_examples.c delete
+ *   </td>
+ * </tr>
+ * </table>
+ *
+ * \internal The \c FUNC_ENTER macro clears the error stack whenever an
+ *           interface function is entered. When an error is detected, an entry
+ *           is pushed onto the stack. As the functions unwind, additional
+ *           entries are pushed onto the stack. The API function will return
+ *           some indication that an error occurred and the application can
+ *           print the error stack.
+ *
+ * \internal Certain API functions in the \ref H5E package, such as H5Eprint(),
+ *           do not clear the error stack. Otherwise, any function which does
+ *           not have an underscore immediately after the package name will
+ *           clear the error stack. For instance, H5Fopen() clears the error
+ *           stack while \Code{H5F_open} does not.
+ *
+ * \internal An error stack has a fixed maximum size. If this size is exceeded
+ *           then the stack will be truncated and only the inner-most functions
+ *           will have entries on the stack. This is expected to be a rare
+ *           condition.
+ *
+ * \internal Each thread has its own error stack, but since multi-threading has
+ *           not been added to the library yet, this package maintains a single
+ *           error stack. The error stack is statically allocated to reduce the
+ *           complexity of handling errors within the \ref H5E package.
+ *
+ */
+
 #endif /* H5Emodule_H */
diff --git a/src/H5Epublic.h b/src/H5Epublic.h
index 1c7055a..43eb4fc 100644
--- a/src/H5Epublic.h
+++ b/src/H5Epublic.h
@@ -38,9 +38,9 @@ typedef struct H5E_error2_t {
     hid_t cls_id;
     /**< Class ID                           */
     hid_t maj_num;
-    /**< Major error ID		                */
+    /**< Major error ID                        */
     hid_t min_num;
-    /**< Minor error number		            */
+    /**< Minor error number                    */
     unsigned line;
     /**< Line in file where error occurs    */
     const char *func_name;
@@ -696,12 +696,13 @@ typedef herr_t (*H5E_auto1_t)(void *client_data);
  *
  * \return \herr_t
  *
+ * \deprecated 1.8.0 Function H5Eclear() renamed to H5Eclear1() and deprecated
+ *                   in this release.
+ *
  * \details H5Eclear1() clears the error stack for the current thread.\n
  *          The stack is also cleared whenever an API function is called, with
  *          certain exceptions (for instance, H5Eprint1()).
  *
- * \deprecated 1.8.0 Function H5Eclear() renamed to H5Eclear1() and deprecated
- *                   in this release.
  */
 H5_DLL herr_t H5Eclear1(void);
 /**
@@ -717,6 +718,9 @@ H5_DLL herr_t H5Eclear1(void);
  *                         function
  * \return \herr_t
  *
+ * \deprecated 1.8.0 Function H5Eget_auto() renamed to H5Eget_auto1() and
+ *                   deprecated in this release.
+ *
  * \details H5Eget_auto1() returns the current settings for the automatic error
  *          stack traversal function, \p func, and its data,
  *          \p client_data. Either or both arguments may be \c NULL, in which case the
@@ -743,8 +747,6 @@ H5_DLL herr_t H5Eclear1(void);
  *          H5Eprint2(), mixing H5Eset_auto1() and H5Eget_auto2() or mixing
  *          H5Eset_auto2() and H5Eget_auto1() does not fail.
  *
- * \deprecated 1.8.0 Function H5Eget_auto() renamed to H5Eget_auto1() and
- *                   deprecated in this release.
  */
 H5_DLL herr_t H5Eget_auto1(H5E_auto1_t *func, void **client_data);
 /**
@@ -761,6 +763,9 @@ H5_DLL herr_t H5Eget_auto1(H5E_auto1_t *func, void **client_data);
  * \param[in] str Error description string
  * \return \herr_t
  *
+ * \deprecated 1.8.0 Function H5Epush() renamed to H5Epush1() and
+ *                   deprecated in this release.
+ *
  * \details H5Epush1() pushes a new error record onto the error stack for the
  *          current thread.\n
  *          The error has major and minor numbers \p maj_num
@@ -771,8 +776,6 @@ H5_DLL herr_t H5Eget_auto1(H5E_auto1_t *func, void **client_data);
  *          allocated.
  *
  * \since 1.4.0
- * \deprecated 1.8.0 Function H5Epush() renamed to H5Epush1() and
- *                   deprecated in this release.
  */
 H5_DLL herr_t H5Epush1(const char *file, const char *func, unsigned line, H5E_major_t maj, H5E_minor_t min,
                        const char *str);
@@ -785,6 +788,9 @@ H5_DLL herr_t H5Epush1(const char *file, const char *func, unsigned line, H5E_ma
  * \param[in] stream File pointer, or \c NULL for \c stderr
  * \return \herr_t
  *
+ * \deprecated 1.8.0 Function H5Eprint() renamed to H5Eprint1() and
+ *                   deprecated in this release.
+ *
  * \details H5Eprint1() prints prints the error stack for the current thread
  *          on the specified stream, \p stream. Even if the error stack is empty, a
  *          one-line message of the following form will be printed:
@@ -795,8 +801,6 @@ H5_DLL herr_t H5Epush1(const char *file, const char *func, unsigned line, H5E_ma
  *          that prints error messages. Users are encouraged to write their own
  *          more specific error handlers.
  *
- * \deprecated 1.8.0 Function H5Eprint() renamed to H5Eprint1() and
- *                   deprecated in this release.
  */
 H5_DLL herr_t H5Eprint1(FILE *stream);
 /**
@@ -809,6 +813,9 @@ H5_DLL herr_t H5Eprint1(FILE *stream);
  * \param[in] client_data Data passed to the error function
  * \return \herr_t
  *
+ * \deprecated 1.8.0 Function H5Eset_auto() renamed to H5Eset_auto1() and
+ *                   deprecated in this release.
+ *
  * \details H5Eset_auto1() turns on or off automatic printing of errors. When
  *          turned on (non-null \p func pointer), any API function which returns
  *          an error indication will first call \p func, passing it \p
@@ -825,8 +832,6 @@ H5_DLL herr_t H5Eprint1(FILE *stream);
  *          Automatic stack traversal is always in the #H5E_WALK_DOWNWARD
  *          direction.
  *
- * \deprecated 1.8.0 Function H5Eset_auto() renamed to H5Eset_auto1() and
- *                   deprecated in this release.
  */
 H5_DLL herr_t H5Eset_auto1(H5E_auto1_t func, void *client_data);
 /**
@@ -840,6 +845,9 @@ H5_DLL herr_t H5Eset_auto1(H5E_auto1_t func, void *client_data);
  * \param[in] client_data Data to be passed to \p func
  * \return \herr_t
  *
+ * \deprecated 1.8.0 Function H5Ewalk() renamed to H5Ewalk1() and
+ *                   deprecated in this release.
+ *
  * \details H5Ewalk1() walks the error stack for the current thread and calls
  *          the function specified in \p func for each error along the way.
  *
@@ -857,8 +865,6 @@ H5_DLL herr_t H5Eset_auto1(H5E_auto1_t func, void *client_data);
  *          is as follows:
  *          \snippet this H5E_walk1_t_snip
  *
- * \deprecated 1.8.0 Function H5Ewalk() renamed to H5Ewalk1() and
- *                   deprecated in this release.
  */
 H5_DLL herr_t H5Ewalk1(H5E_direction_t direction, H5E_walk1_t func, void *client_data);
 /**
@@ -871,6 +877,8 @@ H5_DLL herr_t H5Ewalk1(H5E_direction_t direction, H5E_walk1_t func, void *client
  * \param[in] maj Major error number
  * \return \herr_t
  *
+ * \deprecated 1.8.0 Function deprecated in this release.
+ *
  * \details Given a major error number, H5Eget_major() returns a constant
  *          character string that describes the error.
  *
@@ -878,7 +886,6 @@ H5_DLL herr_t H5Ewalk1(H5E_direction_t direction, H5E_walk1_t func, void *client
  *            array). An application calling this function must free the memory
  *            associated with the return value to prevent a memory leak.
  *
- * \deprecated 1.8.0 Function deprecated in this release.
  */
 H5_DLL char *H5Eget_major(H5E_major_t maj);
 /**
@@ -891,6 +898,8 @@ H5_DLL char *H5Eget_major(H5E_major_t maj);
  * \param[in] min Minor error number
  * \return \herr_t
  *
+ * \deprecated 1.8.0 Function deprecated and return type changed in this release.
+ *
  * \details Given a minor error number, H5Eget_minor() returns a constant
  *          character string that describes the error.
  *
@@ -900,7 +909,6 @@ H5_DLL char *H5Eget_major(H5E_major_t maj);
  *            the memory associated with the return value to prevent a memory
  *            leak. This is a change from the 1.6.x release series.
  *
- * \deprecated 1.8.0 Function deprecated and return type changed in this release.
  */
 H5_DLL char *H5Eget_minor(H5E_minor_t min);
 #endif /* H5_NO_DEPRECATED_SYMBOLS */
diff --git a/src/H5Fmodule.h b/src/H5Fmodule.h
index 7f0299a..81c1ede 100644
--- a/src/H5Fmodule.h
+++ b/src/H5Fmodule.h
@@ -29,8 +29,7 @@
 #define H5_MY_PKG_ERR  H5E_FILE
 #define H5_MY_PKG_INIT YES
 
-/**
- * \defgroup H5F H5F
+/**\defgroup H5F H5F
  *
  * Use the functions in this module to manage HDF5 files.
  *
@@ -41,15 +40,23 @@
  * creation or access \c mode control the interaction with the underlying
  * storage such as file systems.
  *
- * \Emph{Proper error handling is part of the life cycle.}
  * <table>
- * <tr><th>Create</th><th>Open</th></tr>
+ * <tr><th>Create</th><th>Read</th></tr>
  * <tr valign="top">
  *   <td>
- *   \snippet H5F_examples.c life_cycle
+ *   \snippet{lineno} H5F_examples.c create
  *   </td>
  *   <td>
- *   \snippet H5F_examples.c life_cycle_w_open
+ *   \snippet{lineno} H5F_examples.c read
+ *   </td>
+ * </tr>
+ * <tr><th>Update</th><th>Delete</th></tr>
+ * <tr valign="top">
+ *   <td>
+ *   \snippet{lineno} H5F_examples.c update
+ *   </td>
+ *   <td>
+ *   \snippet{lineno} H5F_examples.c delete
  *   </td>
  * </tr>
  * </table>
diff --git a/src/H5Fpublic.h b/src/H5Fpublic.h
index 2fe1c9f..58fa3b8 100644
--- a/src/H5Fpublic.h
+++ b/src/H5Fpublic.h
@@ -188,7 +188,7 @@ typedef enum H5F_libver_t {
     H5F_LIBVER_EARLIEST = 0, /**< Use the earliest possible format for storing objects */
     H5F_LIBVER_V18      = 1, /**< Use the latest v18 format for storing objects */
     H5F_LIBVER_V110     = 2, /**< Use the latest v110 format for storing objects */
-    H5F_LIBVER_NBOUNDS
+    H5F_LIBVER_NBOUNDS       /**< Sentinel */
 } H5F_libver_t;
 
 #define H5F_LIBVER_LATEST H5F_LIBVER_V110
diff --git a/src/H5Gmodule.h b/src/H5Gmodule.h
index fe26bd2..a0e121d 100644
--- a/src/H5Gmodule.h
+++ b/src/H5Gmodule.h
@@ -29,8 +29,29 @@
 #define H5_MY_PKG_ERR  H5E_SYM
 #define H5_MY_PKG_INIT YES
 
-/**
- * \defgroup H5G H5G
+/** \defgroup H5G H5G
+ *
+ * Use the functions in this module to manage HDF5 groups.
+ *
+ * <table>
+ * <tr><th>Create</th><th>Read</th></tr>
+ * <tr valign="top">
+ *   <td>
+ *   \snippet{lineno} H5G_examples.c create
+ *   </td>
+ *   <td>
+ *   \snippet{lineno} H5G_examples.c read
+ *   </td>
+ * <tr><th>Update</th><th>Delete</th></tr>
+ * <tr valign="top">
+ *   <td>
+ *   \snippet{lineno} H5G_examples.c update
+ *   </td>
+ *   <td>
+ *   \snippet{lineno} H5G_examples.c delete
+ *   </td>
+ * </tr>
+ * </table>
  *
  * \details \Bold{Groups in HDF5:} A group associates names with objects and
  *          provides a mechanism for mapping a name to an object. Since all
diff --git a/src/H5Imodule.h b/src/H5Imodule.h
index a2174d7..d77591d 100644
--- a/src/H5Imodule.h
+++ b/src/H5Imodule.h
@@ -30,8 +30,85 @@
 #define H5_MY_PKG_INIT NO
 
 /**\defgroup H5I H5I
- * \brief Identifier Interface
- * \todo Describe concisely what the functions in this module are about.
+ *
+ * Use the functions in this module to manage identifiers defined by the HDF5
+ * library. See \ref H5IUD for user-defined identifiers and identifier
+ * types.
+ *
+ * HDF5 identifiers are usually created as a side-effect of creating HDF5
+ * entities such as groups, datasets, attributes, or property lists.
+ *
+ * Identifiers defined by the HDF5 library can be used to retrieve information
+ * such as path names and reference counts, and their validity can be checked.
+ *
+ * Identifiers can be updated by manipulating their reference counts.
+ *
+ * Unused identifiers should be reclaimed by closing the associated item, e.g.,
+ * HDF5 object, or decrementing the reference count to 0.
+ *
+ * \note Identifiers (of type \ref hid_t) are run-time auxiliaries and
+ * not persisted in the file.
+ *
+ * <table>
+ * <tr><th>Create</th><th>Read</th></tr>
+ * <tr valign="top">
+ *   <td>
+ *   \snippet{lineno} H5I_examples.c create
+ *   </td>
+ *   <td>
+ *   \snippet{lineno} H5I_examples.c read
+ *   </td>
+ * <tr><th>Update</th><th>Delete</th></tr>
+ * <tr valign="top">
+ *   <td>
+ *   \snippet{lineno} H5I_examples.c update
+ *   </td>
+ *   <td>
+ *   \snippet{lineno} H5I_examples.c delete
+ *   </td>
+ * </tr>
+ * </table>
+ *
+ * \defgroup H5IUD User-defined ID Types
+ * \ingroup H5I
+ *
+ * The \ref H5I module contains functions to define new identifier types.
+ * For convenience, handles of type \ref hid_t can then be associated with the
+ * new identifier types and user objects.
+ *
+ * New identifier types can be created by registering a new identifier type
+ * with the HDF5 library. Once a new identifier type has bee registered,
+ * it can be used to generate identifiers for user objects.
+ *
+ * User-defined identifier types can be searched and iterated.
+ *
+ * Like library-defined identifiers, user-defined identifiers \Emph{and}
+ * identifier types are reference counted, and the reference counts can be
+ * manipulated accordingly.
+ *
+ * User-defined identifiers no longer in use should be deleted or reclaimed,
+ * and identifier types should be destroyed if they are no longer required.
+ *
+ * <table>
+ * <tr><th>Create</th><th>Read</th></tr>
+ * <tr valign="top">
+ *   <td>
+ *   \snippet{lineno} H5I_examples.c create_ud
+ *   </td>
+ *   <td>
+ *   \snippet{lineno} H5I_examples.c read_ud
+ *   </td>
+ * <tr><th>Update</th><th>Delete</th></tr>
+ * <tr valign="top">
+ *   <td>
+ *   \snippet{lineno} H5I_examples.c update_ud
+ *   </td>
+ *   <td>
+ *   \snippet{lineno} H5I_examples.c delete_ud
+ *   </td>
+ * </tr>
+ * </table>
+ *
  */
 
 #endif /* H5Imodule_H */
diff --git a/src/H5Ipublic.h b/src/H5Ipublic.h
index a632881..d07347b 100644
--- a/src/H5Ipublic.h
+++ b/src/H5Ipublic.h
@@ -94,7 +94,7 @@ extern "C" {
 /* Public API functions */
 
 /**
- * \ingroup H5I
+ * \ingroup H5IUD
  *
  * \brief Registers an object under a type and returns an ID for it
  *
@@ -116,7 +116,7 @@ extern "C" {
  */
 H5_DLL hid_t H5Iregister(H5I_type_t type, const void *object);
 /**
- * \ingroup H5I
+ * \ingroup H5IUD
  *
  * \brief Returns the object referenced by an ID
  *
@@ -139,7 +139,7 @@ H5_DLL hid_t H5Iregister(H5I_type_t type, const void *object);
  */
 H5_DLL void *H5Iobject_verify(hid_t id, H5I_type_t type);
 /**
- * \ingroup H5I
+ * \ingroup H5IUD
  *
  * \brief Removes an ID from its type
  *
@@ -178,12 +178,7 @@ H5_DLL void *H5Iremove_verify(hid_t id, H5I_type_t type);
  * \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
+ *          \p id. 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
@@ -379,7 +374,7 @@ H5_DLL int H5Idec_ref(hid_t id);
  */
 H5_DLL int H5Iget_ref(hid_t id);
 /**
- * \ingroup H5I
+ * \ingroup H5IUD
  *
  * \brief Creates and returns a new ID type
  *
@@ -411,7 +406,7 @@ H5_DLL int H5Iget_ref(hid_t id);
  */
 H5_DLL H5I_type_t H5Iregister_type(size_t hash_size, unsigned reserved, H5I_free_t free_func);
 /**
- * \ingroup H5I
+ * \ingroup H5IUD
  *
  * \brief Deletes all identifiers of the given type
  *
@@ -435,7 +430,7 @@ H5_DLL H5I_type_t H5Iregister_type(size_t hash_size, unsigned reserved, H5I_free
  */
 H5_DLL herr_t H5Iclear_type(H5I_type_t type, hbool_t force);
 /**
- * \ingroup H5I
+ * \ingroup H5IUD
  *
  * \brief Removes an identifier type and all identifiers within that type
  *
@@ -458,7 +453,7 @@ H5_DLL herr_t H5Iclear_type(H5I_type_t type, hbool_t force);
  */
 H5_DLL herr_t H5Idestroy_type(H5I_type_t type);
 /**
- * \ingroup H5I
+ * \ingroup H5IUD
  *
  * \brief Increments the reference count on an ID type
  *
@@ -477,7 +472,7 @@ H5_DLL herr_t H5Idestroy_type(H5I_type_t type);
  */
 H5_DLL int H5Iinc_type_ref(H5I_type_t type);
 /**
- * \ingroup H5I
+ * \ingroup H5IUD
  *
  * \brief Decrements the reference count on an identifier type
  *
@@ -497,7 +492,7 @@ H5_DLL int H5Iinc_type_ref(H5I_type_t type);
  */
 H5_DLL int H5Idec_type_ref(H5I_type_t type);
 /**
- * \ingroup H5I
+ * \ingroup H5IUD
  *
  * \brief Retrieves the reference count on an ID type
  *
@@ -516,7 +511,7 @@ H5_DLL int H5Idec_type_ref(H5I_type_t type);
  */
 H5_DLL int H5Iget_type_ref(H5I_type_t type);
 /**
- * \ingroup H5I
+ * \ingroup H5IUD
  *
  * \brief Finds the memory referred to by an ID within the given ID type such
  *        that some criterion is satisfied
@@ -557,7 +552,7 @@ H5_DLL int H5Iget_type_ref(H5I_type_t type);
  */
 H5_DLL void *H5Isearch(H5I_type_t type, H5I_search_func_t func, void *key);
 /**
- * \ingroup H5I
+ * \ingroup H5IUD
  *
  * \brief Returns the number of identifiers in a given identifier type
  *
@@ -577,7 +572,7 @@ H5_DLL void *H5Isearch(H5I_type_t type, H5I_search_func_t func, void *key);
  */
 H5_DLL herr_t H5Inmembers(H5I_type_t type, hsize_t *num_members);
 /**
- * \ingroup H5I
+ * \ingroup H5IUD
  *
  * \brief Determines whether an identifier type is registered
  *
diff --git a/src/H5Lmodule.h b/src/H5Lmodule.h
index 54b94a4..cffd25c 100644
--- a/src/H5Lmodule.h
+++ b/src/H5Lmodule.h
@@ -30,11 +30,34 @@
 #define H5_MY_PKG_INIT YES
 
 /**\defgroup H5L H5L
- * \brief Link Interface
- * \todo Describe concisely what the functions in this module are about.
+ *
+ * Use the functions in this module to manage HDF5 links and link types.
+ *
+ * <table>
+ * <tr><th>Create</th><th>Read</th></tr>
+ * <tr valign="top">
+ *   <td>
+ *   \snippet{lineno} H5L_examples.c create
+ *   </td>
+ *   <td>
+ *   \snippet{lineno} H5L_examples.c iter_cb
+ *   \snippet{lineno} H5L_examples.c read
+ *   </td>
+ * <tr><th>Update</th><th>Delete</th></tr>
+ * <tr valign="top">
+ *   <td>
+ *   \snippet{lineno} H5L_examples.c update
+ *   </td>
+ *   <td>
+ *   \snippet{lineno} H5L_examples.c delete
+ *   </td>
+ * </tr>
+ * </table>
  *
  * \defgroup TRAV Link Traversal
  * \ingroup H5L
+ * \defgroup H5LA Advanced Link Functions
+ * \ingroup H5L
  */
 
 #endif /* H5Lmodule_H */
diff --git a/src/H5Lpublic.h b/src/H5Lpublic.h
index a87edfe..be0d065 100644
--- a/src/H5Lpublic.h
+++ b/src/H5Lpublic.h
@@ -713,38 +713,37 @@ H5_DLL htri_t H5Lexists(hid_t loc_id, const char *name, hid_t lapl_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()).
+ *          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_info() returns information about name in the data structure
- *          \ref H5L_info_t, which is described below and defined in
- *          H5Lpublic.h. This structure is returned in the buffer \p linfo.
+ *          H5L_info_t, which is described below and defined in H5Lpublic.h.
+ *          This structure is returned in the buffer \p linfo.
  *          \snippet this H5L_info_t_snip
- *          In the above struct, type specifies the link class. Valid values
+ *          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.
  *
- *          \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;
+ *          \p corder specifies the link’s creation order position while
+ *          \p corder_valid indicates whether the value in corder is valid.
  *
- *          \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.
+ *          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.
  *
- *          \c cset specifies the character set in which the link name is
+ *          \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().
@@ -784,9 +783,8 @@ H5_DLL herr_t H5Lget_info(hid_t loc_id, const char *name, H5L_info_t *linfo, hid
  * \return \herr_t
  *
  * \details H5get_info_by_idx() 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
+ *          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
@@ -947,19 +945,18 @@ H5_DLL herr_t H5Literate(hid_t grp_id, H5_index_t idx_type, H5_iter_order_t orde
 /**
  * \ingroup TRAV
  *
- * \brief Iterates through links in a group by its name
+ * \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})
+ *                    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.}
@@ -1022,7 +1019,6 @@ H5_DLL herr_t H5Literate_by_name(hid_t loc_id, const char *group_name, H5_index_
  * \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.}
@@ -1109,11 +1105,7 @@ H5_DLL herr_t H5Lvisit(hid_t grp_id, H5_index_t idx_type, H5_iter_order_t order,
  * \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.}
+ * \return \herr_t
  *
  * \details H5Lvisit_by_name() is a recursive iteration function to visit all
  *          links in and below a group in an HDF5 file, thus providing a
diff --git a/src/H5Omodule.h b/src/H5Omodule.h
index 134aa92..8afba29 100644
--- a/src/H5Omodule.h
+++ b/src/H5Omodule.h
@@ -30,9 +30,46 @@
 #define H5_MY_PKG_INIT YES
 
 /**\defgroup H5O H5O
- * \brief Object Interface
  *
- * \todo Describe concisely what the functions in this module are about.
+ * Use the functions in this module to manage HDF5 objects.
+ *
+ * HDF5 objects (groups, datasets, datatype objects) are usually created
+ * using functions in the object-specific modules (\ref H5G, \ref H5D,
+ * \ref H5T). However, new objects can also be created by copying existing
+ * objects.
+ *
+ * Many functions in this module are variations on object introspection,
+ * that is, the retrieval of detailed information about HDF5 objects in a file.
+ * Objects in an HDF5 file can be "visited" in an iterative fashion.
+ *
+ * HDF5 objects are usually updated using functions in the object-specific
+ * modules. However, there are certain generic object properties, such as
+ * reference counts, that can be manipulated using functions in this module.
+ *
+ * HDF5 objects are deleted as a side effect of rendering them unreachable
+ * from the root group. The net effect is the diminution of the object's
+ * reference count to zero, which can (but should not usually) be effected
+ * by a function in this module.
+ *
+ * <table>
+ * <tr><th>Create</th><th>Read</th></tr>
+ * <tr valign="top">
+ *   <td>
+ *   \snippet{lineno} H5O_examples.c create
+ *   </td>
+ *   <td>
+ *   \snippet{lineno} H5O_examples.c read
+ *   </td>
+ * <tr><th>Update</th><th>Delete</th></tr>
+ * <tr valign="top">
+ *   <td>
+ *   \snippet{lineno} H5O_examples.c update
+ *   </td>
+ *   <td>
+ *   \snippet{lineno} H5O_examples.c delete
+ *   </td>
+ * </tr>
+ * </table>
  *
  */
 #endif /* H5Omodule_H */
diff --git a/src/H5Opublic.h b/src/H5Opublic.h
index 3cb7372..769df60 100644
--- a/src/H5Opublic.h
+++ b/src/H5Opublic.h
@@ -35,14 +35,14 @@
 /*****************/
 
 /* Flags for object copy (H5Ocopy) */
-#define H5O_COPY_SHALLOW_HIERARCHY_FLAG     (0x0001u) /* Copy only immediate members */
-#define H5O_COPY_EXPAND_SOFT_LINK_FLAG      (0x0002u) /* Expand soft links into new objects */
-#define H5O_COPY_EXPAND_EXT_LINK_FLAG       (0x0004u) /* Expand external links into new objects */
-#define H5O_COPY_EXPAND_REFERENCE_FLAG      (0x0008u) /* Copy objects that are pointed by references */
-#define H5O_COPY_WITHOUT_ATTR_FLAG          (0x0010u) /* Copy object without copying attributes */
-#define H5O_COPY_PRESERVE_NULL_FLAG         (0x0020u) /* Copy NULL messages (empty space) */
-#define H5O_COPY_MERGE_COMMITTED_DTYPE_FLAG (0x0040u) /* Merge committed datatypes in dest file */
-#define H5O_COPY_ALL                        (0x007Fu) /* All object copying flags (for internal checking) */
+#define H5O_COPY_SHALLOW_HIERARCHY_FLAG     (0x0001u) /**< Copy only immediate members */
+#define H5O_COPY_EXPAND_SOFT_LINK_FLAG      (0x0002u) /**< Expand soft links into new objects */
+#define H5O_COPY_EXPAND_EXT_LINK_FLAG       (0x0004u) /**< Expand external links into new objects */
+#define H5O_COPY_EXPAND_REFERENCE_FLAG      (0x0008u) /**< Copy objects that are pointed by references */
+#define H5O_COPY_WITHOUT_ATTR_FLAG          (0x0010u) /**< Copy object without copying attributes */
+#define H5O_COPY_PRESERVE_NULL_FLAG         (0x0020u) /**< Copy NULL messages (empty space) */
+#define H5O_COPY_MERGE_COMMITTED_DTYPE_FLAG (0x0040u) /**< Merge committed datatypes in dest file */
+#define H5O_COPY_ALL                        (0x007Fu) /**< All object copying flags (for internal checking) */
 
 /* Flags for shared message indexes.
  * Pass these flags in using the mesg_type_flags parameter in
@@ -51,25 +51,27 @@
  * but we need to assign each kind of message to a different bit so that
  * one index can hold multiple types.)
  */
-#define H5O_SHMESG_NONE_FLAG    0x0000                  /* No shared messages */
-#define H5O_SHMESG_SDSPACE_FLAG ((unsigned)1 << 0x0001) /* Simple Dataspace Message.  */
-#define H5O_SHMESG_DTYPE_FLAG   ((unsigned)1 << 0x0003) /* Datatype Message.  */
-#define H5O_SHMESG_FILL_FLAG    ((unsigned)1 << 0x0005) /* Fill Value Message. */
-#define H5O_SHMESG_PLINE_FLAG   ((unsigned)1 << 0x000b) /* Filter pipeline message.  */
-#define H5O_SHMESG_ATTR_FLAG    ((unsigned)1 << 0x000c) /* Attribute Message.  */
+#define H5O_SHMESG_NONE_FLAG    0x0000                  /**< No shared messages */
+#define H5O_SHMESG_SDSPACE_FLAG ((unsigned)1 << 0x0001) /**< Simple Dataspace Message.  */
+#define H5O_SHMESG_DTYPE_FLAG   ((unsigned)1 << 0x0003) /**< Datatype Message.  */
+#define H5O_SHMESG_FILL_FLAG    ((unsigned)1 << 0x0005) /**< Fill Value Message. */
+#define H5O_SHMESG_PLINE_FLAG   ((unsigned)1 << 0x000b) /**< Filter pipeline message.  */
+#define H5O_SHMESG_ATTR_FLAG    ((unsigned)1 << 0x000c) /**< Attribute Message.  */
 #define H5O_SHMESG_ALL_FLAG                                                                                  \
     (H5O_SHMESG_SDSPACE_FLAG | H5O_SHMESG_DTYPE_FLAG | H5O_SHMESG_FILL_FLAG | H5O_SHMESG_PLINE_FLAG |        \
      H5O_SHMESG_ATTR_FLAG)
 
+/* clang-format off */
 /* Object header status flag definitions */
-#define H5O_HDR_CHUNK0_SIZE             0x03 /* 2-bit field indicating # of bytes to store the size of chunk 0's data */
-#define H5O_HDR_ATTR_CRT_ORDER_TRACKED  0x04 /* Attribute creation order is tracked */
-#define H5O_HDR_ATTR_CRT_ORDER_INDEXED  0x08 /* Attribute creation order has index */
-#define H5O_HDR_ATTR_STORE_PHASE_CHANGE 0x10 /* Non-default attribute storage phase change values stored */
-#define H5O_HDR_STORE_TIMES             0x20 /* Store access, modification, change & birth times for object */
+#define H5O_HDR_CHUNK0_SIZE             0x03 /**< 2-bit field indicating # of bytes to store the size of chunk 0's data */
+#define H5O_HDR_ATTR_CRT_ORDER_TRACKED  0x04 /**< Attribute creation order is tracked */
+#define H5O_HDR_ATTR_CRT_ORDER_INDEXED  0x08 /**< Attribute creation order has index */
+#define H5O_HDR_ATTR_STORE_PHASE_CHANGE 0x10 /**< Non-default attribute storage phase change values stored */
+#define H5O_HDR_STORE_TIMES             0x20 /**< Store access, modification, change & birth times for object */
 #define H5O_HDR_ALL_FLAGS                                                                                    \
     (H5O_HDR_CHUNK0_SIZE | H5O_HDR_ATTR_CRT_ORDER_TRACKED | H5O_HDR_ATTR_CRT_ORDER_INDEXED |                 \
      H5O_HDR_ATTR_STORE_PHASE_CHANGE | H5O_HDR_STORE_TIMES)
+/* clang-format on */
 
 /* Maximum shared message values.  Number of indexes is 8 to allow room to add
  * new types of messages.
@@ -81,11 +83,11 @@
  * Theses flags determine which fields will be filled in in the H5O_info_t
  * struct.
  */
-#define H5O_INFO_BASIC     0x0001u /* Fill in the fileno, addr, type, and rc fields */
-#define H5O_INFO_TIME      0x0002u /* Fill in the atime, mtime, ctime, and btime fields */
-#define H5O_INFO_NUM_ATTRS 0x0004u /* Fill in the num_attrs field */
-#define H5O_INFO_HDR       0x0008u /* Fill in the hdr field */
-#define H5O_INFO_META_SIZE 0x0010u /* Fill in the meta_size field */
+#define H5O_INFO_BASIC     0x0001u /**< Fill in the fileno, addr, type, and rc fields */
+#define H5O_INFO_TIME      0x0002u /**< Fill in the atime, mtime, ctime, and btime fields */
+#define H5O_INFO_NUM_ATTRS 0x0004u /**< Fill in the num_attrs field */
+#define H5O_INFO_HDR       0x0008u /**< Fill in the hdr field */
+#define H5O_INFO_META_SIZE 0x0010u /**< Fill in the meta_size field */
 #define H5O_INFO_ALL       (H5O_INFO_BASIC | H5O_INFO_TIME | H5O_INFO_NUM_ATTRS | H5O_INFO_HDR | H5O_INFO_META_SIZE)
 
 /*******************/
@@ -144,11 +146,10 @@ typedef struct H5O_info_t {
     time_t         btime;     /**< Birth time            */
     hsize_t        num_attrs; /**< # of attributes attached to object */
     H5O_hdr_info_t hdr;       /**< Object header information */
-    /* Extra metadata storage for obj & attributes */
     struct {
         H5_ih_info_t obj;  /**< v1/v2 B-tree & local/fractal heap for groups, B-tree for chunked datasets */
         H5_ih_info_t attr; /**< v2 B-tree & heap for attributes */
-    } meta_size;
+    } meta_size;           /**< Extra metadata storage for obj & attributes */
 } H5O_info_t;
 //! <!-- [H5O_info_t_snip] -->
 
@@ -160,6 +161,17 @@ typedef uint32_t H5O_msg_crt_idx_t;
 //! <!-- [H5O_iterate_t_snip] -->
 /**
  * Prototype for H5Ovisit(), H5Ovisit_by_name() operator (version 3)
+ *
+ * \param[in] obj Object that serves as the root of the iteration;
+ *                the same value as the H5Ovisit() \c obj_id parameter
+ * \param[in] name Name of object, relative to \p obj, being examined at current
+ *                 step of the iteration
+ * \param[out] info Information about that object
+ * \param[in,out] op_data User-defined pointer to data required by the application
+ *                        in processing the object; a pass-through of the \c op_data
+ *                        pointer provided with the H5Ovisit3() function call
+ * \return \herr_t_iter
+ *
  */
 typedef herr_t (*H5O_iterate_t)(hid_t obj, const char *name, const H5O_info_t *info, void *op_data);
 //! <!-- [H5O_iterate_t_snip] -->
@@ -448,8 +460,7 @@ H5_DLL htri_t H5Oexists_by_name(hid_t loc_id, const char *name, hid_t lapl_id);
  * \return \herr_t
  *
  * \details H5Oget_info2() specifies an object by its identifier, \p loc_id , and
- *          retrieves the metadata describing that object in \p oinfo , an H5O_info1_t \c struct.
- *          This \c struct type is described in H5Oget_info1().
+ *          retrieves the metadata describing that object in \p oinfo.
  *
  *          The \p fields parameter contains flags to determine which fields will be filled in
  *          the H5O_info1_t \c struct returned in \p oinfo.
@@ -457,6 +468,11 @@ H5_DLL htri_t H5Oexists_by_name(hid_t loc_id, const char *name, hid_t lapl_id);
  *
  *          \obj_info_fields
  *
+ * \par Example
+ *      An example snippet from examples/h5_attribute.c:
+ * \par
+ *      \snippet h5_attribute.c H5Oget_info2_snip
+ *
  * \note If you are iterating through a lot of different objects to
  *       retrieve information via the H5Oget_info() family of routines,
  *       you may see memory building up. This can be due to memory
@@ -477,8 +493,8 @@ H5_DLL herr_t H5Oget_info2(hid_t loc_id, H5O_info_t *oinfo, unsigned fields);
  *-------------------------------------------------------------------------
  * \ingroup H5O
  *
- * \brief Retrieves the metadata for an object, identifying the object
- *        by location and relative name
+ * \brief Retrieves the metadata for an object, identifying the object by
+ *        location and relative name
  *
  * \fgdta_loc_obj_id{loc_id}
  * \param[in] name Name of group, relative to \p loc_id
@@ -488,20 +504,17 @@ H5_DLL herr_t H5Oget_info2(hid_t loc_id, H5O_info_t *oinfo, unsigned fields);
  *
  * \return \herr_t
  *
- * \details H5Oget_info_by_name2() specifies an object’s location and name, \p loc_id and
- *          \p name, respectively, and retrieves the metadata describing
- *          that object in \p oinfo, an H5O_info1_t \c struct.
+ * \details H5Oget_info_by_name2() specifies an object’s location and name,
+ *          \p loc_id and \p name, respectively, and retrieves the metadata
+ *          describing that object in \p oinfo, an H5O_info1_t struct.
  *
- *          The \c struct H5O_info1_t is defined in H5Opublic.h and described
- *          in the H5Oget_info1() function entry.
- *
- *          The \p fields parameter contains flags to determine which fields
- *          will be filled in in the H5O_info1_t \c struct returned in
- *          \p oinfo. These flags are defined in the H5Opublic.h file:
+ *          The \p fields parameter contains flags to determine which fields will be filled in
+ *          the H5O_info1_t \c struct returned in \p oinfo.
+ *          These flags are defined in the H5Opublic.h file:
  *
  *          \obj_info_fields
  *
- *          The link access property list, \p lapl_id, is not currently used;
+ *          The link access property list, \c lapl_id, is not currently used;
  *          it should be passed in as #H5P_DEFAULT.
  *
  * \since 1.10.3
@@ -509,6 +522,7 @@ H5_DLL herr_t H5Oget_info2(hid_t loc_id, H5O_info_t *oinfo, unsigned fields);
  */
 H5_DLL herr_t H5Oget_info_by_name2(hid_t loc_id, const char *name, H5O_info_t *oinfo, unsigned fields,
                                    hid_t lapl_id);
+
 /**
  *-------------------------------------------------------------------------
  * \ingroup H5O
@@ -520,7 +534,7 @@ H5_DLL herr_t H5Oget_info_by_name2(hid_t loc_id, const char *name, H5O_info_t *o
  * \param[in] group_name Name of group in which object is located
  * \idx_type
  * \order
- * \param[in]  n Position within the index
+ * \param[in] n Position within the index
  * \param[out] oinfo Buffer in which to return object information
  * \param[in] fields Flags specifying the fields to include in \p oinfo
  * \lapl_id
@@ -534,15 +548,11 @@ H5_DLL herr_t H5Oget_info_by_name2(hid_t loc_id, const char *name, H5O_info_t *o
  *          index is to be traversed, \p order, and an object’s position
  *          \p n within that index.
  *
- *          \p oinfo, in which the object information is returned, is a \c struct of
- *          type H5O_info1_t.  This and other \c struct types used
- *          by H5Oget_info_by_idx2() are described in H5Oget_info_by_idx1().
- *
  *          If \p loc_id fully specifies the group in which the object resides,
- *          i\p group_name can be a dot (\c .).
+ *          \p group_name can be a dot (\c .).
  *
- *          The \p fields parameter contains flags to determine which fields will be
- *          filled in the H5O_info1_t \c struct returned in \p oinfo.
+ *          The \p fields parameter contains flags to determine which fields will be filled in
+ *          the H5O_info1_t \c struct returned in \p oinfo.
  *          These flags are defined in the H5Opublic.h file:
  *          \obj_info_fields
  *
@@ -991,9 +1001,9 @@ H5_DLL ssize_t H5Oget_comment_by_name(hid_t loc_id, const char *name, char *comm
  * \details H5Ovisit2() is a recursive iteration function to visit the
  *          object \p obj_id and, if \p obj_id is a group, all objects in
  *          and below it in an HDF5 file, thus providing a mechanism for
- *          an application to perform a common set of operations across all
- *          of those objects or a dynamically selected subset. For
- *          non-recursive iteration across the members of a group,
+ *          an application to perform a common set of operations across
+ *          all of those objects or a dynamically selected subset.
+ *          For non-recursive iteration across the members of a group,
  *          see H5Literate1().
  *
  *          If \p obj_id is a group identifier, that group serves as the
@@ -1011,11 +1021,8 @@ H5_DLL ssize_t H5Oget_comment_by_name(hid_t loc_id, const char *name, char *comm
  *          a group 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
- *
+ *          unnecessary, so the iteration may begin more quickly.
+
  *          Note that the index type passed in \p idx_type is a
  *          <em>best effort</em> setting. If the application passes in
  *          a value indicating iteration in creation order and a group is
@@ -1025,52 +1032,7 @@ H5_DLL ssize_t H5Oget_comment_by_name(hid_t loc_id, const char *name, char *comm
  *          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 prototype of the callback function op is as follows (as
- *          defined in the source code file H5Opublic.h):
- *
- *          \snippet this H5O_iterate1_t_snip
- *
- *          The parameters of this callback function have the following values
- *          or meanings:
- *          <table>
- *          <tr>
- *              <td>\c obj</td>
- *              <td>Object that serves as root of the iteration;
- *                  same value as the H5Ovisit1() \p obj_id parameter</td>
- *          </tr>
- *          <tr>
- *          <td>\c name</td>
- *          <td>Name of object, relative to \c obj, being examined at
- *              current step of the iteration</td>
- *          </tr>
- *          <tr>
- *              <td>\c info</td>
- *              <td>H5O_info1_t \c struct containing information
- *                  regarding that object</td>
- *          </tr>
- *          <tr>
- *              <td>\c op_data</td>
- *              <td>User-defined pointer to data required by the application in
- *                  processing the object; a pass-through of the \c op_data pointer
- *                  provided with the H5Ovisit() function call</td>
- *          </tr>
- *          </table>
- *
- *          The H5O_info1_t \c struct is defined in H5Opublic.h and
- *          described in the H5Oget_info1() function entry.
- *
- *          The return values from an operator are:
- *          - Zero causes the visit iterator to continue, returning zero when all
- *            group members have been processed.
- *          - A positive value causes the visit iterator to immediately return that
- *            positive value, indicating short-circuit success.
- *          - A negative value causes the visit iterator to immediately return that
- *            value, indicating failure.
+ *          along the index specified in \p idx_type.
  *
  *          The H5Ovisit2() \p op_data parameter is a user-defined pointer to the data
  *          required to process objects in the course of the iteration. This pointer
@@ -1117,11 +1079,12 @@ H5_DLL ssize_t H5Oget_comment_by_name(hid_t loc_id, const char *name, char *comm
  */
 H5_DLL herr_t H5Ovisit2(hid_t obj_id, H5_index_t idx_type, H5_iter_order_t order, H5O_iterate_t op,
                         void *op_data, unsigned fields);
+
 /**
  *-------------------------------------------------------------------------
  * \ingroup H5O
  *
- * \brief Recursively visits all objects starting from a specified object
+ * \brief Recursively visits all objects accessible from a specified object
  *
  * \fgdta_loc_obj_id{loc_id}
  * \param[in] obj_name Name of the object, generally relative to
@@ -1150,7 +1113,7 @@ H5_DLL herr_t H5Ovisit2(hid_t obj_id, H5_index_t idx_type, H5_iter_order_t order
  *          in an HDF5 file, thus providing a mechanism for an application to
  *          perform a common set of operations across all of those objects or
  *          a dynamically selected subset. For non-recursive iteration across
- *          the members of a group, see #H5Literate.
+ *          the members of a group, see H5Literate().
  *
  *          The object serving as the root of the iteration is specified
  *          by the \p loc_id / \p obj_name parameter pair. \p loc_id specifies
@@ -1162,7 +1125,7 @@ H5_DLL herr_t H5Ovisit2(hid_t obj_id, H5_index_t idx_type, H5_iter_order_t order
  *          as the root of the iteration, \p obj_name should be '\c .' (a dot).
  *          (Note that when \p loc_id fully specifies the object that is to serve
  *          as the root of the iteration, the user may wish to consider
- *          using H5Ovisit2() instead of #H5Ovisit_by_name.)
+ *          using H5Ovisit2() instead of H5Ovisit_by_name().)
  *
  *          Two parameters are used to establish the iteration: \p idx_type
  *          and \p order.
@@ -1174,8 +1137,6 @@ H5_DLL herr_t H5Ovisit2(hid_t obj_id, H5_index_t idx_type, H5_iter_order_t order
  *          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
  *          <em>best effort</em> setting. If the application passes in a
  *          value indicating iteration in creation order and a group is
@@ -1185,17 +1146,7 @@ H5_DLL herr_t H5Ovisit2(hid_t obj_id, H5_index_t idx_type, H5_iter_order_t 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 and the effect of the callback
- *          function’s return value on the application are described
- *          in H5Ovisit2().
- *
- *          The H5O_info1_t \c struct is defined in H5Opublic.h
- *          and described in the H5Oget_info1() function entry.
+ *          along the index specified in \p idx_type.
  *
  *          The H5Ovisit_by_name2() \p op_data parameter is a user-defined
  *          pointer to the data required to process objects in the course
@@ -1215,7 +1166,7 @@ H5_DLL herr_t H5Ovisit2(hid_t obj_id, H5_index_t idx_type, H5_iter_order_t order
  *          in the H5Opublic.h file:
  *          \obj_info_fields
  *
- *          #H5Lvisit_by_name and #H5Ovisit_by_name are companion
+ *          H5Lvisit_by_name() and H5Ovisit_by_name() 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
@@ -1247,6 +1198,7 @@ H5_DLL herr_t H5Ovisit2(hid_t obj_id, H5_index_t idx_type, H5_iter_order_t order
 H5_DLL herr_t H5Ovisit_by_name2(hid_t loc_id, const char *obj_name, H5_index_t idx_type,
                                 H5_iter_order_t order, H5O_iterate_t op, void *op_data, unsigned fields,
                                 hid_t lapl_id);
+
 /**
  *-------------------------------------------------------------------------
  * \ingroup H5O
@@ -1295,32 +1247,16 @@ H5_DLL herr_t H5Oclose(hid_t object_id);
  *       files. After that, the OS is responsible for ensuring that
  *       the data is actually flushed to disk.
  *
- * \par See Also:
- *      - H5Dflush()
- *      - H5Drefresh()
- *      - H5Oflush()
- *      - H5Grefresh()
- *      - H5Oflush()
- *      - H5Orefresh()
- *      - H5Tflush()
- *      - H5Trefresh()
- * \par
- *      - \c H5DOappend()
- *      - H5Fstart_swmr_write()
- *      - H5Pget_append_flush()
- *      - H5Pget_object_flush_cb()
- *      - H5Pset_append_flush()
- *      - H5Pset_object_flush_cb()
- * \par
- *      - H5Oare_mdc_flushes_disabled()
- *      - H5Odisable_mdc_flushes()
- *      - H5Oenable_mdc_flushes()
+ * \see H5Dflush(), H5Drefresh(), H5Oflush(), H5Grefresh(), H5Oflush(),
+ *      H5Orefresh(), H5Tflush(), H5Trefresh()
+ * \see H5DOappend(), H5Fstart_swmr_write(), H5Pget_append_flush(),
+ *      H5Pget_object_flush_cb(), H5Pset_append_flush(), H5Pset_object_flush_cb()
+ * \see H5Oare_mdc_flushes_disabled(), H5Odisable_mdc_flushes(), H5Oenable_mdc_flushes()
  *
  * \since 1.10.0
  *
  */
 H5_DLL herr_t H5Oflush(hid_t obj_id);
-
 /**
  *-------------------------------------------------------------------------
  * \ingroup H5O
@@ -1373,21 +1309,17 @@ H5_DLL herr_t H5Orefresh(hid_t oid);
  *          HDF5 object level (datasets, groups, committed datatypes)
  *          and the entire metadata cache level.
  *
- * \note HDF5 objects include datasets, groups, and committed datatypes.
- *       Only #hid_t identifiers that represent these objects can be passed to the function.
- * \note Passing in a #hid_t identifier that represents any other HDF5 entity is
- *       considered an error.
- * \note It is an error to pass an HDF5 file identifier
- *       (obtained from H5Fopen() or H5Fcreate())
- *       to this function.
- * \note Misuse of this function can cause the cache to exhaust
- *       available memory.
- * \note Objects can be returned to the default automatic flush behavior
- *       with H5Oenable_mdc_flushes().
- * \note Flush prevention only pertains to new or dirty metadata entries.
- *       Clean entries can be evicted from the cache.
- * \note Calling this function on an object that has already had flushes
- *       disabled will return an error.
+ * \note HDF5 objects include datasets, groups, and committed datatypes.  Only
+ *       #hid_t identifiers that represent these objects can be passed to the
+ *       function.  Passing in a #hid_t identifier that represents any other
+ *       HDF5 entity is considered an error.  It is an error to pass an HDF5
+ *       file identifier (obtained from H5Fopen() or H5Fcreate()) to this
+ *       function.  Misuse of this function can cause the cache to exhaust
+ *       available memory.  Objects can be returned to the default automatic
+ *       flush behavior with H5Oenable_mdc_flushes().  Flush prevention only
+ *       pertains to new or dirty metadata entries.  Clean entries can be
+ *       evicted from the cache.  Calling this function on an object that has
+ *       already had flushes disabled will return an error.
  *
  * \since 1.10.0
  *
@@ -1417,28 +1349,18 @@ H5_DLL herr_t H5Odisable_mdc_flushes(hid_t object_id);
  *          metadata cache level.
  *
  *
- * \note HDF5 objects include datasets, groups, and committed datatypes.
- *       Only #hid_t identifiers that represent these objects can be
- *       passed to the function.
- *
- * \note Passing in a #hid_t identifier that represents any other HDF5 entity
- *       is considered an error.
- *
- * \note It is an error to pass an HDF5 file identifier
- *       (obtained from H5Fopen() or H5Fcreate())
- *       to this function.
- *
- * \note Using this function on an object that has not had flushes disabled
- *       is considered an error. The state of an object can be determined
- *       with H5Oare_mdc_flushes_disabled().
- *
- * \note An object will be returned to the default flush algorithm when it is closed.
- *
- * \note All objects will be returned to the default flush algorithm when
- *       the file is closed.
- *
- * \note An object’s entries will not necessarily be flushed as a result of
- *       calling this function.
+ * \note HDF5 objects include datasets, groups, and committed datatypes.  Only
+ *       #hid_t identifiers that represent these objects can be passed to the
+ *       function.  Passing in a #hid_t identifier that represents any other
+ *       HDF5 entity is considered an error.  It is an error to pass an HDF5
+ *       file identifier (obtained from H5Fopen() or H5Fcreate()) to this
+ *       function.  Using this function on an object that has not had flushes
+ *       disabled is considered an error. The state of an object can be
+ *       determined with H5Oare_mdc_flushes_disabled().  An object will be
+ *       returned to the default flush algorithm when it is closed.  All objects
+ *       will be returned to the default flush algorithm when the file is
+ *       closed.  An object’s entries will not necessarily be flushed as a
+ *       result of calling this function.
  *
  * \since 1.10.0
  *
@@ -1480,7 +1402,6 @@ H5_DLL herr_t H5Oenable_mdc_flushes(hid_t object_id);
  */
 H5_DLL herr_t H5Oare_mdc_flushes_disabled(hid_t object_id, hbool_t *are_disabled);
 
-/* Future function prototypes to be deprecated in next version */
 /**
  *-------------------------------------------------------------------------
  * \ingroup H5O
@@ -1489,19 +1410,11 @@ H5_DLL herr_t H5Oare_mdc_flushes_disabled(hid_t object_id, hbool_t *are_disabled
  *
  * \fgdta_loc_obj_id{loc_id}
  * \param[out] oinfo Buffer in which to return object information
- * \param[in] fields Flags specifying the fields to include in \p oinfo
  *
  * \return \herr_t
  *
  * \details H5Oget_info specifies an object by its identifier, \p loc_id , and
- *          retrieves the metadata describing that object in \p oinfo , an H5O_info_t \c struct.
- *          This \c struct type is described in H5Oget_info().
- *
- *          The \p fields parameter contains flags to determine which fields will be filled in
- *          the H5O_info_t \c struct returned in \p oinfo.
- *          These flags are defined in the H5Opublic.h file:
- *
- *          \obj_info_fields
+ *          retrieves the metadata describing that object in \p oinfo.
  *
  * \note If you are iterating through a lot of different objects to
  *       retrieve information via the H5Oget_info() family of routines,
@@ -1529,24 +1442,17 @@ H5_DLL herr_t H5Oget_info(hid_t loc_id, H5O_info_t *oinfo);
  * \fgdta_loc_obj_id{loc_id}
  * \param[in] name Name of group, relative to \p loc_id
  * \param[out] oinfo Buffer in which to return object information
- * \param[in] fields Flags specifying the fields to include in \p oinfo
  * \lapl_id
  *
  * \return \herr_t
  *
- * \details H5Oget_info_by_name() specifies an object’s location and name, \p loc_id and
- *          \p name, respectively, and retrieves the metadata describing
- *          that object in \p oinfo, an H5O_info1_t \c struct.
+ * \details H5Oget_info_by_name() specifies an object’s location and name, \p loc_id
+ *          and \p name, respectively, and retrieves the metadata describing that object
+ *          in \p oinfo, an H5O_info1_t \c struct.
  *
  *          The \c struct H5O_info_t is defined in H5Opublic.h and described
  *          in the H5Oget_info() function entry.
  *
- *          The \p fields parameter contains flags to determine which fields
- *          will be filled in in the H5O_info_t \c struct returned in
- *          \p oinfo. These flags are defined in the H5Opublic.h file:
- *
- *          \obj_info_fields
- *
  *          The link access property list, \p lapl_id, is not currently used;
  *          it should be passed in as #H5P_DEFAULT.
  *
@@ -1565,9 +1471,8 @@ H5_DLL herr_t H5Oget_info_by_name(hid_t loc_id, const char *name, H5O_info_t *oi
  * \param[in] group_name Name of group in which object is located
  * \idx_type
  * \order
- * \param[in]  n Position within the index
+ * \param[in] n Position within the index
  * \param[out] oinfo Buffer in which to return object information
- * \param[in] fields Flags specifying the fields to include in \p oinfo
  * \lapl_id
  *
  * \return \herr_t
@@ -1579,17 +1484,8 @@ H5_DLL herr_t H5Oget_info_by_name(hid_t loc_id, const char *name, H5O_info_t *oi
  *          index is to be traversed, \p order, and an object’s position
  *          \p n within that index.
  *
- *          \p oinfo, in which the object information is returned, is a \c struct of
- *          type H5O_info1_t.  This and other \c struct types used
- *          by H5Oget_info_by_idx() are described in H5Oget_info_by_idx1().
- *
  *          If \p loc_id fully specifies the group in which the object resides,
- *          i\p group_name can be a dot (\c .).
- *
- *          The \p fields parameter contains flags to determine which fields will be
- *          filled in the H5O_info_t \c struct returned in \p oinfo.
- *          These flags are defined in the H5Opublic.h file:
- *          \obj_info_fields
+ *          \p group_name can be a dot (\c .).
  *
  *          The link access property list, \c lapl_id, is not currently used;
  *          it should be passed in as #H5P_DEFAULT.
@@ -1808,10 +1704,7 @@ H5_DLL herr_t H5Oget_info_by_idx1(hid_t loc_id, const char *group_name, H5_index
  *          a group 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
+ *          unnecessary, so the iteration may begin more quickly.
  *
  *          Note that the index type passed in \p idx_type is a
  *          <em>best effort</em> setting. If the application passes in
@@ -1822,56 +1715,7 @@ H5_DLL herr_t H5Oget_info_by_idx1(hid_t loc_id, const char *group_name, H5_index
  *          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 prototype of the callback function op is as follows (as
- *          defined in the source code file H5Opublic.h):
- *
- *          \snippet this H5O_iterate1_t_snip
- *
- *          The parameters of this callback function have the following values
- *          or meanings:
- *          <table>
- *          <tr>
- *              <td>\c obj</td>
- *              <td>Object that serves as root of the iteration;
- *                  same value as the H5Ovisit1() \p obj_id parameter</td>
- *          </tr>
- *          <tr>
- *          <td>\c name</td>
- *          <td>Name of object, relative to \c obj, being examined at
- *              current step of the iteration</td>
- *          </tr>
- *          <tr>
- *              <td>\c info</td>
- *              <td>H5O_info1_t \c struct containing information
- *                  regarding that object</td>
- *          </tr>
- *          <tr>
- *              <td>\c op_data</td>
- *              <td>User-defined pointer to data required by the application in
- *                  processing the object</td>
- *          </tr>
- *          </table>
- *
- *          The H5O_info1_t \c struct is defined in H5Opublic.h:
- *          \snippet this H5O_info1_t_snip
- *
- *          The return values from an operator are:
- *          - Zero causes the visit iterator to continue, returning zero when all
- *            group members have been processed.
- *          - A positive value causes the visit iterator to immediately return that
- *            positive value, indicating short-circuit success.
- *          - A negative value causes the visit iterator to immediately return that
- *            value, indicating failure.
- *
- *          The H5Ovisit1() \p op_data parameter is a user-defined pointer to the data
- *          required to process objects 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.
+ *          along the index specified in \p idx_type.
  *
  *          H5Lvisit1() and H5Ovisit1() are companion functions: one for
  *          examining and operating on links; the other for examining
@@ -1967,10 +1811,7 @@ H5_DLL herr_t H5Ovisit1(hid_t obj_id, H5_index_t idx_type, H5_iter_order_t order
  *          a group 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
+ *          unnecessary, so the iteration may begin more quickly.
  *
  *          Note that the index type passed in \p idx_type is a
  *          <em>best effort</em> setting. If the application passes in a
@@ -1981,10 +1822,7 @@ H5_DLL herr_t H5Ovisit1(hid_t obj_id, H5_index_t idx_type, H5_iter_order_t 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
+ *          along the index specified in \p idx_type.
  *
  *          The \p op callback function and the effect of the callback
  *          function’s return value on the application are described
diff --git a/src/H5PLmodule.h b/src/H5PLmodule.h
index ab9f1d5..a093096 100644
--- a/src/H5PLmodule.h
+++ b/src/H5PLmodule.h
@@ -28,8 +28,34 @@
 #define H5_MY_PKG_INIT YES
 
 /**\defgroup H5PL H5PL
- * \brief Plugins
- * \todo Describe what programmatically controlling dynamically loaded plugins (H5PL) is all about
+ *
+ * Use the functions in this module to manage the loading behavior of HDF5
+ * plugins.
+ *
+ * <table>
+ * <tr><th>Create</th><th>Read</th></tr>
+ * <tr valign="top">
+ *   <td>
+ *   \snippet H5PL_examples.c create
+ *   </td>
+ *   <td>
+ *   \snippet H5PL_examples.c read
+ *   </td>
+ * <tr><th>Update</th><th>Delete</th></tr>
+ * <tr valign="top">
+ *   <td>
+ *   \snippet H5PL_examples.c update
+ *   </td>
+ *   <td>
+ *   \snippet H5PL_examples.c delete
+ *   </td>
+ * </tr>
+ * </table>
+ *
+ * \attention The loading behavior of HDF5 plugins can be controlled via the
+ *            functions described below and certain environment variables, such
+ *            as \c HDF5_PLUGIN_PRELOAD  and \c HDF5_PLUGIN_PATH.
+ *
  */
 
 #endif /* H5PLmodule_H */
diff --git a/src/H5Pmodule.h b/src/H5Pmodule.h
index 18f30c6..3c28615 100644
--- a/src/H5Pmodule.h
+++ b/src/H5Pmodule.h
@@ -30,49 +30,162 @@
 #define H5_MY_PKG_INIT YES
 
 /**\defgroup H5P H5P
- * \brief Property List Interface
  *
- * \details The HDF5 Property List Interface provides a mechanism to take
- *          advantage of more powerful or unusual features in HDF5.
+ * Use the functions in this module to manage HDF5 property lists and property
+ * list classes. HDF5 property lists are the main vehicle to configure the
+ * behavior of HDF5 API functions.
  *
- *          HDF5 objects have properties or characteristics associated with
- *          them, and there are default properties that handle the most
- *          common needs. These default properties can be modified using the
- *          HDF5 Property List Interface. For example, the data storage
- *          layout property of a dataset is contiguous by default. For better
- *          performance, the layout can be modified to be chunked or chunked
- *          and compressed.
+ * Typically, property lists are created by instantiating one of the built-in
+ * or user-defined property list classes. After adding suitable properties,
+ * property lists are used when opening or creating HDF5 items, or when reading
+ * or writing data. Property lists can be modified by adding or changing
+ * properties. Property lists are deleted by closing the associated handles.
  *
- * \todo Describe concisely what the functions in this module are about.
+ * <table>
+ * <tr><th>Create</th><th>Read</th></tr>
+ * <tr valign="top">
+ *   <td>
+ *   \snippet{lineno} H5P_examples.c create
+ *   </td>
+ *   <td>
+ *   \snippet{lineno} H5P_examples.c read
+ *   </td>
+ * <tr><th>Update</th><th>Delete</th></tr>
+ * <tr valign="top">
+ *   <td>
+ *   \snippet{lineno} H5P_examples.c update
+ *   </td>
+ *   <td>
+ *   \snippet{lineno} H5P_examples.c delete
+ *   </td>
+ * </tr>
+ * </table>
  *
- * \defgroup GPLO General Property List Operations
+ * \defgroup ALCAPL Attribute and Link Creation Properties
  * \ingroup H5P
- * \defgroup GPLOA General Property List Operations (Advanced)
+ * Currently, there are only two creation properties that you can use to control
+ * the creation of HDF5 attributes and links. The first creation property, the
+ * choice of a character encoding, applies to both attributes and links.
+ * The second creation property applies to links only, and advises the library
+ * to automatically create missing intermediate groups when creating new objects.
+ *
+ * \defgroup DAPL Dataset Access Properties
  * \ingroup H5P
- * \defgroup FCPL File Creation Properties
+ * Use dataset access properties to modify the default behavior of the HDF5
+ * library when accessing datasets. The properties include adjusting the size
+ * of the chunk cache, providing prefixes for external content and virtual
+ * dataset file paths, and controlling flush behavior, etc. These properties
+ * are \Emph{not} persisted with datasets, and can be adjusted at runtime before
+ * a dataset is created or opened.
+ *
+ * \defgroup DCPL Dataset Creation Properties
+ * \ingroup H5P
+ * Use dataset creation properties to control aspects of dataset creation such
+ * as fill time, storage layout, compression methods, etc.
+ * Unlike dataset access and transfer properties, creation properties \Emph{are}
+ * stored with the dataset, and cannot be changed once a dataset has been
+ * created.
+ *
+ * \defgroup DXPL Dataset Transfer Properties
  * \ingroup H5P
+ * Use dataset transfer properties to customize certain aspects of reading
+ * and writing datasets such as transformations, MPI-IO I/O mode, error
+ * detection, etc. These properties are \Emph{not} persisted with datasets,
+ * and can be adjusted at runtime before a dataset is read or written.
+ *
  * \defgroup FAPL File Access Properties
  * \ingroup H5P
- * \defgroup GCPL Group Creation Properties
+ * Use file access properties to modify the default behavior of the HDF5
+ * library when accessing files. The properties include selecting a virtual
+ * file driver (VFD), configuring the metadata cache (MDC), control
+ * file locking, etc. These properties are \Emph{not} persisted with files, and
+ * can be adjusted at runtime before a file is created or opened.
+ *
+ * \defgroup FCPL File Creation Properties
  * \ingroup H5P
- * \defgroup ALCAPL Attribute and Link Creation Properties
+ * Use file creation properties to control aspects of file creation such
+ * as setting a file space management strategy or creating a user block.
+ * Unlike file access properties, creation properties \Emph{are}
+ * stored with the file, and cannot be changed once a file has been
+ * created.
+ *
+ * \defgroup GAPL General Access Properties
  * \ingroup H5P
- * \defgroup LAPL Link Access Properties
+ * \todo Should this be as standalone page?
+ *
+ * \defgroup GCPL Group Creation Properties
  * \ingroup H5P
- * \defgroup DCPL Dataset Creation Properties
+ * Use group creation properties to control aspects of group creation such
+ * as storage layout, compression, and link creation order tracking.
+ * Unlike file access properties, creation properties \Emph{are}
+ * stored with the group, and cannot be changed once a group has been
+ * created.
+ *
+ * \defgroup GPLO General Property List Operations
  * \ingroup H5P
- * \defgroup DAPL Dataset Access Properties
+ *
+ * Use the functions in this module to manage HDF5 property lists.
+ *
+ * <table>
+ * <tr><th>Create</th><th>Read</th></tr>
+ * <tr valign="top">
+ *   <td>
+ *   \snippet{lineno} H5P_examples.c create
+ *   </td>
+ *   <td>
+ *   \snippet{lineno} H5P_examples.c read
+ *   </td>
+ * <tr><th>Update</th><th>Delete</th></tr>
+ * <tr valign="top">
+ *   <td>
+ *   \snippet{lineno} H5P_examples.c update
+ *   </td>
+ *   <td>
+ *   \snippet{lineno} H5P_examples.c delete
+ *   </td>
+ * </tr>
+ * </table>
+ *
+ * \defgroup GPLOA General Property List Operations (Advanced)
  * \ingroup H5P
- * \defgroup DXPL Dataset Transfer Properties
+ *
+ * You can create and customize user-defined property list classes using the
+ * functions described below. Arbitrary user-defined properties can also
+ * be inserted into existing property lists as so-called temporary properties.
+ *
+ * <table>
+ * <tr><th>Create</th><th>Read</th></tr>
+ *
+ * <tr valign="top">
+ *   <td>
+ *   \snippet{lineno} H5P_examples.c create_class
+ *   </td>
+ *   <td>
+ *   \snippet{lineno} H5P_examples.c read_class
+ *   </td>
+ * <tr><th>Update</th><th>Delete</th></tr>
+ * <tr valign="top">
+ *   <td>
+ *   \snippet{lineno} H5P_examples.c update_class
+ *   </td>
+ *   <td>
+ *   \snippet{lineno} H5P_examples.c delete_class
+ *   </td>
+ * </tr>
+ * </table>
+ *
+ * \defgroup LAPL Link Access Properties
  * \ingroup H5P
+ *
+ *
  * \defgroup OCPL Object Creation Properties
  * \ingroup H5P
+ *
+ *
  * \defgroup OCPPL Object Copy Properties
  * \ingroup H5P
- * \defgroup GACPL General Access Properties
- * \ingroup H5P
- * \defgroup MAPL Map Access Properties
- * \ingroup H5P
+ *
+ *
  */
 
 #endif /* H5Pmodule_H */
diff --git a/src/H5Ppublic.h b/src/H5Ppublic.h
index ca79494..6961c13 100644
--- a/src/H5Ppublic.h
+++ b/src/H5Ppublic.h
@@ -22,16 +22,17 @@
 
 /* Public headers needed by this file */
 #include "H5public.h"
-#include "H5ACpublic.h"
-#include "H5Dpublic.h"
-#include "H5Fpublic.h"
-#include "H5FDpublic.h"
-#include "H5Ipublic.h"
-#include "H5Lpublic.h"
-#include "H5Opublic.h"
-#include "H5MMpublic.h"
-#include "H5Tpublic.h"
-#include "H5Zpublic.h"
+#include "H5ACpublic.h" /* Metadata cache                           */
+#include "H5Dpublic.h"  /* Datasets                                 */
+#include "H5Fpublic.h"  /* Files                                    */
+#include "H5FDpublic.h" /* File drivers                             */
+#include "H5Ipublic.h"  /* ID management                            */
+#include "H5Lpublic.h"  /* Links                                    */
+#include "H5MMpublic.h" /* Memory management                        */
+#include "H5Opublic.h"  /* Object headers                           */
+#include "H5Spublic.h"  /* Dataspaces                               */
+#include "H5Tpublic.h"  /* Datatypes                                */
+#include "H5Zpublic.h"  /* Data filters                             */
 
 /*****************/
 /* Public Macros */
@@ -91,7 +92,9 @@
 #define H5P_CRT_ORDER_TRACKED 0x0001
 #define H5P_CRT_ORDER_INDEXED 0x0002
 
-/* Default value for all property list classes */
+/**
+ * Default value of type \ref hid_t for all property list classes
+ */
 #define H5P_DEFAULT 0 /* (hid_t) */
 
 #ifdef __cplusplus
@@ -104,14 +107,23 @@ extern "C" {
 
 /* Define property list class callback function pointer types */
 //! <!-- [H5P_cls_create_func_t_snip] -->
+/**
+ * \todo Document me!
+ */
 typedef herr_t (*H5P_cls_create_func_t)(hid_t prop_id, void *create_data);
 //! <!-- [H5P_cls_create_func_t_snip] -->
 
 //! <!-- [H5P_cls_copy_func_t_snip] -->
+/**
+ * \todo Document me!
+ */
 typedef herr_t (*H5P_cls_copy_func_t)(hid_t new_prop_id, hid_t old_prop_id, void *copy_data);
 //! <!-- [H5P_cls_copy_func_t_snip] -->
 
 //! <!-- [H5P_cls_close_func_t_snip] -->
+/**
+ * \todo Document me!
+ */
 typedef herr_t (*H5P_cls_close_func_t)(hid_t prop_id, void *close_data);
 //! <!-- [H5P_cls_close_func_t_snip] -->
 
@@ -154,6 +166,9 @@ typedef H5P_prp_cb2_t H5P_prp_delete_func_t;
 typedef H5P_prp_cb1_t H5P_prp_copy_func_t;
 
 //! <!-- [H5P_prp_compare_func_t_snip] -->
+/**
+ * \todo Document me!
+ */
 typedef int (*H5P_prp_compare_func_t)(const void *value1, const void *value2, size_t size);
 //! <!-- [H5P_prp_compare_func_t_snip] -->
 
@@ -161,6 +176,9 @@ typedef H5P_prp_cb1_t H5P_prp_close_func_t;
 
 /* Define property list iteration function type */
 //! <!-- [H5P_iterate_t_snip] -->
+/**
+ * \todo Document me!
+ */
 typedef herr_t (*H5P_iterate_t)(hid_t id, const char *name, void *iter_data);
 //! <!-- [H5P_iterate_t_snip] -->
 
@@ -2171,7 +2189,7 @@ H5_DLL herr_t H5Pset_attr_creation_order(hid_t plist_id, unsigned crt_order_flag
  */
 H5_DLL herr_t H5Pset_attr_phase_change(hid_t plist_id, unsigned max_compact, unsigned min_dense);
 /**
- * \ingroup OCPL
+ * \ingroup DCPL
  *
  * \brief Sets deflate (GNU gzip) compression method and compression level
  *
@@ -2180,6 +2198,8 @@ H5_DLL herr_t H5Pset_attr_phase_change(hid_t plist_id, unsigned max_compact, uns
  *
  * \return \herr_t
  *
+ * \par_compr_note
+ *
  * \details H5Pset_deflate() sets the deflate compression method and the
  *          compression level, \p level, for a dataset or group creation
  *          property list, \p plist_id.
@@ -5113,7 +5133,7 @@ H5_DLL herr_t H5Pset_sieve_buf_size(hid_t fapl_id, size_t size);
 H5_DLL herr_t H5Pset_small_data_block_size(hid_t fapl_id, hsize_t size);
 #ifdef H5_HAVE_PARALLEL
 /**
- * \ingroup GACPL
+ * \ingroup GAPL
  *
  * \brief Sets metadata I/O mode for read operations to collective or independent (default)
  *
@@ -5182,7 +5202,7 @@ H5_DLL herr_t H5Pset_small_data_block_size(hid_t fapl_id, hsize_t size);
  */
 H5_DLL herr_t H5Pset_all_coll_metadata_ops(hid_t plist_id, hbool_t is_collective);
 /**
- * \ingroup GACPL
+ * \ingroup GAPL
  *
  * \brief Retrieves metadata read mode setting
  *
@@ -6132,6 +6152,8 @@ H5_DLL herr_t H5Pset_fill_value(hid_t plist_id, hid_t type_id, const void *value
  *
  * \return \herr_t
  *
+ * \par_compr_note
+ *
  * \details H5Pset_shuffle() sets the shuffle filter, #H5Z_FILTER_SHUFFLE,
  *          in the dataset creation property list \p plist_id. The shuffle
  *          filter de-interlaces a block of data by reordering the bytes.
@@ -6203,6 +6225,8 @@ H5_DLL herr_t H5Pset_layout(hid_t plist_id, H5D_layout_t layout);
  *
  * \return \herr_t
  *
+ * \par_compr_note
+ *
  * \details H5Pset_nbit() sets the N-Bit filter, #H5Z_FILTER_NBIT, in the
  *          dataset creation property list \p plist_id.
  *
@@ -6296,6 +6320,8 @@ H5_DLL herr_t H5Pset_nbit(hid_t plist_id);
  *
  * \return \herr_t
  *
+ * \par_compr_note
+ *
  * \details H5Pset_scaleoffset() sets the scale-offset filter,
  *          #H5Z_FILTER_SCALEOFFSET, for a dataset.
  *
@@ -6405,6 +6431,8 @@ H5_DLL herr_t H5Pset_scaleoffset(hid_t plist_id, H5Z_SO_scale_type_t scale_type,
  *
  * \return \herr_t
  *
+ * \par_compr_note
+ *
  * \details H5Pset_szip() sets an SZIP compression filter, #H5Z_FILTER_SZIP,
  *          for a dataset. SZIP is a compression method designed for use with
  *          scientific data.
@@ -9235,9 +9263,6 @@ H5_DLL herr_t H5Pset_mcdt_search_cb(hid_t plist_id, H5O_mcdt_search_cb_t func, v
  *          The #H5P_prp_cb2_t is as follows:
  *          \snippet this H5P_prp_cb2_t_snip
  *
- *
- * \cpp_c_api_note
- *
  */
 
 /* Function prototypes */
@@ -9351,8 +9376,7 @@ H5_DLL herr_t H5Pregister1(hid_t cls_id, const char *name, size_t size, void *de
  *
  *          The #H5P_prp_cb2_t is as follows:
  *          \snippet this H5P_prp_cb2_t_snip
-
- * \cpp_c_api_note
+ *
  */
 H5_DLL herr_t H5Pinsert1(hid_t plist_id, const char *name, size_t size, void *value,
                          H5P_prp_set_func_t prp_set, H5P_prp_get_func_t prp_get,
diff --git a/src/H5Rmodule.h b/src/H5Rmodule.h
index 2a34d56..fe28bb2 100644
--- a/src/H5Rmodule.h
+++ b/src/H5Rmodule.h
@@ -27,9 +27,32 @@
 
 /**
  * \defgroup H5R H5R
- * \brief Reference Interface
- * \details The HDF5 Reference Interface, H5R, provides a mechanism for managing
- *          HDF5 referenced objects.
+ *
+ * Use the functions in this module to manage HDF5 references. Referents can
+ * be HDF5 objects, attributes, and selections on datasets a.k.a. dataset
+ * regions.
+ *
+ *
+ * <table>
+ * <tr><th>Create</th><th>Read</th></tr>
+ * <tr valign="top">
+ *   <td>
+ *   \snippet{lineno} H5R_examples.c create
+ *   </td>
+ *   <td>
+ *   \snippet{lineno} H5R_examples.c read
+ *   </td>
+ * <tr><th>Update</th><th>Delete</th></tr>
+ * <tr valign="top">
+ *   <td>
+ *   \snippet{lineno} H5R_examples.c update
+ *   </td>
+ *   <td>
+ *   \snippet{lineno} H5R_examples.c delete
+ *   </td>
+ * </tr>
+ * </table>
+ *
  */
 
 #endif /* H5Rmodule_H */
diff --git a/src/H5Rpublic.h b/src/H5Rpublic.h
index 348a7a2..9682bf2 100644
--- a/src/H5Rpublic.h
+++ b/src/H5Rpublic.h
@@ -53,7 +53,7 @@ typedef enum {
     H5R_BADTYPE = (-1), /**< Invalid reference type               */
     H5R_OBJECT,         /**< Object reference                     */
     H5R_DATASET_REGION, /**< Dataset Region Reference             */
-    H5R_MAXTYPE         /**< Highest type (Invalid as true type)  */
+    H5R_MAXTYPE         /**< Highest type (invalid)               */
 } H5R_type_t;
 //! <!-- [H5R_type_t_snip] -->
 
diff --git a/src/H5Smodule.h b/src/H5Smodule.h
index bb33eb8..010f4a6 100644
--- a/src/H5Smodule.h
+++ b/src/H5Smodule.h
@@ -30,29 +30,36 @@
 #define H5_MY_PKG_INIT YES
 
 /**\defgroup H5S H5S
- * \brief Dataspace Interface
  *
- * \details The Dataspace Interface provides functions for creating and
- *          working with dataspaces.
+ * Use the functions in this module to manage HDF5 dataspaces \Emph{and} selections.
  *
- *          A dataspace has two roles:
+ * HDF5 dataspaces describe the \Emph{shape} of datasets in memory or in HDF5
+ * files. Dataspaces can be empty (#H5S_NULL), a singleton (#H5S_SCALAR), or
+ * a multi-dimensional, regular grid (#H5S_SIMPLE). Dataspaces can be re-shaped.
  *
- *          \li It contains the spatial information (logical layout) of a
- *              dataset stored in a file.
- *          \li It describes an application’s data buffers and data elements
- *              participating in I/O. In other words, it can be used to
- *              select a portion or subset of a dataset.
+ * Subsets of dataspaces can be "book-marked" or used to restrict I/O operations
+ * using \Emph{selections}. Furthermore, certain set operations are supported
+ * for selections.
  *
- *          The spatial information of a dataset in a file includes the
- *          rank and dimensions of the dataset, which are a permanent part
- *          of the dataset definition. It can have dimensions that are fixed
- *          (unchanging) or unlimited, which means they can grow in size
- *          (or are extendible).
- *
- *          A dataspace can consist of:
- *          \li  no elements (NULL)
- *          \li  a single element (scalar), or
- *          \li  a simple array.
+ * <table>
+ * <tr><th>Create</th><th>Read</th></tr>
+ * <tr valign="top">
+ *   <td>
+ *   \snippet{lineno} H5S_examples.c create
+ *   </td>
+ *   <td>
+ *   \snippet{lineno} H5S_examples.c read
+ *   </td>
+ * <tr><th>Update</th><th>Delete</th></tr>
+ * <tr valign="top">
+ *   <td>
+ *   \snippet{lineno} H5S_examples.c update
+ *   </td>
+ *   <td>
+ *   \snippet{lineno} H5S_examples.c delete
+ *   </td>
+ * </tr>
+ * </table>
  *
  */
 
diff --git a/src/H5Spublic.h b/src/H5Spublic.h
index e3fe37e..376c3e4 100644
--- a/src/H5Spublic.h
+++ b/src/H5Spublic.h
@@ -21,75 +21,94 @@
 #include "H5public.h"
 #include "H5Ipublic.h"
 
-/* Define atomic datatypes */
-#define H5S_ALL       0 /* (hid_t) */
-#define H5S_UNLIMITED HSIZE_UNDEF
+/* Define special dataspaces for dataset I/O operations */
+#define H5S_ALL       (hid_t)0
+#define H5S_UNLIMITED HSIZE_UNDEF /**< Value for 'unlimited' dimensions */
 
-/* Define user-level maximum number of dimensions */
+/**
+ * The maximum dataspace rank or number of dimensions
+ */
 #define H5S_MAX_RANK 32
 
-/* Different types of dataspaces */
+/**
+ * Types of dataspaces
+ */
 typedef enum H5S_class_t {
-    H5S_NO_CLASS = -1, /*error                                      */
-    H5S_SCALAR   = 0,  /*scalar variable                            */
-    H5S_SIMPLE   = 1,  /*simple dataspace                           */
-    H5S_NULL     = 2   /*null dataspace                             */
+    H5S_NO_CLASS = -1, /**< Error                                      */
+    H5S_SCALAR   = 0,  /**< Singleton (scalar)                         */
+    H5S_SIMPLE   = 1,  /**< Regular grid                               */
+    H5S_NULL     = 2   /**< Empty set                                  */
 } H5S_class_t;
 
-/* Different ways of combining selections */
+/**
+ * Different ways of combining selections
+ */
 typedef enum H5S_seloper_t {
-    H5S_SELECT_NOOP = -1, /* error                                     */
-    H5S_SELECT_SET  = 0,  /* Select "set" operation              */
-    H5S_SELECT_OR,        /* Binary "or" operation for hyperslabs
+    H5S_SELECT_NOOP = -1, /**< Error                                     */
+    H5S_SELECT_SET  = 0,  /**< Select "set" operation 		             */
+    H5S_SELECT_OR,        /**< Binary "or" operation for hyperslabs
                            * (add new selection to existing selection)
+                           * \code
                            * Original region:  AAAAAAAAAA
                            * New region:             BBBBBBBBBB
                            * A or B:           CCCCCCCCCCCCCCCC
+                           * \endcode
                            */
-    H5S_SELECT_AND,       /* Binary "and" operation for hyperslabs
+    H5S_SELECT_AND,       /**< Binary "and" operation for hyperslabs
                            * (only leave overlapped regions in selection)
+                           * \code
                            * Original region:  AAAAAAAAAA
                            * New region:             BBBBBBBBBB
                            * A and B:                CCCC
+                           * \endcode
                            */
-    H5S_SELECT_XOR,       /* Binary "xor" operation for hyperslabs
+    H5S_SELECT_XOR,       /**< Binary "xor" operation for hyperslabs
                            * (only leave non-overlapped regions in selection)
+                           * \code
                            * Original region:  AAAAAAAAAA
                            * New region:             BBBBBBBBBB
                            * A xor B:          CCCCCC    CCCCCC
+                           * \endcode
                            */
-    H5S_SELECT_NOTB,      /* Binary "not" operation for hyperslabs
+    H5S_SELECT_NOTB,      /**< Binary "not" operation for hyperslabs
                            * (only leave non-overlapped regions in original selection)
+                           * \code
                            * Original region:  AAAAAAAAAA
                            * New region:             BBBBBBBBBB
                            * A not B:          CCCCCC
+                           * \endcode
                            */
-    H5S_SELECT_NOTA,      /* Binary "not" operation for hyperslabs
+    H5S_SELECT_NOTA,      /**< Binary "not" operation for hyperslabs
                            * (only leave non-overlapped regions in new selection)
+                           * \code
                            * Original region:  AAAAAAAAAA
                            * New region:             BBBBBBBBBB
                            * B not A:                    CCCCCC
+                           * \endcode
                            */
-    H5S_SELECT_APPEND,    /* Append elements to end of point selection */
-    H5S_SELECT_PREPEND,   /* Prepend elements to beginning of point selection */
-    H5S_SELECT_INVALID    /* Invalid upper bound on selection operations */
+    H5S_SELECT_APPEND,    /**< Append elements to end of point selection */
+    H5S_SELECT_PREPEND,   /**< Prepend elements to beginning of point selection */
+    H5S_SELECT_INVALID    /**< Invalid upper bound on selection operations */
 } H5S_seloper_t;
 
-/* Enumerated type for the type of selection */
+/**
+ * Selection type
+ */
 typedef enum {
-    H5S_SEL_ERROR      = -1, /* Error            */
-    H5S_SEL_NONE       = 0,  /* Nothing selected         */
-    H5S_SEL_POINTS     = 1,  /* Points / elements selected    */
-    H5S_SEL_HYPERSLABS = 2,  /* Hyperslab selected           */
-    H5S_SEL_ALL        = 3,  /* Entire extent selected    */
-    H5S_SEL_N                /*THIS MUST BE LAST        */
+    H5S_SEL_ERROR      = -1, /**< Error                                 */
+    H5S_SEL_NONE       = 0,  /**< Empty selection                       */
+    H5S_SEL_POINTS     = 1,  /**< Set of points                         */
+    H5S_SEL_HYPERSLABS = 2,  /**< Hyperslab                             */
+    H5S_SEL_ALL        = 3,  /**< Everything	                        */
+    H5S_SEL_N                /**< Sentinel \internal THIS MUST BE LAST	*/
 } H5S_sel_type;
 
 #ifdef __cplusplus
 extern "C" {
 #endif
 
-/* Operations on dataspaces */
+/* Operations on dataspaces, dataspace selections and selection iterators */
+
 /**
  * \ingroup H5S
  *
@@ -243,31 +262,31 @@ H5_DLL hid_t H5Sdecode(const void *buf);
  *
  * \space_id{obj_id}
  * \param[in,out] buf     Buffer for the object to be encoded into;
- *                        If the provided buffer is NULL, only the size of
- *                        buffer needed is returned through \p nalloc.
+ *                        If the provided buffer is NULL, only the size
+ *                        of buffer needed is returned through \p nalloc.
  * \param[in,out] nalloc  The size of the allocated buffer
  *
  * \return \herr_t
  *
  * \details Given the data space identifier \p obj_id, H5Sencode() converts
- *          a data space description into binary form in a buffer. Using
- *          this binary form in the buffer, a data space object can be
- *          reconstructed using H5Sdecode() to return a new object handle
- *          (\p hid_t) for this data space.
+ *          a data space description into binary form in a buffer. Using this
+ *          binary form in the buffer, a data space object can be
+ *          reconstructed with H5Sdecode() to return a new object handle
+ *          (#hid_t) for this data space.
  *
- *          A preliminary H5Sencode() 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 H5Sencode1()
- *          call, which will retrieve the actual encoded object.
+ *          A preliminary H5Sencode() call can be made to determine the
+ *          size of the buffer needed. This value is returned in \p nalloc.
+ *          That value can then be assigned to \p nalloc for a second
+ *           H5Sencode()call, which will retrieve the actual encoded object.
  *
- *          If the library finds out \p nalloc is not big enough for the
+ *          If the library determines 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.
  *
- *          The types of data space addressed in this function are null,
- *          scalar, and simple space. For a simple data space, the information
- *          on the selection, for example, hyperslab selection, is also
- *          encoded and decoded. A complex data space has not been
+ *          The types of data space that are addressed in this function are
+ *          null, scalar, and simple space. For a simple data space, the
+ *          information on the selection, for example, hyperslab selection,
+ *          is also encoded and decoded. A complex data space has not been
  *          implemented in the library.
  *
  * \since 1.8.0
diff --git a/src/H5Tmodule.h b/src/H5Tmodule.h
index c489edc..73424fb 100644
--- a/src/H5Tmodule.h
+++ b/src/H5Tmodule.h
@@ -29,10 +29,38 @@
 #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 H5T H5T
+ *
+ * Use the functions in this module to manage HDF5 datatypes.
+ *
+ * HDF5 datatypes describe the element type of HDF5 datasets and attributes.
+ * There's a large set of predefined datatypes, but users may find it useful
+ * to define new datatypes through a process called \Emph{derivation}.
+ *
+ * The element type is automatically persisted as part of the HDF5 metadata of
+ * attributes and datasets. Additionally, datatype definitions can be persisted
+ * to HDF5 files and linked to groups as HDF5 datatype objects or so-called
+ * \Emph{committed datatypes}.
+ *
+ * <table>
+ * <tr><th>Create</th><th>Read</th></tr>
+ * <tr valign="top">
+ *   <td>
+ *   \snippet{lineno} H5T_examples.c create
+ *   </td>
+ *   <td>
+ *   \snippet{lineno} H5T_examples.c read
+ *   </td>
+ * <tr><th>Update</th><th>Delete</th></tr>
+ * <tr valign="top">
+ *   <td>
+ *   \snippet{lineno} H5T_examples.c update
+ *   </td>
+ *   <td>
+ *   \snippet{lineno} H5T_examples.c delete
+ *   </td>
+ * </tr>
+ * </table>
  *
  * \defgroup ARRAY Array Datatypes
  * \ingroup H5T
diff --git a/src/H5Tpublic.h b/src/H5Tpublic.h
index 9711178..10a4b06 100644
--- a/src/H5Tpublic.h
+++ b/src/H5Tpublic.h
@@ -196,9 +196,9 @@ typedef enum H5T_pers_t {
  */
 //! <!-- [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 ascending         */
+    H5T_DIR_ASCEND  = 1, /**< in ascending order                     */
+    H5T_DIR_DESCEND = 2  /**< in descending order                    */
 } H5T_direction_t;
 //! <!-- [H5T_direction_t_snip] -->
 
@@ -245,7 +245,7 @@ typedef struct {
  * Indicate that a string is variable length (null-terminated in C, instead of
  * fixed length)
  */
-#define H5T_VARIABLE ((size_t)-1)
+#define H5T_VARIABLE ((size_t)(-1))
 
 /* Opaque information */
 /**
@@ -279,7 +279,7 @@ typedef herr_t (*H5T_conv_t)(hid_t src_id, hid_t dst_id, H5T_cdata_t *cdata, siz
  * \returns Valid callback function return values are #H5T_CONV_ABORT,
  *          #H5T_CONV_UNHANDLED and #H5T_CONV_HANDLED.
  *
- * \details If an exception like overflow happenes during conversion, this
+ * \details If an exception like overflow happens during conversion, this
  *          function is called if it's registered through H5Pset_type_conv_cb().
  *
  */
@@ -3021,4 +3021,4 @@ H5_DLL int H5Tget_array_dims1(hid_t type_id, hsize_t dims[], int perm[]);
 #ifdef __cplusplus
 }
 #endif
-#endif /* H5Tpublic_H */
\ No newline at end of file
+#endif /* H5Tpublic_H */
diff --git a/src/H5Zmodule.h b/src/H5Zmodule.h
index 76a2380..9312b72 100644
--- a/src/H5Zmodule.h
+++ b/src/H5Zmodule.h
@@ -29,57 +29,80 @@
 #define H5_MY_PKG_ERR  H5E_PLINE
 #define H5_MY_PKG_INIT YES
 
-/**
- * \defgroup H5Z H5Z
+/**\defgroup H5Z H5Z
  *
+ * Use the functions in this module to manage HDF5 filters.
  *
- * \brief Filter and Compression Interface
+ * User-defined filters are created by registering a filter descriptor of
+ * type #H5Z_class_t with the library.
  *
- * \details The functions in this module let you configure filters that process
- *          data during I/O operation.
+ * Available filters can be read or examined at runtime.
  *
- *          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.
+ * It is conceivable that filters are stateful and that that state be
+ * updated at runtime.
  *
- *          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.
+ * Filters are deleted by unregistering.
  *
- *          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.
+ * <table>
+ * <tr><th>Create</th><th>Read</th></tr>
+ * <tr valign="top">
+ *   <td>
+ *   \snippet{lineno} H5Z_examples.c filter
+ *   \snippet{lineno} H5Z_examples.c create
+ *   </td>
+ *   <td>
+ *   \snippet{lineno} H5Z_examples.c read
+ *   </td>
+ * </tr>
+ * <tr><th>Update</th><th>Delete</th></tr>
+ * <tr valign="top">
+ *   <td>
+ *   \snippet{lineno} H5Z_examples.c update
+ *   </td>
+ *   <td>
+ *   \snippet{lineno} H5Z_examples.c delete
+ * </tr>
+ * </table>
  *
- *          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.
+ * 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.
  *
- *          See \ref_dld_filters for more information on how an HDF5
- *          application can apply a filter that is not registered with the HDF5
- *          library.
+ * 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 \ref_dld_filters for more information on how an HDF5 application can
+ * apply a filter that is not registered with the HDF5 library.
  *
  * \defgroup H5ZPRE Predefined Filters
  * \ingroup H5Z
diff --git a/src/H5module.h b/src/H5module.h
index 96bead8..f37dfc7 100644
--- a/src/H5module.h
+++ b/src/H5module.h
@@ -27,8 +27,31 @@
 #define H5_MY_PKG_INIT NO
 
 /**\defgroup H5 H5
- * \brief General Library Functions
- * \todo Describe concisely what the functions in this module are about.
+ *
+ * Use the functions in this module to manage the life cycle of HDF5 library
+ * instances.
+ *
+ * <table>
+ * <tr><th>Create</th><th>Read</th></tr>
+ * <tr valign="top">
+ *   <td>
+ *   \snippet{lineno} H5_examples.c create
+ *   </td>
+ *   <td>
+ *   \snippet{lineno} H5_examples.c read
+ *   </td>
+ * <tr><th>Update</th><th>Delete</th></tr>
+ * <tr valign="top">
+ *   <td>
+ *   \snippet{lineno} H5_examples.c update
+ *   </td>
+ *   <td>
+ *   \snippet{lineno} H5_examples.c closing_shop
+ *   \snippet{lineno} H5_examples.c delete
+ *   </td>
+ * </tr>
+ * </table>
+ *
  */
 
 #endif /* H5module_H */
diff --git a/src/H5public.h b/src/H5public.h
index 6dffcf6..1c5496b 100644
--- a/src/H5public.h
+++ b/src/H5public.h
@@ -34,30 +34,37 @@
 #ifdef H5_HAVE_FEATURES_H
 #include <features.h> /* For setting POSIX, BSD, etc. compatibility */
 #endif
-
-/* C library header files for things that appear in HDF5 public headers */
-#ifdef __cplusplus
-#define __STDC_FORMAT_MACROS
-#endif
-#include <inttypes.h>
-#include <limits.h>
-#include <stdarg.h>
-#include <stdbool.h>
-#include <stddef.h>
-#include <stdint.h>
-
-/* Unlike most sys/ headers, which are POSIX-only, sys/types.h is avaible
- * on Windows, though it doesn't necessarily contain all the POSIX types
- * we need for HDF5 (e.g. ssize_t).
- */
 #ifdef H5_HAVE_SYS_TYPES_H
 #include <sys/types.h>
 #endif
+#ifdef H5_STDC_HEADERS
+#include <limits.h> /* For H5T_NATIVE_CHAR defn in H5Tpublic.h  */
+#include <stdarg.h> /* For variadic functions in H5VLpublic.h   */
+#endif
+#ifndef __cplusplus
+#ifdef H5_HAVE_STDINT_H
+#include <stdint.h> /* For C9x types */
+#endif
+#else
+#ifdef H5_HAVE_STDINT_H_CXX
+#include <stdint.h> /* For C9x types (when included from C++) */
+#endif
+#endif
+#ifdef H5_HAVE_INTTYPES_H
+#include <inttypes.h> /* C99/POSIX.1 header for uint64_t, PRIu64 */
+#endif
+#ifdef H5_HAVE_STDDEF_H
+#include <stddef.h>
+#endif
 
 #ifdef H5_HAVE_PARALLEL
 /* Don't link against MPI C++ bindings */
+#ifndef MPICH_SKIP_MPICXX
 #define MPICH_SKIP_MPICXX 1
-#define OMPI_SKIP_MPICXX  1
+#endif
+#ifndef OMPI_SKIP_MPICXX
+#define OMPI_SKIP_MPICXX 1
+#endif
 #include <mpi.h>
 #ifndef MPI_FILE_NULL /* MPIO may be defined in mpi.h already */
 #include <mpio.h>
@@ -190,8 +197,9 @@ extern "C" {
  * Status return values.  Failed integer functions in HDF5 result almost
  * always in a negative value (unsigned failing functions sometimes return
  * zero for failure) while successful return is non-negative (often zero).
- * The negative failure value is most commonly -1, but don't bet on it.  The
- * proper way to detect failure is something like:
+ * The negative failure value is most commonly -1, but don't bet on it.
+ *
+ * The proper way to detect failure is something like:
  * \code
  * if((dset = H5Dopen2(file, name)) < 0)
  *    fprintf(stderr, "unable to open the requested dataset\n");
@@ -215,10 +223,30 @@ typedef int herr_t;
  * }
  * \endcode
  */
+#ifdef H5_HAVE_STDBOOL_H
+#include <stdbool.h>
+#else /* H5_HAVE_STDBOOL_H */
+#ifndef __cplusplus
+#if defined(H5_SIZEOF_BOOL) && (H5_SIZEOF_BOOL != 0)
+#define bool _Bool
+#else
+#define bool unsigned int
+#endif
+#define true 1
+#define false 0
+#endif /* __cplusplus */
+#endif /* H5_HAVE_STDBOOL_H */
 typedef bool hbool_t;
 typedef int  htri_t;
 
-/* Define the ssize_t type if it not is defined */
+/* The signed version of size_t
+ *
+ * ssize_t is POSIX and not defined in any C standard. It's used in some
+ * public HDF5 API calls so this work-around will define it if it's not
+ * present.
+ *
+ * Use of ssize_t should be discouraged in new code.
+ */
 #if H5_SIZEOF_SSIZE_T == 0
 /* Undefine this size, we will re-define it in one of the sections below */
 #undef H5_SIZEOF_SSIZE_T
@@ -236,8 +264,10 @@ typedef long long ssize_t;
 #endif
 #endif
 
-/* int64_t type is used for creation order field for links.  It may be
- * defined in Posix.1g, otherwise it is defined here.
+/**
+ * The size of file objects.
+ *
+ * \internal Defined as a (minimum) 64-bit integer type.
  */
 #if H5_SIZEOF_INT64_T >= 8
 #elif H5_SIZEOF_INT >= 8
@@ -282,9 +312,11 @@ typedef unsigned long long uint64_t;
 #error "nothing appropriate for uint64_t"
 #endif
 
-/*
- * The sizes of file objects have their own types defined here, use a minimum
- * 64-bit type.
+/**
+ * The size of file objects. Used when negative values are needed to indicate errors.
+ *
+ * \internal Defined as a (minimum) 64-bit integer type. Use of hssize_t
+ * should be discouraged in new code.
  */
 #if H5_SIZEOF_LONG_LONG >= 8
 H5_GCC_DIAG_OFF("long-long")
@@ -304,8 +336,10 @@ H5_GCC_DIAG_ON("long-long")
 #error "nothing appropriate for hsize_t"
 #endif
 
-/*
- * File addresses have their own types.
+/**
+ * The address of an object in the file.
+ *
+ * \internal Defined as a (minimum) 64-bit unsigned integer type.
  */
 #if H5_SIZEOF_INT >= 8
 typedef unsigned haddr_t;
@@ -386,9 +420,9 @@ typedef enum {
 /* (Actually, any positive value will cause the iterator to stop and pass back
  *      that positive value to the function that called the iterator)
  */
-#define H5_ITER_ERROR (-1)
-#define H5_ITER_CONT  (0)
-#define H5_ITER_STOP  (1)
+#define H5_ITER_ERROR (-1) /**< Error, stop iteration */
+#define H5_ITER_CONT  (0)  /**< Continue iteration */
+#define H5_ITER_STOP  (1)  /**< Stop iteration, short-circuit success */
 
 //! <!-- [H5_index_t_snip] -->
 /**