summaryrefslogtreecommitdiffstats
path: root/src
diff options
context:
space:
mode:
Diffstat (limited to 'src')
-rw-r--r--src/CMakeLists.txt1
-rw-r--r--src/H5Amodule.h24
-rw-r--r--src/H5Apublic.h267
-rw-r--r--src/H5Dmodule.h8
-rw-r--r--src/H5Dpublic.h562
-rw-r--r--src/H5ESmodule.h6
-rw-r--r--src/H5Emodule.h75
-rw-r--r--src/H5Epublic.h36
-rw-r--r--src/H5Fmodule.h19
-rw-r--r--src/H5Fpublic.h2
-rw-r--r--src/H5Gmodule.h25
-rw-r--r--src/H5Gpublic.h2
-rw-r--r--src/H5Imodule.h81
-rw-r--r--src/H5Ipublic.h33
-rw-r--r--src/H5Lmodule.h25
-rw-r--r--src/H5Lpublic.h2
-rw-r--r--src/H5Mmodule.h6
-rw-r--r--src/H5Mpublic.h2
-rw-r--r--src/H5Omodule.h41
-rw-r--r--src/H5Opublic.h681
-rw-r--r--src/H5PLmodule.h30
-rw-r--r--src/H5Pmodule.h164
-rw-r--r--src/H5Ppublic.h51
-rw-r--r--src/H5Rmodule.h29
-rw-r--r--src/H5Rpublic.h10
-rw-r--r--src/H5Smodule.h45
-rw-r--r--src/H5Spublic.h112
-rw-r--r--src/H5Tmodule.h36
-rw-r--r--src/H5VLmodule.h8
-rw-r--r--src/H5Zmodule.h109
-rw-r--r--src/H5module.h27
-rw-r--r--src/H5public.h30
32 files changed, 1166 insertions, 1383 deletions
diff --git a/src/CMakeLists.txt b/src/CMakeLists.txt
index ff47c8e..7989899 100644
--- a/src/CMakeLists.txt
+++ b/src/CMakeLists.txt
@@ -1416,6 +1416,7 @@ if (DOXYGEN_FOUND)
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_DOXYGEN_DIR}/hdf5.tag)
set (DOXYGEN_SERVER_BASED_SEARCH NO)
set (DOXYGEN_EXTERNAL_SEARCH NO)
set (DOXYGEN_SEARCHENGINE_URL)
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 b3da77f..b78ae05 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
*
@@ -117,27 +117,19 @@ H5_DLL herr_t H5Aclose_async(const char *app_file, const char *app_func, unsigne
* 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()
@@ -175,28 +167,19 @@ H5_DLL hid_t H5Acreate_async(const char *app_file, const char *app_func, unsigne
* 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
*
*/
@@ -224,10 +207,14 @@ H5_DLL hid_t H5Acreate_by_name_async(const char *app_file, const char *app_func,
*
* \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
*
@@ -254,27 +241,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.
@@ -302,9 +278,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.
@@ -360,9 +333,7 @@ H5_DLL herr_t H5Aexists_async(const char *app_file, const char *app_func, unsign
* \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
@@ -394,9 +365,6 @@ H5_DLL herr_t H5Aexists_by_name_async(const char *app_file, const char *app_func
* 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
*
*/
@@ -413,32 +381,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
*
*/
@@ -466,16 +411,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
@@ -493,8 +431,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
@@ -507,11 +444,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.
@@ -542,8 +474,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
@@ -554,7 +486,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,
@@ -575,13 +507,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
@@ -621,7 +549,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
*
@@ -639,17 +567,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.
@@ -662,7 +589,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
@@ -689,17 +616,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.
*
@@ -716,11 +632,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
@@ -756,24 +667,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.
*
@@ -790,25 +687,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.
@@ -835,8 +713,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,
@@ -845,6 +722,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()
@@ -876,17 +756,13 @@ H5_DLL hid_t H5Aopen_async(const char *app_file, const char *app_func, unsigned
*
* \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
@@ -933,11 +809,9 @@ H5_DLL hid_t H5Aopen_by_idx_async(const char *app_file, const char *app_func, un
*
* \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
@@ -982,6 +856,9 @@ H5_DLL hid_t H5Aopen_by_name_async(const char *app_file, const char *app_func, u
* 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.
@@ -1051,15 +928,12 @@ H5_DLL herr_t H5Arename_by_name_async(const char *app_file, const char *app_func
* 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
@@ -1100,6 +974,7 @@ H5_DLL herr_t H5Awrite_async(const char *app_file, const char *app_func, unsigne
H5_DLL herr_t H5Arename_by_name(hid_t loc_id, const char *obj_name, const char *old_attr_name,
const char *new_attr_name, hid_t lapl_id);
+/// \cond DEV
/* API Wrappers for async routines */
/* (Must be defined _after_ the function prototype) */
/* (And must only defined when included in application code, not the library) */
@@ -1133,6 +1008,7 @@ H5_DLL herr_t H5Arename_by_name(hid_t loc_id, const char *obj_name, const char *
#define H5Aexists_by_name_async_wrap H5_NO_EXPAND(H5Aexists_by_name_async)
#define H5Aclose_async_wrap H5_NO_EXPAND(H5Aclose_async)
#endif /* H5A_MODULE */
+/// \endcond
/* Symbols defined for compatibility with previous versions of the HDF5 API.
*
@@ -1182,9 +1058,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.
@@ -1192,18 +1068,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
*
@@ -1225,8 +1090,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.
@@ -1249,8 +1113,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
@@ -1262,10 +1125,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
@@ -1283,8 +1142,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
@@ -1310,8 +1168,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 63cc61c..8fe8020 100644
--- a/src/H5Dpublic.h
+++ b/src/H5Dpublic.h
@@ -32,7 +32,9 @@
#define H5D_CHUNK_CACHE_NBYTES_DEFAULT SIZE_MAX
#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,18 +197,51 @@ 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] -->
//! <!-- [H5D_chunk_iter_op_t_snip] -->
/**
- * Define the operator function pointer for H5Dchunk_iter()
+ * \brief Callback for H5Dchunk_iter()
+ *
+ * \param[in] offset Array of starting logical coordinates of chunk.
+ * \param[in] filter_mask Filter mask of chunk.
+ * \param[in] addr Offset in file of chunk data.
+ * \param[in] nbytes Size in bytes of chunk data in file.
+ * \param[in,out] op_data Pointer to any user-defined data associated with
+ * the operation.
+ * \returns \li Zero (#H5_ITER_CONT) causes the iterator to continue, returning
+ * zero when all elements have been processed.
+ * \li A positive value (#H5_ITER_STOP) causes the iterator to
+ * immediately return that value, indicating short-circuit success.
+ * \li A negative (#H5_ITER_ERROR) causes the iterator to immediately
+ * return that value, indicating failure.
*/
-//! <!-- [H5D_chunk_iter_op_t_snip] -->
typedef int (*H5D_chunk_iter_op_t)(const hsize_t *offset, uint32_t filter_mask, haddr_t addr, uint32_t nbytes,
void *op_data);
+//! <!-- [H5D_chunk_iter_op_t_snip] -->
/********************/
/* Public Variables */
@@ -186,7 +261,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
@@ -211,13 +286,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
@@ -225,7 +293,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
@@ -236,8 +304,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
*
@@ -285,34 +353,14 @@ H5_DLL hid_t H5Dcreate_async(const char *app_file, const char *app_func, unsigne
* 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);
@@ -338,12 +386,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()
@@ -377,6 +419,9 @@ H5_DLL hid_t H5Dopen_async(const char *app_file, const char *app_func, unsigned
* 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()
*
*/
@@ -393,7 +438,19 @@ H5_DLL hid_t H5Dget_space_async(const char *app_file, const char *app_func, unsi
/**
* --------------------------------------------------------------------------
* \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);
@@ -412,27 +469,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);
@@ -452,9 +489,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);
@@ -488,10 +522,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
*
*/
@@ -510,11 +540,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
@@ -524,21 +551,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);
@@ -595,7 +620,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
*
@@ -638,7 +663,7 @@ H5_DLL herr_t H5Dget_chunk_info_by_coord(hid_t dset_id, const hsize_t *offset, u
* --------------------------------------------------------------------------
* \ingroup H5D
*
- * \brief Iterate over all chunks
+ * \brief Iterate over all chunks of a chunked dataset
*
* \dset_id
* \param[in] dxpl_id Identifier of a transfer property list
@@ -649,33 +674,16 @@ H5_DLL herr_t H5Dget_chunk_info_by_coord(hid_t dset_id, const hsize_t *offset, u
*
* \details H5Dget_chunk_iter iterates over all chunks in the dataset, calling the
* user supplied callback with the details of the chunk and the supplied
- * \p op_data.
- *
- * Callback information:
- * H5D_chunk_iter_op_t is defined as:
- *
- * typedef int (*H5D_chunk_iter_op_t)(
- * const hsize_t *offset,
- * uint32_t filter_mask,
- * haddr_t addr,
- * uint32_t nbytes,
- * void *op_data);
- *
- * H5D_chunk_iter_op_t parameters:
- * hsize_t *offset; IN/OUT: Array of starting logical coordinates of chunk.
- * uint32_t filter_mask; IN: Filter mask of chunk.
- * haddr_t addr; IN: Offset in file of chunk data.
- * uint32_t nbytes; IN: Size in number of bytes of chunk data in file.
- * void *op_data; IN/OUT: Pointer to any user-defined data
- * associated with the operation.
- *
- * The return values from an operator are:
- * Zero (H5_ITER_CONT) causes the iterator to continue, returning zero when all
- * elements have been processed.
- * Positive (H5_ITER_STOP) causes the iterator to immediately return that positive
- * value, indicating short-circuit success.
- * Negative (H5_ITER_ERROR) causes the iterator to immediately return that value,
- * indicating failure.
+ * context \p op_data.
+ *
+ * \par Example
+ * For each chunk, print the allocated chunk size (0 for un-allocated chunks).
+ * \snippet H5D_examples.c H5Dchunk_iter_cb
+ * Iterate over all chunked datasets and chunks in a file.
+ * \snippet H5D_examples.c H5Ovisit_cb
+ *
+ * \version 1.?.?
+ * \todo When was this function introduced?
*
*/
H5_DLL herr_t H5Dchunk_iter(hid_t dset_id, hid_t dxpl_id, H5D_chunk_iter_op_t cb, void *op_data);
@@ -696,16 +704,16 @@ H5_DLL herr_t H5Dchunk_iter(hid_t dset_id, hid_t dxpl_id, H5D_chunk_iter_op_t cb
*
* \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
@@ -719,9 +727,9 @@ H5_DLL herr_t H5Dchunk_iter(hid_t dset_id, hid_t dxpl_id, H5D_chunk_iter_op_t cb
* \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
*
@@ -737,7 +745,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
@@ -786,9 +794,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
@@ -833,14 +840,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,
@@ -953,6 +958,8 @@ H5_DLL herr_t H5Dread_async(const char *app_file, const char *app_func, unsigned
* 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
@@ -960,6 +967,9 @@ H5_DLL herr_t H5Dread_async(const char *app_file, const char *app_func, unsigned
* 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()
*
*/
@@ -1000,11 +1010,6 @@ H5_DLL herr_t H5Dwrite_async(const char *app_file, const char *app_func, unsigne
* 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
@@ -1032,11 +1037,10 @@ H5_DLL herr_t H5Dwrite_async(const char *app_file, const char *app_func, unsigne
* 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
*
@@ -1074,10 +1078,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
@@ -1091,8 +1095,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
*
@@ -1122,52 +1126,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
@@ -1217,30 +1178,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);
@@ -1287,22 +1243,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
*
@@ -1337,6 +1292,8 @@ H5_DLL herr_t H5Dset_extent_async(const char *app_file, const char *app_func, un
* 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);
@@ -1395,40 +1352,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
*
@@ -1480,27 +1404,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
@@ -1524,11 +1430,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
*
@@ -1544,12 +1450,14 @@ H5_DLL herr_t H5Dclose(hid_t dset_id);
*/
H5_DLL herr_t H5Dclose_async(const char *app_file, const char *app_func, unsigned app_line, hid_t dset_id,
hid_t es_id);
-
+/// \cond DEV
/* Internal API routines */
H5_DLL herr_t H5Ddebug(hid_t dset_id);
H5_DLL herr_t H5Dformat_convert(hid_t dset_id);
H5_DLL herr_t H5Dget_chunk_index_type(hid_t did, H5D_chunk_index_t *idx_type);
+/// \endcond
+/// \cond DEV
/* API Wrappers for async routines */
/* (Must be defined _after_ the function prototype) */
/* (And must only defined when included in application code, not the library) */
@@ -1573,6 +1481,7 @@ H5_DLL herr_t H5Dget_chunk_index_type(hid_t did, H5D_chunk_index_t *idx_type);
#define H5Dset_extent_async_wrap H5_NO_EXPAND(H5Dset_extent_async)
#define H5Dclose_async_wrap H5_NO_EXPAND(H5Dclose_async)
#endif /* H5D_MODULE */
+/// \endcond
/* Symbols defined for compatibility with previous versions of the HDF5 API.
*
@@ -1613,8 +1522,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
@@ -1680,8 +1588,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,
@@ -1711,10 +1618,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:
@@ -1734,7 +1641,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.
*
*/
@@ -1752,8 +1659,7 @@ H5_DLL herr_t H5Dextend(hid_t dset_id, const hsize_t size[]);
*
* \return \herr_t
*
- * \deprecated This function has been deprecated in HDF5-1.12 in favor of the
- * function H5Treclaim().
+ * \deprecation_note{H5Treclaim()}
*
* \details H5Dvlen_reclaim() reclaims memory buffers created to store VL
* datatypes.
@@ -1771,7 +1677,7 @@ H5_DLL herr_t H5Dextend(hid_t dset_id, const hsize_t size[]);
* frees them from the bottom up, releasing all the memory without
* creating memory leaks.
*
- * \version 1.12.0 Routine was deprecated
+ * \version 1.12.0 Function was deprecated
*
*/
H5_DLL herr_t H5Dvlen_reclaim(hid_t type_id, hid_t space_id, hid_t dxpl_id, void *buf);
diff --git a/src/H5ESmodule.h b/src/H5ESmodule.h
index cbc812e..5169b52 100644
--- a/src/H5ESmodule.h
+++ b/src/H5ESmodule.h
@@ -29,8 +29,10 @@
#define H5_MY_PKG_ERR H5E_EVENTSET
#define H5_MY_PKG_INIT YES
-/**
- * \defgroup H5ES H5ES
+/**\defgroup H5ES H5ES
+ *
+ * \todo Add the event set life cycle.
+ *
* \brief Event Set Interface
*
* \details \Bold{This interface can be only used with the HDF5 VOL connectors that
diff --git a/src/H5Emodule.h b/src/H5Emodule.h
index 43d5d36..58a3517 100644
--- a/src/H5Emodule.h
+++ b/src/H5Emodule.h
@@ -29,33 +29,54 @@
#define H5_MY_PKG_ERR H5E_ERROR
#define H5_MY_PKG_INIT YES
-/**
- * \defgroup H5E H5E
- * \brief Error Handling Interface
- *
- * \details The Error interface provides error handling in the form of a stack.
- * The \Code{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.
- *
- * Certain API functions in the \c H5E package, such as H5Eprint1(), 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.
- *
- * 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.
- *
- * 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 \c H5E package.
+/**\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 0294023..9dfd1fc 100644
--- a/src/H5Epublic.h
+++ b/src/H5Epublic.h
@@ -716,12 +716,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);
/**
@@ -737,6 +738,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
@@ -763,8 +767,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);
/**
@@ -781,6 +783,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
@@ -791,8 +796,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);
@@ -805,6 +808,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:
@@ -815,8 +821,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);
/**
@@ -829,6 +833,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
@@ -845,8 +852,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);
/**
@@ -860,6 +865,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.
*
@@ -877,8 +885,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);
/**
@@ -891,6 +897,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.
*
@@ -898,7 +906,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);
/**
@@ -911,6 +918,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.
*
@@ -920,7 +929,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 98d2a9f..c3230e1 100644
--- a/src/H5Fpublic.h
+++ b/src/H5Fpublic.h
@@ -1777,6 +1777,7 @@ H5_DLL herr_t H5Fset_mpi_atomicity(hid_t file_id, hbool_t flag);
H5_DLL herr_t H5Fget_mpi_atomicity(hid_t file_id, hbool_t *flag);
#endif /* H5_HAVE_PARALLEL */
+/// \cond DEV
/* API Wrappers for async routines */
/* (Must be defined _after_ the function prototype) */
/* (And must only defined when included in application code, not the library) */
@@ -1796,6 +1797,7 @@ H5_DLL herr_t H5Fget_mpi_atomicity(hid_t file_id, hbool_t *flag);
#define H5Fflush_async_wrap H5_NO_EXPAND(H5Fflush_async)
#define H5Fclose_async_wrap H5_NO_EXPAND(H5Fclose_async)
#endif /* H5F_MODULE */
+/// \endcond
/* Symbols defined for compatibility with previous versions of the HDF5 API.
*
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/H5Gpublic.h b/src/H5Gpublic.h
index b009d41..d9c29f6 100644
--- a/src/H5Gpublic.h
+++ b/src/H5Gpublic.h
@@ -467,6 +467,7 @@ H5_DLL herr_t H5Gclose(hid_t group_id);
H5_DLL herr_t H5Gclose_async(const char *app_file, const char *app_func, unsigned app_line, hid_t group_id,
hid_t es_id);
+/// \cond DEV
/* API Wrappers for async routines */
/* (Must be defined _after_ the function prototype) */
/* (And must only defined when included in application code, not the library) */
@@ -488,6 +489,7 @@ H5_DLL herr_t H5Gclose_async(const char *app_file, const char *app_func, unsigne
#define H5Gget_info_by_idx_async_wrap H5_NO_EXPAND(H5Gget_info_by_idx_async)
#define H5Gclose_async_wrap H5_NO_EXPAND(H5Gclose_async)
#endif /* H5G_MODULE */
+/// \endcond
/* Symbols defined for compatibility with previous versions of the HDF5 API.
*
diff --git a/src/H5Imodule.h b/src/H5Imodule.h
index 8db31c8..08f8bb0 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 a5f830b..8d4dbf8 100644
--- a/src/H5Ipublic.h
+++ b/src/H5Ipublic.h
@@ -106,7 +106,7 @@ extern "C" {
/* Public API functions */
/**
- * \ingroup H5I
+ * \ingroup H5IUD
*
* \brief Registers an object under a type and returns an ID for it
*
@@ -128,7 +128,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
*
@@ -151,7 +151,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
*
@@ -190,12 +190,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
@@ -391,7 +386,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
*
@@ -423,7 +418,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
*
@@ -447,7 +442,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
*
@@ -470,7 +465,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
*
@@ -489,7 +484,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
*
@@ -509,7 +504,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
*
@@ -528,7 +523,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
@@ -569,7 +564,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 Calls a callback for each member of the identifier type specified
*
@@ -598,7 +593,7 @@ H5_DLL void *H5Isearch(H5I_type_t type, H5I_search_func_t func, void *key);
*/
H5_DLL herr_t H5Iiterate(H5I_type_t type, H5I_iterate_func_t op, void *op_data);
/**
- * \ingroup H5I
+ * \ingroup H5IUD
*
* \brief Returns the number of identifiers in a given identifier type
*
@@ -618,7 +613,7 @@ H5_DLL herr_t H5Iiterate(H5I_type_t type, H5I_iterate_func_t op, void *op_data);
*/
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 16f1f34..cffd25c 100644
--- a/src/H5Lmodule.h
+++ b/src/H5Lmodule.h
@@ -30,8 +30,29 @@
#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
diff --git a/src/H5Lpublic.h b/src/H5Lpublic.h
index f665526..72b0182 100644
--- a/src/H5Lpublic.h
+++ b/src/H5Lpublic.h
@@ -1380,6 +1380,7 @@ H5_DLL herr_t H5Lunpack_elink_val(const void *ext_linkval /*in*/, size_t link_si
H5_DLL herr_t H5Lcreate_external(const char *file_name, const char *obj_name, hid_t link_loc_id,
const char *link_name, hid_t lcpl_id, hid_t lapl_id);
+/// \cond DEV
/* API Wrappers for async routines */
/* (Must be defined _after_ the function prototype) */
/* (And must only defined when included in application code, not the library) */
@@ -1401,6 +1402,7 @@ H5_DLL herr_t H5Lcreate_external(const char *file_name, const char *obj_name, hi
#define H5Lexists_async_wrap H5_NO_EXPAND(H5Lexists_async)
#define H5Literate_async_wrap H5_NO_EXPAND(H5Literate_async)
#endif /* H5L_MODULE */
+/// \endcond
/* Symbols defined for compatibility with previous versions of the HDF5 API.
*
diff --git a/src/H5Mmodule.h b/src/H5Mmodule.h
index 3dae3e2..848f63f 100644
--- a/src/H5Mmodule.h
+++ b/src/H5Mmodule.h
@@ -26,9 +26,9 @@
#define H5_MY_PKG_ERR H5E_MAP
#define H5_MY_PKG_INIT YES
-/**
- * \defgroup H5M H5M
- * \brief Map Interface
+/**\defgroup H5M H5M
+ *
+ * \todo Describe the map life cycle.
*
* \details \Bold{The interface can only be used with the HDF5 VOL connectors that
* implement map objects.} The native HDF5 library does not support this
diff --git a/src/H5Mpublic.h b/src/H5Mpublic.h
index b3a0903..3f94edb 100644
--- a/src/H5Mpublic.h
+++ b/src/H5Mpublic.h
@@ -588,6 +588,7 @@ H5_DLL herr_t H5Miterate_by_name(hid_t loc_id, const char *map_name, hsize_t *id
*/
H5_DLL herr_t H5Mdelete(hid_t map_id, hid_t key_mem_type_id, const void *key, hid_t dxpl_id);
+/// \cond DEV
/* API Wrappers for async routines */
/* (Must be defined _after_ the function prototype) */
/* (And must only defined when included in application code, not the library) */
@@ -606,6 +607,7 @@ H5_DLL herr_t H5Mdelete(hid_t map_id, hid_t key_mem_type_id, const void *key, hi
#define H5Mput_async_wrap H5_NO_EXPAND(H5Mput_async)
#define H5Mget_async_wrap H5_NO_EXPAND(H5Mget_async)
#endif /* H5M_MODULE */
+/// \endcond
/* Symbols defined for compatibility with previous versions of the HDF5 API.
*
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 7bc7784..0fcedb2 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,22 +51,26 @@
* 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)
/* 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)
@@ -81,9 +85,9 @@
* 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_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_ALL (H5O_INFO_BASIC | H5O_INFO_TIME | H5O_INFO_NUM_ATTRS)
//! <!-- [H5O_native_info_fields_snip] -->
@@ -91,8 +95,8 @@
* Flags for H5Oget_native_info(). Theses flags determine which fields will be
* filled in in the \ref H5O_native_info_t struct.
*/
-#define H5O_NATIVE_INFO_HDR 0x0008u /* Fill in the hdr field */
-#define H5O_NATIVE_INFO_META_SIZE 0x0010u /* Fill in the meta_size field */
+#define H5O_NATIVE_INFO_HDR 0x0008u /**< Fill in the hdr field */
+#define H5O_NATIVE_INFO_META_SIZE 0x0010u /**< Fill in the meta_size field */
#define H5O_NATIVE_INFO_ALL (H5O_NATIVE_INFO_HDR | H5O_NATIVE_INFO_META_SIZE)
//! <!-- [H5O_native_info_fields_snip] -->
@@ -146,15 +150,15 @@ typedef struct H5O_hdr_info_t {
* (For H5Oget_info(), H5Oget_info_by_name(), H5Oget_info_by_idx() version 3)
*/
typedef struct H5O_info2_t {
- unsigned long fileno; /* File number that object is located in */
- H5O_token_t token; /* Token representing the object */
- H5O_type_t type; /* Basic object type (group, dataset, etc.) */
- unsigned rc; /* Reference count of object */
- time_t atime; /* Access time */
- time_t mtime; /* Modification time */
- time_t ctime; /* Change time */
- time_t btime; /* Birth time */
- hsize_t num_attrs; /* # of attributes attached to object */
+ unsigned long fileno; /**< File number that object is located in */
+ H5O_token_t token; /**< Token representing the object */
+ H5O_type_t type; /**< Basic object type (group, dataset, etc.) */
+ unsigned rc; /**< Reference count of object */
+ time_t atime; /**< Access time */
+ time_t mtime; /**< Modification time */
+ time_t ctime; /**< Change time */
+ time_t btime; /**< Birth time */
+ hsize_t num_attrs; /**< Number of attributes attached to object */
} H5O_info2_t;
//! <!-- [H5O_info2_t_snip] -->
@@ -165,11 +169,10 @@ typedef struct H5O_info2_t {
*/
typedef struct H5O_native_info_t {
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_native_info_t;
//! <!-- [H5O_native_info_t_snip] -->
@@ -181,6 +184,17 @@ typedef uint32_t H5O_msg_crt_idx_t;
//! <!-- [H5O_iterate2_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 H5Ovisit3() \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_iterate2_t)(hid_t obj, const char *name, const H5O_info2_t *info, void *op_data);
//! <!-- [H5O_iterate2_t_snip] -->
@@ -460,28 +474,7 @@ H5_DLL htri_t H5Oexists_by_name(hid_t loc_id, const char *name, hid_t lapl_id);
* \return \herr_t
*
* \details H5Oget_info3() specifies an object by its identifier, \p loc_id , and
- * retrieves the metadata describing that object in \p oinfo , an H5O_info2_t \c struct.
- *
- * The H5O_info2_t \c struct is defined in H5Opublic.h as follows :
- * \snippet this H5O_info2_t_snip
- *
- * Note the following about H5O_info2_t :
- * - Of the four time fields (\c atime, \c mtime, \c ctime, and \c btime)
- * only \c ctime has been implemented.
- * - The \c atime value is the last time the object was read or written.
- * - The \c mtime value is the last time the raw data in the object was changed.
- * - The \c ctime value is the last time the metadata for the object was changed.
- * - The \c btime value is the time the object was created.
- *
- * The H5O_token_t is defined in H5public.h as follows:
- * \snippet H5public.h H5O_token_t_snip
- *
- * The H5O_type_t \c enum indicates the object type and
- * is defined in H5Opublic.h as follows:
- * \snippet this H5O_type_t_snip
- *
- * Note that the object retrieved as indicated by \p loc_id
- * refers only to the types specified by H5O_type_t.
+ * 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_info2_t \c struct returned in \p oinfo.
@@ -530,29 +523,6 @@ H5_DLL herr_t H5Oget_info3(hid_t loc_id, H5O_info2_t *oinfo, unsigned fields);
* \p loc_id and \p name, respectively, and retrieves the metadata
* describing that object in \p oinfo, an H5O_info2_t struct.
*
- * \p oinfo, in which the object information is returned, is a \c struct of
- * type H5O_info2_t, which is defined in H5Opublic.h in the HDF5 source code:
- *
- * \snippet this H5O_info2_t_snip
- *
- * Note the following about H5O_info2_t :
- * - Of the four time fields (\c atime, \c mtime, \c ctime, and \c btime)
- * only \c ctime has been implemented.
- * - The \c atime value is the last time the object was read or written.
- * - The \c mtime value is the last time the raw data in the object was changed.
- * - The \c ctime value is the last time the metadata for the object was changed.
- * - The \c btime value is the time the object was created.
- *
- * The H5O_token_t is defined in H5public.h as follows:
- * \snippet H5public.h H5O_token_t_snip
- *
- * The H5O_type_t \c enum indicates the object type and
- * is defined in H5Opublic.h as follows:
- * \snippet this H5O_type_t_snip
- *
- * Note that the object retrieved as indicated by \p loc_id
- * refers only to the types specified by H5O_type_t.
- *
* The \p fields parameter contains flags to determine which fields will be filled in
* the H5O_info2_t \c struct returned in \p oinfo.
* These flags are defined in the H5Opublic.h file:
@@ -608,34 +578,6 @@ H5_DLL herr_t H5Oget_info_by_name_async(const char *app_file, const char *app_fu
* If \p loc_id fully specifies the group in which the object resides,
* \p group_name can be a dot (\c .).
*
- * \p idx_type is of type #H5_index_t, defined in H5public.h as:
- * \snippet H5public.h H5_index_t_snip
- *
- * \p order is of type #H5_iter_order_t defined in H5public.h as:
- * \snippet H5public.h H5_iter_order_t_snip
- *
- * \p oinfo, in which the object information is returned, is a \c struct of
- * type H5O_info2_t, which is defined in H5Opublic.h in the HDF5 source code:
- * \snippet this H5O_info2_t_snip
- *
- * Note the following about H5O_info2_t :
- * - Of the four time fields (\c atime, \c mtime, \c ctime, and \c btime)
- * only \c ctime has been implemented.
- * - The \c atime value is the last time the object was read or written.
- * - The \c mtime value is the last time the raw data in the object was changed.
- * - The \c ctime value is the last time the metadata for the object was changed.
- * - The \c btime value is the time the object was created.
- *
- * H5O_token_t is defined in H5public.h as follows:
- * \snippet H5public.h H5O_token_t_snip
- *
- * The #H5O_type_t \c enum indicates the object type and
- * is defined in H5Opublic.h as follows:
- * \snippet this H5O_type_t_snip
- *
- * Note that the object retrieved as indicated by \p loc_id
- * refers only to the types specified by #H5O_type_t.
- *
* The \p fields parameter contains flags to determine which fields will be filled in
* the H5O_info2_t \c struct returned in \p oinfo.
* These flags are defined in the H5Opublic.h file:
@@ -668,11 +610,7 @@ H5_DLL herr_t H5Oget_info_by_idx3(hid_t loc_id, const char *group_name, H5_index
* \return \herr_t
*
* \details H5Oget_native_info() retrieves the native file format information for an object
- * specified by \p loc_id. The information is retrieved into the
- * buffer specified by \p oinfo, which is defined as a \c struct of
- * type H5O_native_info_t in H5Opublic.h:
- *
- * \snippet this H5O_native_info_t_snip
+ * specified by \p loc_id.
*
* The \p fields parameter indicates which fields to fill in
* H5O_native_info_t. Possible values defined in H5Opublic.h are:
@@ -703,12 +641,9 @@ H5_DLL herr_t H5Oget_native_info(hid_t loc_id, H5O_native_info_t *oinfo, unsigne
*
* \return \herr_t
*
- * \details H5Oget_native_info_by_name() retrieves the native file format information for an object
- * specified by \p loc_id and the name \p name. The information is
- * retrieved into the buffer specified by \p oinfo, which is defined
- * as a \c struct of type H5O_native_info_t in H5Opublic.h:
- *
- * \snippet this H5O_native_info_t_snip
+ * \details H5Oget_native_info_by_name() retrieves the native file format
+ * information for an object specified by \p loc_id and the name \p
+ * name.
*
* The \p fields parameter which fields to fill in H5O_native_info_t.
* Possible values defined in H5Opublic.h are:
@@ -747,16 +682,7 @@ H5_DLL herr_t H5Oget_native_info_by_name(hid_t loc_id, const char *name, H5O_nat
* specified by \p loc_id, group name, \p group_name, the index by which
* objects in the group are tracked, \p idx_type, the order by which
* the index is to be traversed, \p order , and an object's position
- * \p n within that index. The information is retrieved into the
- * buffer specified by \p oinfo, which is defined as a \c struct of
- * type H5O_native_info_t in H5Opublic.h:
- * \snippet this H5O_native_info_t_snip
- *
- * \p idx_type is of type #H5_index_t, defined in H5public.h as:
- * \snippet H5public.h H5_index_t_snip
- *
- * \p order is of type #H5_iter_order_t defined in H5public.h as:
- * \snippet H5public.h H5_iter_order_t_snip
+ * \p n within that index.
*
* The \p fields parameter indicates which fields to fill in H5O_native_info_t.
* Possible values defined in H5Opublic.h are:
@@ -1236,11 +1162,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
@@ -1250,62 +1173,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_iterate2_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 H5Ovisit() \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_info2_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_info2_t \c struct is defined in H5Opublic.h as follows:
- * \snippet this H5O_info2_t_snip
- *
- * H5O_token_t is defined in H5public.h as follows:
- * \snippet H5public.h H5O_token_t_snip
- *
- * The #H5O_type_t enum indicates the object type and is
- * defined in H5Opublic.h as follows:
- * \snippet this H5O_type_t_snip
- *
- * Note that the object retrieved as indicated by \p obj_id
- * refers only to the types specified by #H5O_type_t.
- *
- * 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 H5Ovisit3() \p op_data parameter is a user-defined pointer to the data
* required to process objects in the course of the iteration. This pointer
@@ -1329,24 +1197,6 @@ H5_DLL ssize_t H5Oget_comment_by_name(hid_t loc_id, const char *name, char *comm
* group change during the iteration, the resulting behavior
* is undefined.
*
- * \note \Bold{Programming Note for C++ Developers Using C Functions:}
- * \note If a C routine that takes a function pointer as an argument is
- * called from within C++ code, the C routine should be returned
- * from normally.
- *
- * \note Examples of this kind of routine include callbacks such as
- * H5Pset_elink_cb() and H5Pset_type_conv_cb() and
- * functions such as H5Tconvert() and H5Ewalk2().
- *
- * \note Exiting the routine in its normal fashion allows the HDF5
- * C library to clean up its work properly. In other words, if
- * the C++ application jumps out of the routine back to the C++
- * “catch” statement, the library is not given the opportunity
- * to close any temporary data structures that were set up when
- * the routine was called. The C++ application should save some
- * state as the routine is started so that any problem that occurs
- * might be diagnosed.
- *
* \par Example
* An example snippet from test/links.c:
* \snippet links.c H5Ovisit3_snip
@@ -1411,10 +1261,7 @@ H5_DLL herr_t H5Ovisit3(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
@@ -1425,49 +1272,7 @@ H5_DLL herr_t H5Ovisit3(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 prototype of the callback function op is as follows (as
- * defined in the source code file H5Opublic.h):
- *
- * \snippet this H5O_iterate2_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</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_info2_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_info2_t \c struct is defined in H5Opublic.h as follows:
- * \snippet this H5O_info2_t_snip
- *
- * H5O_token_t is defined in H5public.h as follows:
- * \snippet H5public.h H5O_token_t_snip
- *
- * The #H5O_type_t enum indicates the object type and is
- * defined in H5Opublic.h as follows:
- * \snippet this H5O_type_t_snip
+ * along the index specified in \p idx_type.
*
* The H5Ovisit_by_name3() \p op_data parameter is a user-defined
* pointer to the data required to process objects in the course
@@ -1495,24 +1300,6 @@ H5_DLL herr_t H5Ovisit3(hid_t obj_id, H5_index_t idx_type, H5_iter_order_t order
* in the file has been presented to the application for whatever
* processing the application requires.
*
- * \note \Bold{Programming Note for C++ Developers Using C Functions:}
- * \note If a C routine that takes a function pointer as an argument is
- * called from within C++ code, the C routine should be returned
- * from normally.
- *
- * \note Examples of this kind of routine include callbacks such as
- * H5Pset_elink_cb() and H5Pset_type_conv_cb() and
- * functions such as H5Tconvert() and H5Ewalk2().
- *
- * \note Exiting the routine in its normal fashion allows the HDF5
- * C library to clean up its work properly. In other words, if
- * the C++ application jumps out of the routine back to the C++
- * “catch” statement, the library is not given the opportunity
- * to close any temporary data structures that were set up when
- * the routine was called. The C++ application should save some
- * state as the routine is started so that any problem that occurs
- * might be diagnosed.
- *
* \par Example
* An example snippet from test/links.c:
* \snippet links.c H5Ovisit_by_name3_snip
@@ -1579,26 +1366,11 @@ H5_DLL herr_t H5Oclose_async(const char *app_file, const char *app_func, unsigne
* 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
*
@@ -1670,21 +1442,17 @@ H5_DLL herr_t H5Orefresh_async(const char *app_file, const char *app_func, unsig
* 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
*
@@ -1714,28 +1482,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
*
@@ -1871,6 +1629,7 @@ H5_DLL herr_t H5Otoken_to_str(hid_t loc_id, const H5O_token_t *token, char **tok
*/
H5_DLL herr_t H5Otoken_from_str(hid_t loc_id, const char *token_str, H5O_token_t *token);
+/// \cond DEV
/* API Wrappers for async routines */
/* (Must be defined _after_ the function prototype) */
/* (And must only defined when included in application code, not the library) */
@@ -1894,6 +1653,7 @@ H5_DLL herr_t H5Otoken_from_str(hid_t loc_id, const char *token_str, H5O_token_t
#define H5Orefresh_async_wrap H5_NO_EXPAND(H5Orefresh_async)
#define H5Ocopy_async_wrap H5_NO_EXPAND(H5Ocopy_async)
#endif
+/// \endcond
/* The canonical 'undefined' token value */
#define H5O_TOKEN_UNDEF (H5OPEN H5O_TOKEN_UNDEF_g)
@@ -1908,8 +1668,8 @@ H5_DLLVAR const H5O_token_t H5O_TOKEN_UNDEF_g;
/* Macros */
/* Deprecated flags for earlier versions of H5Oget_info* */
-#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_HDR 0x0008u /**< Fill in the hdr field */
+#define H5O_INFO_META_SIZE 0x0010u /**< Fill in the meta_size field */
#undef H5O_INFO_ALL
#define H5O_INFO_ALL (H5O_INFO_BASIC | H5O_INFO_TIME | H5O_INFO_NUM_ATTRS | H5O_INFO_HDR | H5O_INFO_META_SIZE)
@@ -1942,7 +1702,7 @@ typedef struct H5O_info1_t {
time_t mtime; /**< Modification time */
time_t ctime; /**< Change time */
time_t btime; /**< Birth time */
- hsize_t num_attrs; /**< # of attributes attached to object */
+ hsize_t num_attrs; /**< Number of attributes attached to object */
H5O_hdr_info_t hdr; /**< Object header information */
/* Extra metadata storage for obj & attributes */
struct {
@@ -1955,6 +1715,16 @@ typedef struct H5O_info1_t {
//! <!-- [H5O_iterate1_t_snip] -->
/**
* Prototype for H5Ovisit(), H5Ovisit_by_name() operator (versions 1 & 2)
+ *
+ * \param[in] obj Object that serves as the root of the iteration;
+ * the same value as the H5Ovisit1() \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
+ * \return \herr_t_iter
+ *
*/
typedef herr_t (*H5O_iterate1_t)(hid_t obj, const char *name, const H5O_info1_t *info, void *op_data);
//! <!-- [H5O_iterate1_t_snip] -->
@@ -2027,36 +1797,7 @@ H5_DLL hid_t H5Oopen_by_addr(hid_t loc_id, haddr_t addr);
* the function H5Oget_info3() or the macro #H5Oget_info.
*
* \details H5Oget_info1() specifies an object by its identifier, \p loc_id , and
- * retrieves the metadata describing that object in \p oinfo ,
- * defined as a \c struct of type H5O_info1_t :
- *
- * \snippet this H5O_info1_t_snip
- *
- * Note the following about H5O_info1_t :
- * - Of the four time fields (\c atime, \c mtime, \c ctime, and \c btime)
- * only \c ctime has been implemented.
- * - The \c atime value is the last time the object was read or written.
- * - The \c mtime value is the last time the raw data in the object was changed.
- * - The \c ctime value is the last time the metadata for the object was changed.
- * - The \c btime value is the time the object was created.
- * - The fields nested in the \c meta_size field are for internal library use only.
- *
- * The #H5O_type_t \c enum indicates the object type and
- * is defined in H5Opublic.h as follows:
- * \snippet this H5O_type_t_snip
- *
- * Note that the object retrieved as indicated by \p loc_id
- * refers only to the types specified by #H5O_type_t.
- *
- * An H5O_hdr_info_t \c struct holds object header metadata and is
- * defined in H5Opublic.h as follows:
- * \snippet this H5O_hdr_info_t_snip
- *
- * Valid values for the \c version field are \c H5O_VERSION_1 and \c H5O_VERSION_2.
- * Version 2 of the object header is smaller and more efficient than version 1.
- *
- * Please be aware that the information held by H5O_hdr_info_t may only be useful to
- * developers with extensive HDF5 experience.
+ * 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,
@@ -2156,16 +1897,6 @@ H5_DLL herr_t H5Oget_info_by_name1(hid_t loc_id, const char *name, H5O_info1_t *
* If \p loc_id fully specifies the group in which the object resides,
* \p group_name can be a dot (\c .).
*
- * \p idx_type is of type #H5_index_t, defined in H5public.h as:
- * \snippet H5public.h H5_index_t_snip
- *
- * \p order is of type #H5_iter_order_t defined in H5public.h as:
- * \snippet H5public.h H5_iter_order_t_snip
- *
- * \p oinfo, in which the object information is returned, is a \c struct of
- * type H5O_info1_t .
- * \snippet this H5O_info1_t_snip
- *
* The link access property list, \c lapl_id, is not currently used;
* it should be passed in as #H5P_DEFAULT.
*
@@ -2361,10 +2092,7 @@ H5_DLL herr_t H5Oget_info_by_idx2(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
@@ -2375,56 +2103,7 @@ H5_DLL herr_t H5Oget_info_by_idx2(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
@@ -2438,24 +2117,6 @@ H5_DLL herr_t H5Oget_info_by_idx2(hid_t loc_id, const char *group_name, H5_index
* group change during the iteration, the resulting behavior
* is undefined.
*
- * \note \Bold{Programming Note for C++ Developers Using C Functions:}
- * \note If a C routine that takes a function pointer as an argument is
- * called from within C++ code, the C routine should be returned
- * from normally.
- *
- * \note Examples of this kind of routine include callbacks such as
- * H5Pset_elink_cb() and H5Pset_type_conv_cb() and
- * functions such as H5Tconvert() and H5Ewalk2().
- *
- * \note Exiting the routine in its normal fashion allows the HDF5
- * C library to clean up its work properly. In other words, if
- * the C++ application jumps out of the routine back to the C++
- * “catch” statement, the library is not given the opportunity
- * to close any temporary data structures that were set up when
- * the routine was called. The C++ application should save some
- * state as the routine is started so that any problem that occurs
- * might be diagnosed.
- *
* \version 1.10.5 The macro #H5Ovisit was removed and the function
* H5Ovisit1() was copied to H5Ovisit().
* \version 1.10.3 Function H5Ovisit() was copied to H5Ovisit1(),
@@ -2523,10 +2184,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
@@ -2537,10 +2195,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
@@ -2570,24 +2225,6 @@ H5_DLL herr_t H5Ovisit1(hid_t obj_id, H5_index_t idx_type, H5_iter_order_t order
* in the file has been presented to the application for whatever
* processing the application requires.
*
- * \note \Bold{Programming Note for C++ Developers Using C Functions:}
- * \note If a C routine that takes a function pointer as an argument is
- * called from within C++ code, the C routine should be returned
- * from normally.
- *
- * \note Examples of this kind of routine include callbacks such as
- * H5Pset_elink_cb() and H5Pset_type_conv_cb() and
- * functions such as H5Tconvert() and H5Ewalk2().
- *
- * \note Exiting the routine in its normal fashion allows the HDF5
- * C library to clean up its work properly. In other words, if
- * the C++ application jumps out of the routine back to the C++
- * “catch” statement, the library is not given the opportunity
- * to close any temporary data structures that were set up when
- * the routine was called. The C++ application should save some
- * state as the routine is started so that any problem that occurs
- * might be diagnosed.
- *
* \version 1.10.5 The macro #H5Ovisit_by_name was removed and the function
* H5Ovisit_by_name1() was copied to #H5Ovisit_by_name.
* \version 1.10.3 The H5Ovisit_by_name() function was renamed to H5Ovisit_by_name1(),
@@ -2650,10 +2287,7 @@ H5_DLL herr_t H5Ovisit_by_name1(hid_t loc_id, const char *obj_name, H5_index_t i
* 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
@@ -2664,57 +2298,7 @@ H5_DLL herr_t H5Ovisit_by_name1(hid_t loc_id, const char *obj_name, H5_index_t i
* 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.
- *
- * 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
- * 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.
*
* The \p fields parameter contains flags to determine which fields will
* be retrieved by the \p op callback function. These flags are defined
@@ -2733,23 +2317,6 @@ H5_DLL herr_t H5Ovisit_by_name1(hid_t loc_id, const char *obj_name, H5_index_t i
* group change during the iteration, the resulting behavior
* is undefined.
*
- * \note \Bold{Programming Note for C++ Developers Using C Functions:}
- * \note If a C routine that takes a function pointer as an argument is
- * called from within C++ code, the C routine should be returned
- * from normally.
- *
- * \note Examples of this kind of routine include callbacks such as
- * H5Pset_elink_cb() and H5Pset_type_conv_cb() and
- * functions such as H5Tconvert() and H5Ewalk2().
- *
- * \note Exiting the routine in its normal fashion allows the HDF5
- * C library to clean up its work properly. In other words, if
- * the C++ application jumps out of the routine back to the C++
- * “catch” statement, the library is not given the opportunity
- * to close any temporary data structures that were set up when
- * the routine was called. The C++ application should save some
- * state as the routine is started so that any problem that occurs
- * might be diagnosed.
*
* \since 1.10.3
*
@@ -2814,10 +2381,7 @@ H5_DLL herr_t H5Ovisit2(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
@@ -2828,10 +2392,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
+ * 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
@@ -2866,24 +2427,6 @@ H5_DLL herr_t H5Ovisit2(hid_t obj_id, H5_index_t idx_type, H5_iter_order_t order
* in the file has been presented to the application for whatever
* processing the application requires.
*
- * \note \Bold{Programming Note for C++ Developers Using C Functions:}
- * \note If a C routine that takes a function pointer as an argument is
- * called from within C++ code, the C routine should be returned
- * from normally.
- *
- * \note Examples of this kind of routine include callbacks such as
- * H5Pset_elink_cb() and H5Pset_type_conv_cb() and
- * functions such as H5Tconvert() and H5Ewalk2().
- *
- * \note Exiting the routine in its normal fashion allows the HDF5
- * C library to clean up its work properly. In other words, if
- * the C++ application jumps out of the routine back to the C++
- * “catch” statement, the library is not given the opportunity
- * to close any temporary data structures that were set up when
- * the routine was called. The C++ application should save some
- * state as the routine is started so that any problem that occurs
- * might be diagnosed.
- *
* \since 1.10.3
*
*/
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..6e92e66 100644
--- a/src/H5Pmodule.h
+++ b/src/H5Pmodule.h
@@ -30,49 +30,165 @@
#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 MAPL Map 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 10609b2..5e9c4ab 100644
--- a/src/H5Ppublic.h
+++ b/src/H5Ppublic.h
@@ -100,7 +100,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
@@ -113,14 +115,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] -->
@@ -159,12 +170,25 @@ typedef herr_t (*H5P_prp_cb2_t)(hid_t prop_id, const char *name, size_t size, vo
typedef H5P_prp_cb1_t H5P_prp_create_func_t;
typedef H5P_prp_cb2_t H5P_prp_set_func_t;
typedef H5P_prp_cb2_t H5P_prp_get_func_t;
+//! <!-- [H5P_prp_encode_func_t_snip] -->
+/**
+ * \todo Document me!
+ */
typedef herr_t (*H5P_prp_encode_func_t)(const void *value, void **buf, size_t *size);
+//! <!-- [H5P_prp_encode_func_t_snip] -->
+//! <!-- [H5P_prp_decode_func_t_snip] -->
+/**
+ * \todo Document me!
+ */
typedef herr_t (*H5P_prp_decode_func_t)(const void **buf, void *value);
+//! <!-- [H5P_prp_decode_func_t_snip] -->
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] -->
@@ -172,6 +196,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] -->
@@ -2211,7 +2238,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
*
@@ -2220,6 +2247,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.
@@ -5237,7 +5266,7 @@ H5_DLL herr_t H5Pget_vol_cap_flags(hid_t plist_id, unsigned *cap_flags);
#ifdef H5_HAVE_PARALLEL
/**
- * \ingroup GACPL
+ * \ingroup GAPL
*
* \brief Sets metadata I/O mode for read operations to collective or independent (default)
*
@@ -5306,7 +5335,7 @@ H5_DLL herr_t H5Pget_vol_cap_flags(hid_t plist_id, unsigned *cap_flags);
*/
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
*
@@ -6266,6 +6295,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.
@@ -6337,6 +6368,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.
*
@@ -6430,6 +6463,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.
*
@@ -6539,6 +6574,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.
@@ -9455,9 +9492,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 */
@@ -9571,8 +9605,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 b33960e..ef798ea 100644
--- a/src/H5Rpublic.h
+++ b/src/H5Rpublic.h
@@ -30,9 +30,11 @@
#define H5R_OBJ_REF_BUF_SIZE sizeof(haddr_t)
#define H5R_DSET_REG_REF_BUF_SIZE (sizeof(haddr_t) + 4)
-/* Default reference buffer size.
- * Note! Be careful with the sizes of the references because they should really
- * depend on the run-time values in the file.
+/**
+ * Default reference buffer size.
+ *
+ * \internal Note! Be careful with the sizes of the references because they
+ * should really depend on the run-time values in the file.
*/
#define H5R_REF_BUF_SIZE (64)
@@ -560,6 +562,7 @@ H5_DLL ssize_t H5Rget_obj_name(H5R_ref_t *ref_ptr, hid_t rapl_id, char *name, si
*/
H5_DLL ssize_t H5Rget_attr_name(const H5R_ref_t *ref_ptr, char *name, size_t size);
+/// \cond DEV
/* API Wrappers for async routines */
/* (Must be defined _after_ the function prototype) */
/* (And must only defined when included in application code, not the library) */
@@ -574,6 +577,7 @@ H5_DLL ssize_t H5Rget_attr_name(const H5R_ref_t *ref_ptr, char *name, size_t siz
#define H5Ropen_region_async_wrap H5_NO_EXPAND(H5Ropen_region_async)
#define H5Ropen_attr_async_wrap H5_NO_EXPAND(H5Ropen_attr_async)
#endif /* H5R_MODULE */
+/// \endcond
/* Symbols defined for compatibility with previous versions of the HDF5 API.
*
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 7962035..30ca813 100644
--- a/src/H5Spublic.h
+++ b/src/H5Spublic.h
@@ -26,98 +26,101 @@
#define H5S_BLOCK 1 /* (hid_t) */
#define H5S_PLIST 2 /* (hid_t) */
-/* Define value for 'unlimited' dimensions */
-#define H5S_UNLIMITED HSIZE_UNDEF
+#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
/* Flags for selection iterators */
#define H5S_SEL_ITER_GET_SEQ_LIST_SORTED \
- 0x0001 /* Retrieve elements from iterator \
- * in increasing offset order, for \
- * each call to retrieve sequences. \
- * Currently, this only applies to \
- * point selections, as hyperslab \
- * selections are always returned \
- * in increasing offset order. \
- * \
- * Note that the order is only \
- * increasing for each call to \
- * get_seq_list, the next set of \
- * sequences could start with an \
- * earlier offset than the previous \
- * one. \
+ 0x0001 /**< Retrieve elements from iterator in increasing offset order, for \
+ * each call to retrieve sequences. Currently, this only applies to \
+ * point selections, as hyperslab selections are always returned in \
+ * increasing offset order. Note that the order is only increasing \
+ * for each call to H5Sget_seq_list(), the next set of sequences \
+ * could start with an earlier offset than the previous one. \
*/
#define H5S_SEL_ITER_SHARE_WITH_DATASPACE \
- 0x0002 /* Don't copy the dataspace \
- * selection when creating the \
- * selection iterator. \
- * \
- * This can improve performance \
- * of creating the iterator, but \
- * the dataspace _MUST_NOT_ be \
- * modified or closed until the \
- * selection iterator is closed \
- * or the iterator's behavior \
- * will be undefined. \
+ 0x0002 /**< Don't copy the dataspace selection when creating the selection \
+ * iterator. This can improve performance of creating the iterator, \
+ * but the dataspace \Bold{MUST NOT} be modified or closed until the \
+ * selection iterator is closed or the iterator's behavior will be \
+ * undefined. \
*/
-/* 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
@@ -1318,9 +1321,6 @@ H5_DLL herr_t H5Sset_extent_none(hid_t space_id);
* \details H5Sset_extent_simple() sets or resets the size of an existing
* dataspace.
*
- * \p rank is the dimensionality, or number of dimensions, of the
- * dataspace.
- *
* \p dims is an array of size \p rank which contains the new size
* of each dimension in the dataspace. \p max is an array of size
* \p rank which contains the maximum size of each dimension in
@@ -1329,10 +1329,6 @@ H5_DLL herr_t H5Sset_extent_none(hid_t space_id);
* Any previous extent is removed from the dataspace, the dataspace
* type is set to #H5S_SIMPLE, and the extent is set as specified.
*
- * Note that a dataset must be chunked if \p dims does not equal
- * \p max.
- *
- *
* \version 1.4.0 Fortran subroutine was introduced.
* \since 1.0.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/H5VLmodule.h b/src/H5VLmodule.h
index 009c0e5..8fcb961 100644
--- a/src/H5VLmodule.h
+++ b/src/H5VLmodule.h
@@ -27,14 +27,12 @@
#define H5_MY_PKG_ERR H5E_VOL
#define H5_MY_PKG_INIT YES
-/**
- * \defgroup H5VL H5VL
- * \brief Virtual Object Layer Interface
- * \todo Describe concisely what the functions in this module are about.
+/**\defgroup H5VL H5VL
+ *
+ * \todo Describe the VOL plugin life cycle.
*
* \defgroup ASYNC Asynchronous Functions
* \brief Asynchronous Functions
- * \todo Describe concisely what the functions in this module are about.
*
* \defgroup H5VLDEF Definitions
* \ingroup H5VL
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 64081bf..6d3cba8 100644
--- a/src/H5module.h
+++ b/src/H5module.h
@@ -27,8 +27,31 @@
#define H5_MY_PKG_INIT YES
/**\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 e7ed518..65709c6 100644
--- a/src/H5public.h
+++ b/src/H5public.h
@@ -172,8 +172,9 @@
* 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");
@@ -182,11 +183,17 @@
typedef int herr_t;
/**
- * Boolean type. Successful return values are zero (false) or positive
- * (true). The typical true value is 1 but don't bet on it. Boolean
- * functions cannot fail. Functions that return #htri_t however return zero
- * (false), positive (true), or negative (failure). The proper way to test
- * for truth from a #htri_t function is:
+ * C99-style Boolean type. Successful return values are zero (false) or positive
+ * (true). The typical true value is 1 but don't bet on it.
+ * \attention Boolean functions cannot fail.
+ */
+#include <stdbool.h>
+typedef bool hbool_t;
+/**
+ * Three-valued Boolean type. Functions that return #htri_t however return zero
+ * (false), positive (true), or negative (failure).
+ *
+ * The proper way to test for truth from a #htri_t function is:
* \code
* if ((retval = H5Tcommitted(type)) > 0) {
* printf("data type is committed\n");
@@ -197,8 +204,7 @@ typedef int herr_t;
* }
* \endcode
*/
-typedef bool hbool_t;
-typedef int htri_t;
+typedef int htri_t;
/* The signed version of size_t
*
@@ -285,9 +291,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] -->
/**
generated by cgit v0.12 at 2024-11-01 06:09:11 (GMT)