summaryrefslogtreecommitdiffstats
path: root/src
diff options
context:
space:
mode:
Diffstat (limited to 'src')
-rw-r--r--src/CMakeLists.txt4
-rw-r--r--src/H5Amodule.h24
-rw-r--r--src/H5Apublic.h265
-rw-r--r--src/H5Dmodule.h8
-rw-r--r--src/H5Dpublic.h503
-rw-r--r--src/H5Emodule.h75
-rw-r--r--src/H5Epublic.h56
-rw-r--r--src/H5Fmodule.h19
-rw-r--r--src/H5Fpublic.h2
-rw-r--r--src/H5Gmodule.h25
-rw-r--r--src/H5Imodule.h81
-rw-r--r--src/H5Ipublic.h33
-rw-r--r--src/H5Lmodule.h27
-rw-r--r--src/H5Lpublic.h2
-rw-r--r--src/H5Mmodule.h6
-rw-r--r--src/H5Omodule.h41
-rw-r--r--src/H5Opublic.h680
-rw-r--r--src/H5PLmodule.h30
-rw-r--r--src/H5Pmodule.h164
-rw-r--r--src/H5Ppublic.h74
-rw-r--r--src/H5Rmodule.h29
-rw-r--r--src/H5Rpublic.h8
-rw-r--r--src/H5Smodule.h45
-rw-r--r--src/H5Spublic.h113
-rw-r--r--src/H5Tmodule.h36
-rw-r--r--src/H5VLmodule.h10
-rw-r--r--src/H5Zmodule.h109
-rw-r--r--src/H5module.h33
-rw-r--r--src/H5public.h11
29 files changed, 1151 insertions, 1362 deletions
diff --git a/src/CMakeLists.txt b/src/CMakeLists.txt
index ba43d7d..3fb3072 100644
--- a/src/CMakeLists.txt
+++ b/src/CMakeLists.txt
@@ -1389,15 +1389,17 @@ if (DOXYGEN_FOUND)
set (DOXYGEN_OPTIMIZE_OUTPUT_FOR_C YES)
set (DOXYGEN_MACRO_EXPANSION YES)
set (DOXYGEN_OUTPUT_DIRECTORY ${HDF5_BINARY_DIR}/hdf5lib_docs)
- set (DOXYGEN_EXAMPLES_DIRECTORY "${HDF5_DOXYGEN_DIR}/examples ${HDF5_SRC_DIR} ${HDF5_SOURCE_DIR}/examples ${HDF5_TEST_SRC_DIR}")
+ set (DOXYGEN_EXAMPLES_DIRECTORY "${HDF5_DOXYGEN_DIR}/dox/cookbook ${HDF5_DOXYGEN_DIR}/examples ${HDF5_SRC_DIR} ${HDF5_SOURCE_DIR}/examples ${HDF5_TEST_SRC_DIR}")
set (DOXYGEN_LAYOUT_FILE ${HDF5_DOXYGEN_DIR}/hdf5doxy_layout.xml)
set (DOXYGEN_HTML_HEADER ${HDF5_DOXYGEN_DIR}/hdf5_header.html)
set (DOXYGEN_HTML_FOOTER ${HDF5_DOXYGEN_DIR}/hdf5_footer.html)
set (DOXYGEN_HTML_EXTRA_STYLESHEET ${HDF5_DOXYGEN_DIR}/hdf5doxy.css)
set (DOXYGEN_HTML_EXTRA_FILES "${HDF5_DOXYGEN_DIR}/hdf5_navtree_hacks.js ${HDF5_DOXYGEN_DIR}/img/ftv2node.png ${HDF5_DOXYGEN_DIR}/img/ftv2pnode.png")
+ set (DOXYGEN_TAG_FILE ${HDF5_BINARY_DIR}/hdf5.tag)
set (DOXYGEN_SERVER_BASED_SEARCH NO)
set (DOXYGEN_EXTERNAL_SEARCH NO)
set (DOXYGEN_SEARCHENGINE_URL)
+ set (DOXYGEN_PREDEFINED H5_HAVE_DIRECT H5_HAVE_LIBHDFS H5_HAVE_MAP_API H5_HAVE_PARALLEL H5_HAVE_ROS3_VFD)
# This configure and custom target work together
# Replace variables inside @@ with the current values
diff --git a/src/H5Amodule.h b/src/H5Amodule.h
index c89c93f..9f86ddd 100644
--- a/src/H5Amodule.h
+++ b/src/H5Amodule.h
@@ -33,33 +33,29 @@
*
* Use the functions in this module to manage HDF5 attributes.
*
- * The Attribute Interface, H5A, provides a mechanism for attaching additional
- * information to a dataset, group, or named datatype.
- *
- * Attributes are accessed by opening the object that they are attached to and
- * are not independent objects. Typically an attribute is small in size and
- * contains user metadata about the object that it is attached to.
- *
- * Attributes look similar to HDF5 datasets in that they have a datatype and
- * dataspace. However, they do not support partial I/O operations and cannot be
- * compressed or extended.
+ * Like HDF5 datasets, HDF5 attributes are array variables which have an element
+ * datatype and a shape (dataspace). However, they perform a different function:
+ * Attributes decorate other HDF5 objects, and are typically used to
+ * represent application metadata. Unlike datasets, the HDF5 library does not
+ * support partial I/O operations for attributes and they cannot be compressed
+ * or extended.
*
* <table>
* <tr><th>Create</th><th>Read</th></tr>
* <tr valign="top">
* <td>
- * \snippet H5A_examples.c create
+ * \snippet{lineno} H5A_examples.c create
* </td>
* <td>
- * \snippet H5A_examples.c read
+ * \snippet{lineno} H5A_examples.c read
* </td>
* <tr><th>Update</th><th>Delete</th></tr>
* <tr valign="top">
* <td>
- * \snippet H5A_examples.c update
+ * \snippet{lineno} H5A_examples.c update
* </td>
* <td>
- * \snippet H5A_examples.c delete
+ * \snippet{lineno} H5A_examples.c delete
* </td>
* </tr>
* </table>
diff --git a/src/H5Apublic.h b/src/H5Apublic.h
index 0198668..410eb1e 100644
--- a/src/H5Apublic.h
+++ b/src/H5Apublic.h
@@ -78,11 +78,11 @@ extern "C" {
*
* \return \herr_t
*
- * \details H5Aclose() terminates access to the attribute specified by
- * \p attr_id by releasing the identifier.
+ * \details H5Aclose() terminates access to the attribute through
+ * \p attr_id and releases the identifier.
*
- * \attention Further use of a released attribute identifier is illegal; a
- * function using such an identifier will generate an error.
+ * \par Example
+ * \snippet H5A_examples.c create
*
* \since 1.0.0
*
@@ -110,27 +110,19 @@ H5_DLL herr_t H5Aclose(hid_t attr_id);
* The attribute name, \p attr_name, must be unique for the object.
*
* The attribute is created with the specified datatype and dataspace,
- * \p type_id and \p space_id, which are created with the H5T and
- * H5S interfaces, respectively.
+ * \p type_id and \p space_id.
*
- * If \p type_id is either a fixed-length or variable-length string,
- * it is important to set the string length when defining the
- * datatype. String datatypes are derived from #H5T_C_S1 (or
- * #H5T_FORTRAN_S1 for Fortran), which defaults to 1 character in
- * size. See H5Tset_size() and Creating variable-length string
- * datatypes.
- *
- * The access property list is currently unused, but will be used in
- * the future. This property list should currently be #H5P_DEFAULT.
+ * \plist_unused{acpl}
*
* The attribute identifier returned by this function must be released
* with H5Aclose() resource leaks will develop.
*
- * \note The \p aapl parameter is currently not used; specify #H5P_DEFAULT.
- *
* \note If \p loc_id is a file identifier, the attribute will be attached
* that file’s root group.
*
+ * \par Example
+ * \snippet H5A_examples.c create
+ *
* \since 1.8.0
*
* \see H5Aclose()
@@ -160,28 +152,19 @@ H5_DLL hid_t H5Acreate2(hid_t loc_id, const char *attr_name, hid_t type_id, hid_
* attached to the object specified by \p loc_id and \p obj_name.
*
* \p loc_id is a location identifier; \p obj_name is the object
- * name relative to \p loc_id. If \p loc_id fully specifies the
- * object to which the attribute is to be attached, \p obj_name
- * should be '.' (a dot).
+ * name relative to \p loc_id.
*
* The attribute name, \p attr_name, must be unique for the object.
*
* The attribute is created with the specified datatype and
- * dataspace, \p type_id and \p space_id, which are created with
- * the H5T and H5S interfaces respectively.
+ * dataspace, \p type_id and \p space_id.
*
- * The attribute creation and access property lists are currently
- * unused, but will be used in the future for optional attribute
- * creation and access properties. These property lists should
- * currently be #H5P_DEFAULT.
+ * \plist_unused{aapl}
*
* The link access property list, \p lapl_id, may provide
* information regarding the properties of links required to access
* the object, \p obj_name.
*
- * The attribute identifier returned by this function must be
- * released with H5close() or resource leaks will develop.
- *
* \since 1.8.0
*
*/
@@ -200,10 +183,14 @@ H5_DLL hid_t H5Acreate_by_name(hid_t loc_id, const char *obj_name, const char *a
*
* \details H5Adelete() removes the attribute specified by its name,
* \p attr_name, from a file, dataset, group, or named datatype.
- * This function should not be used when attribute identifiers
- * are open on \p loc_id as it may cause the internal indexes of
- * the attributes to change and future writes to the open
- * attributes to produce incorrect results.
+ *
+ * \attention This function should not be used when other attribute identifiers
+ * are open on \p loc_id. This may cause the internal indexes of
+ * the attributes to change and future writes to the open
+ * attributes to produce incorrect results.
+ *
+ * \par Example
+ * \snippet H5A_examples.c delete
*
* \since 1.0.0
*
@@ -230,27 +217,16 @@ H5_DLL herr_t H5Adelete(hid_t loc_id, const char *attr_name);
*
* The object from which the attribute is to be removed is
* specified by a location identifier and name, \p loc_id and
- * \p obj_name, respectively. If \p loc_id fully specifies the
- * object from which the attribute is to be removed, \p obj_name
- * should be '.' (a dot).
+ * \p obj_name, respectively.
*
* The attribute to be removed is specified by a position in an
- * index, \p n. The type of index is specified by \p idx_type and
- * may be #H5_INDEX_NAME, for an alpha-numeric index by name, or
- * #H5_INDEX_CRT_ORDER, for an index by creation order. The order
- * in which the index is to be traversed is specified by \p order
- * and may be #H5_ITER_INC (increment) for top-down iteration,
- * #H5_ITER_DEC (decrement) for bottom-up iteration, or
- * #H5_ITER_NATIVE, in which case HDF5 will iterate in the
- * fastest-available order. For example, if \p idx_type, \p order,
+ * index, \p n. The type of index is specified by \p idx_type.
+ * The order in which the index is to be traversed is specified by
+ * \p order. For example, if \p idx_type, \p order,
* and \p n are set to #H5_INDEX_NAME, #H5_ITER_INC, and 5,
- * respectively, the fifth attribute by alpha-numeric order of
+ * respectively, the fifth attribute in lexicographic order of
* attribute names will be removed.
*
- * For a discussion of \p idx_type and \p order, the valid values
- * of those parameters, and the use of \p n, see the description
- * of H5Aiterate2().
- *
* The link access property list, \p lapl_id, may provide
* information regarding the properties of links required to access
* the object, \p obj_name.
@@ -278,9 +254,6 @@ H5_DLL herr_t H5Adelete_by_idx(hid_t loc_id, const char *obj_name, H5_index_t id
* from an object specified by location and name, \p loc_id and
* \p obj_name, respectively.
*
- * If \p loc_id fully specifies the object from which the
- * attribute is to be removed, \p obj_name should be '.' (a dot).
- *
* The link access property list, \p lapl_id, may provide
* information regarding the properties of links required to
* access the object, \p obj_name.
@@ -329,9 +302,7 @@ H5_DLL htri_t H5Aexists(hid_t obj_id, const char *attr_name);
* \p loc_id specifies a location in the file containing the object.
* \p obj_name is the name of the object to which the attribute is
* attached and can be a relative name, relative to \p loc_id,
- * or an absolute name, based in the root group of the file. If
- * \p loc_id fully specifies the object, \p obj_name should be '.'
- * (a dot).
+ * or an absolute name, based in the root group of the file.
*
* The link access property list, \p lapl_id, may provide
* information regarding the properties of links required to access
@@ -355,9 +326,6 @@ H5_DLL htri_t H5Aexists_by_name(hid_t obj_id, const char *obj_name, const char *
* creation property list associated with the attribute specified
* by \p attr_id.
*
- * The creation property list identifier should be released with
- * H5Pclose().
- *
* \since 1.8.0
*
*/
@@ -374,32 +342,9 @@ H5_DLL hid_t H5Aget_create_plist(hid_t attr_id);
* \return \herr_t
*
* \details H5Aget_info() retrieves attribute information, locating the
- * attribute with an attribute identifier, \p attr_id, which is
- * the identifier returned by H5Aopen() or H5Aopen_by_idx(). The
+ * attribute with an attribute identifier, \p attr_id. The
* attribute information is returned in the \p ainfo struct.
*
- * The \p ainfo struct is defined as follows:
- * \snippet this H5A_info_t_snip
- *
- * \p corder_valid indicates whether the creation order data is
- * valid for this attribute. Note that if creation order is not
- * being tracked, no creation order data will be valid. Valid
- * values are \c TRUE and \c FALSE.
- *
- * \p corder is a positive integer containing the creation
- * order of the attribute. This value is 0-based, so, for
- * example, the third attribute created will have a \p corder
- * value of 2.
- *
- * \p cset indicates the character set used for the attribute’s
- * name; valid values are defined in H5Tpublic.h and include
- * the following:
- * \csets
- * This value is set with H5Pset_char_encoding().
- *
- * \p data_size indicates the size, in the number of characters,
- * of the attribute.
- *
* \since 1.8.0
*
*/
@@ -427,16 +372,9 @@ H5_DLL herr_t H5Aget_info(hid_t attr_id, H5A_info_t *ainfo /*out*/);
* The attribute is located by its index position and the attribute
* information is returned in the \p ainfo struct.
*
- * If \p loc_id fully specifies the object to which the attribute
- * is attached, \p obj_name should be '.' (a dot).
- *
* The attribute is located by means of an index type, an index
* traversal order, and a position in the index, \p idx_type,
- * \p order and \p n, respectively. These parameters and their
- * valid values are discussed in the description of H5Aiterate2().
- *
- * The \p ainfo struct, which will contain the returned attribute
- * information, is described in H5Aget_info().
+ * \p order and \p n, respectively.
*
* The link access property list, \p lapl_id, may provide
* information regarding the properties of links required to access
@@ -454,8 +392,7 @@ H5_DLL herr_t H5Aget_info_by_idx(hid_t loc_id, const char *obj_name, H5_index_t
* \brief Retrieves attribute information, by attribute name
*
* \fgdt_loc_id
- *
- * \param[in] obj_name Name of object to which attribute is attached,
+ * \param[in] obj_name Name of the object to which an attribute is attached,
* relative to location
* \param[in] attr_name Attribute name
* \param[out] ainfo Struct containing returned attribute information
@@ -468,11 +405,6 @@ H5_DLL herr_t H5Aget_info_by_idx(hid_t loc_id, const char *obj_name, H5_index_t
* location and name, \p loc_id and \p obj_name, respectively.
* The attribute information is returned in the \p ainfo struct.
*
- * If \p loc_id fully specifies the object to which the attribute
- * is attached, \p obj_name should be '.' (a dot).
- *
- * The \p ainfo struct is described in H5Aget_info().
- *
* The link access property list, \p lapl_id, may provide
* information regarding the properties of links required to
* access the object, \p obj_name.
@@ -503,8 +435,8 @@ H5_DLL herr_t H5Aget_info_by_name(hid_t loc_id, const char *obj_name, const char
* string terminator is stored in the last position of the buffer
* to properly terminate the string.
*
- * If the user only wants to find out the size of this name, the
- * values 0 and NULL can be passed in for the parameters
+ * If the user only wants to retrieve the name length, the
+ * values 0 and NULL should be passed for the parameters
* \p bufsize and \p buf.
*
* \since 1.0.0
@@ -515,7 +447,7 @@ H5_DLL ssize_t H5Aget_name(hid_t attr_id, size_t buf_size, char *buf);
/**
* \ingroup H5A
*
- * \brief Gets an attribute name, by attribute index position
+ * \brief Gets an attribute name by attribute index position
*
* \fgdt_loc_id
* \param[in] obj_name Name of object to which attribute is attached,
@@ -536,13 +468,9 @@ H5_DLL ssize_t H5Aget_name(hid_t attr_id, size_t buf_size, char *buf);
* located by its index position, the size of the name is specified
* in \p size, and the attribute name is returned in \p name.
*
- * If \p loc_id fully specifies the object to which the attribute
- * is attached, \p obj_name should be '.' (a dot).
- *
* The attribute is located by means of an index type, an index
* traversal order, and a position in the index, \p idx_type,
- * \p order and \p n, respectively. These parameters and their
- * valid values are discussed in the description of H5Aiterate2().
+ * \p order and \p n, respectively.
*
* If the attribute name’s size is unknown, the values 0 and NULL
* can be passed in for the parameters \p size and \p name. The
@@ -582,7 +510,7 @@ H5_DLL hid_t H5Aget_space(hid_t attr_id);
/**
* \ingroup H5A
*
- * \brief Returns the amount of storage required for an attribute
+ * \brief Returns the amount of storage used to store an attribute
*
* \attr_id
*
@@ -600,17 +528,16 @@ H5_DLL hsize_t H5Aget_storage_size(hid_t attr_id);
/**
* \ingroup H5A
*
- * \brief Gets an attribute datatype
+ * \brief Gets an attribute's datatype
*
* \attr_id
*
* \return \hid_t{datatype}
*
- * \details H5Aget_type() retrieves a copy of the datatype for an attribute.
+ * \details H5Aget_type() retrieves a copy of the attribute's datatype.
* The datatype is reopened if it is a named type before returning
* it to the application. The datatypes returned by this function
- * are always read-only. If an error occurs when atomizing the
- * return datatype, then the datatype is closed.
+ * are always read-only.
*
* The datatype identifier returned from this function must be
* released with H5Tclose() or resource leaks will develop.
@@ -623,7 +550,7 @@ H5_DLL hid_t H5Aget_type(hid_t attr_id);
/**
* \ingroup H5A
*
- * \brief Calls user-defined function for each attribute on an object
+ * \brief Calls a user-defined function for each attribute on an object
*
* \fgdt_loc_id
* \param[in] idx_type Type of index
@@ -650,17 +577,6 @@ H5_DLL hid_t H5Aget_type(hid_t attr_id);
* are specified by three parameters: the index type,
* \p idx_type; the order in which the index is to be traversed,
* \p order; and the attribute’s position in the index, \p idx.
- *
- * The type of index specified by \p idx_type can be one of the
- * following:
- *
- * \indexes
- *
- * The order in which the index is to be traversed, as specified
- * by \p order, can be one of the following:
- *
- * \orders
- *
* The next attribute to be operated on is specified by \p idx,
* a position in the index.
*
@@ -677,11 +593,6 @@ H5_DLL hid_t H5Aget_type(hid_t attr_id);
* the value returned identifies the parameter to be operated on
* in the next step of the iteration.
*
- * \p op is a user-defined function whose prototype is defined
- * as follows:
- * \snippet this H5A_operator2_t_snip
- * \click4more
- *
* \note This function is also available through the H5Aiterate() macro.
*
* \since 1.8.0
@@ -717,24 +628,10 @@ H5_DLL herr_t H5Aiterate2(hid_t loc_id, H5_index_t idx_type, H5_iter_order_t ord
* additional information as defined below, is passed to a
* user-defined function, \p op, which operates on that attribute.
*
- * If \p loc_id fully specifies the object to which these
- * attributes are attached, \p obj_name should be '.' (a dot).
- *
* The order of the iteration and the attributes iterated over
* are specified by three parameters: the index type, \p idx_type;
* the order in which the index is to be traversed, \p order;
* and the attribute’s position in the index, \p idx.
- *
- * The type of index specified by \p idx_type can be one of the
- * following:
- *
- * \indexes
- *
- * The order in which the index is to be traversed, as specified
- * by \p order, can be one of the following:
- *
- * \orders
- *
* The next attribute to be operated on is specified by \p idx,
* a position in the index.
*
@@ -751,25 +648,6 @@ H5_DLL herr_t H5Aiterate2(hid_t loc_id, H5_index_t idx_type, H5_iter_order_t ord
* the value returned identifies the parameter to be operated on in
* the next step of the iteration.
*
- * \p op is a user-defined function whose prototype is defined
- * as follows:
- * \snippet this H5A_operator2_t_snip
- * \click4more
- *
- * Valid return values from an operator and the resulting
- * H5Aiterate_by_name() and \p op behavior are as follows:
- *
- * \li Zero causes the iterator to continue, returning zero when
- * all attributes have been processed.
- * \li A positive value causes the iterator to immediately return
- * that positive value, indicating short-circuit success.
- * The iterator can be restarted at the next attribute, as
- * indicated by the return value of \p idx.
- * \li A negative value causes the iterator to immediately return
- * that value, indicating failure. The iterator can be
- * restarted at the next attribute, as indicated by the return
- * value of \p idx.
- *
* The link access property list, \p lapl_id, may provide
* information regarding the properties of links required to access
* the object, \p obj_name.
@@ -796,8 +674,7 @@ H5_DLL herr_t H5Aiterate_by_name(hid_t loc_id, const char *obj_name, H5_index_t
* \details H5Aopen() opens an existing attribute, \p attr_name, that is
* attached to object specified by an object identifier, \p obj_id.
*
- * The attribute access property list, \p aapl_id, is currently unused
- * and should be #H5P_DEFAULT.
+ * \plist_unused{aapl_id}
*
* This function, H5Aopen_by_idx() or H5Aopen_by_name() must be called
* before the attribute can be accessed for any further purpose,
@@ -806,6 +683,9 @@ H5_DLL herr_t H5Aiterate_by_name(hid_t loc_id, const char *obj_name, H5_index_t
* The attribute identifier returned by this function must be released
* with H5Aclose() or resource leaks will develop.
*
+ * \par Example
+ * \snippet H5A_examples.c read
+ *
* \since 1.8.0
*
* \see H5Aclose(), H5Acreate()
@@ -830,17 +710,13 @@ H5_DLL hid_t H5Aopen(hid_t obj_id, const char *attr_name, hid_t aapl_id);
*
* \details H5Aopen_by_idx() opens an existing attribute that is attached
* to an object specified by location and name, \p loc_id and
- * \p obj_name, respectively. If \p loc_id fully specifies the
- * object to which the attribute is attached, \p obj_name, should
- * be '.' (a dot).
+ * \p obj_name, respectively.
*
* The attribute is identified by an index type, an index traversal
* order, and a position in the index, \p idx_type, \p order and
- * \p n, respectively. These parameters and their valid values are
- * discussed in the description of H5Aiterate2().
+ * \p n, respectively.
*
- * The attribute access property list, \p aapl_id, is currently
- * unused and should currently be #H5P_DEFAULT.
+ * \plist_unused{aapl_id}
*
* The link access property list, \p lapl_id, may provide
* information regarding the properties of links required to access
@@ -879,11 +755,9 @@ H5_DLL hid_t H5Aopen_by_idx(hid_t loc_id, const char *obj_name, H5_index_t idx_t
*
* \p loc_id specifies a location from which the target object can
* be located and \p obj_name is an object name relative to
- * \p loc_id. If \p loc_id fully specifies the object to which the
- * attribute is attached, \p obj_name should be '.' (a dot).
+ * \p loc_id.
*
- * The attribute access property list, \p aapl_id, is currently
- * unused and should currently be #H5P_DEFAULT.
+ * \plist_unused{aapl_id}
*
* The link access property list, \p lapl_id, may provide
* information regarding the properties of links required to access
@@ -920,6 +794,9 @@ H5_DLL hid_t H5Aopen_by_name(hid_t loc_id, const char *obj_name, const char *att
* Datatype conversion takes place at the time of a read or write and
* is automatic.
*
+ * \par Example
+ * \snippet H5A_examples.c read
+ *
* \version 1.8.8 Fortran updated to Fortran2003.
* \version 1.4.2 The \p dims parameter was added to the Fortran API in this
* release.
@@ -967,15 +844,12 @@ H5_DLL herr_t H5Arename(hid_t loc_id, const char *old_name, const char *new_name
* attribute's in-memory datatype is specified with \p type_id.
* The entire attribute is written from \p buf to the file.
*
- * If \p type_id is either a fixed-length or variable-length string,
- * it is important to set the string length when defining the datatype.
- * String datatypes are derived from #H5T_C_S1 (or #H5T_FORTRAN_S1 for
- * Fortran codes), which defaults to 1 character in size.
- * See H5Tset_size() and Creating variable-length string datatypes.
- *
* Datatype conversion takes place at the time of a read or write and
* is automatic.
*
+ * \par Example
+ * \snippet H5A_examples.c update
+ *
* \version 1.8.8 Fortran updated to Fortran2003.
* \version 1.4.2 Fortran \p dims parameter added in this release
* \since 1.0.0
@@ -1057,9 +931,9 @@ typedef herr_t (*H5A_operator1_t)(hid_t location_id /*in*/, const char *attr_nam
*
* \return \hid_tv{attribute}
*
- * \note The \p acpl parameters is currently not used; specify #H5P_DEFAULT.
+ * \deprecation_note{H5Acreate2()}
*
- * \deprecated Deprecated in favor of H5Acreate2()
+ * \plist_unused{acpl}
*
* \details H5Acreate1() creates an attribute, \p name, which is attached
* to the object specified by the identifier \p loc_id.
@@ -1067,18 +941,7 @@ typedef herr_t (*H5A_operator1_t)(hid_t location_id /*in*/, const char *attr_nam
* The attribute name, \p name, must be unique for the object.
*
* The attribute is created with the specified datatype and dataspace,
- * \p type_id and \p space_id, which are created with the H5T and
- * H5S interfaces, respectively.
- *
- * If \p type_id is either a fixed-length or variable-length string,
- * it is important to set the string length when defining the
- * datatype. String datatypes are derived from #H5T_C_S1 (or
- * #H5T_FORTRAN_S1 for Fortran), which defaults to 1 character in
- * size. See H5Tset_size() and Creating variable-length string
- * datatypes.
- *
- * The attribute identifier returned by this function must be released
- * with H5Aclose() resource leaks will develop.
+ * \p type_id and \p space_id.
*
* \since 1.8.0
*
@@ -1100,8 +963,7 @@ H5_DLL hid_t H5Acreate1(hid_t loc_id, const char *name, hid_t type_id, hid_t spa
* \return Returns the number of attributes if successful; otherwise returns
* a negative value.
*
- * \deprecated This function is deprecated in favor of the functions
- * H5Oget_info(), H5Oget_info_by_name(), and H5Oget_info_by_idx().
+ * \deprecation_note{H5Oget_info(), H5Oget_info_by_name(), and H5Oget_info_by_idx()}
*
* \details H5Aget_num_attrs() returns the number of attributes attached to
* the object specified by its identifier, \p loc_id.
@@ -1124,8 +986,7 @@ H5_DLL int H5Aget_num_attrs(hid_t loc_id);
*
* \return \herr_t
*
- * \deprecated This function is deprecated in favor of the function
- * H5Aiterate2().
+ * \deprecation_note{H5Aiterate2()}
*
* \details H5Aiterate1() iterates over the attributes of the object
* specified by its identifier, \p loc_id. The object can be a
@@ -1137,10 +998,6 @@ H5_DLL int H5Aget_num_attrs(hid_t loc_id);
* \p op, is returned in \p idx. If \p idx is the null pointer,
* then all attributes are processed.
*
- * \p op is a user-defined function whose prototype is defined as follows:
- * \snippet this H5A_operator1_t_snip
- * \click4more
- *
* \version 1.8.0 The function \p H5Aiterate was renamed to H5Aiterate1()
* and deprecated in this release.
* \since 1.0.0
@@ -1158,8 +1015,7 @@ H5_DLL herr_t H5Aiterate1(hid_t loc_id, unsigned *idx, H5A_operator1_t op, void
*
* \return \hid_tv{attribute}
*
- * \deprecated This function is deprecated in favor of the function
- * H5Aopen_by_idx().
+ * \deprecation_note{H5Aopen_by_idx()}
*
* \details H5Aopen_idx() opens an attribute which is attached to the
* object specified with \p loc_id . The location object may be
@@ -1185,8 +1041,7 @@ H5_DLL hid_t H5Aopen_idx(hid_t loc_id, unsigned idx);
*
* \return \hid_tv{attribute}
*
- * \deprecated This function is deprecated in favor of the function
- * H5Aopen_by_name().
+ * \deprecation_note{H5Aopen_by_name()}
*
* \details H5Aopen_name() opens an attribute specified by its name,
* \p name, which is attached to the object specified with
diff --git a/src/H5Dmodule.h b/src/H5Dmodule.h
index 595c714..596fd48 100644
--- a/src/H5Dmodule.h
+++ b/src/H5Dmodule.h
@@ -44,18 +44,18 @@
* <tr><th>Create</th><th>Read</th></tr>
* <tr valign="top">
* <td>
- * \snippet H5D_examples.c create
+ * \snippet{lineno} H5D_examples.c create
* </td>
* <td>
- * \snippet H5D_examples.c read
+ * \snippet{lineno} H5D_examples.c read
* </td>
* <tr><th>Update</th><th>Delete</th></tr>
* <tr valign="top">
* <td>
- * \snippet H5D_examples.c update
+ * \snippet{lineno} H5D_examples.c update
* </td>
* <td>
- * \snippet H5D_examples.c delete
+ * \snippet{lineno} H5D_examples.c delete
* </td>
* </tr>
* </table>
diff --git a/src/H5Dpublic.h b/src/H5Dpublic.h
index 2094ff3..26e54d4 100644
--- a/src/H5Dpublic.h
+++ b/src/H5Dpublic.h
@@ -30,9 +30,11 @@
/* Macros used to "unset" chunk cache configuration parameters */
#define H5D_CHUNK_CACHE_NSLOTS_DEFAULT ((size_t)-1)
#define H5D_CHUNK_CACHE_NBYTES_DEFAULT ((size_t)-1)
-#define H5D_CHUNK_CACHE_W0_DEFAULT (-1.0f)
+#define H5D_CHUNK_CACHE_W0_DEFAULT (-1.0)
-/* Bit flags for the H5Pset_chunk_opts() and H5Pget_chunk_opts() */
+/**
+ * Bit flags for the H5Pset_chunk_opts() and H5Pget_chunk_opts()
+ */
#define H5D_CHUNK_DONT_FILTER_PARTIAL_CHUNKS (0x0002u)
/*******************/
@@ -44,13 +46,12 @@
* Values for the H5D_LAYOUT property
*/
typedef enum H5D_layout_t {
- H5D_LAYOUT_ERROR = -1,
-
- H5D_COMPACT = 0, /**< raw data is very small */
- H5D_CONTIGUOUS = 1, /**< the default */
- H5D_CHUNKED = 2, /**< slow and fancy */
- H5D_VIRTUAL = 3, /**< actual data is stored in other datasets */
- H5D_NLAYOUTS = 4 /**< this one must be last! */
+ H5D_LAYOUT_ERROR = -1, /**< error */
+ H5D_COMPACT = 0, /**< raw data is small (< 64KB) */
+ H5D_CONTIGUOUS = 1, /**< contiguous layout */
+ H5D_CHUNKED = 2, /**< chunked or tiled layout */
+ H5D_VIRTUAL = 3, /**< actual data is stored in other datasets */
+ H5D_NLAYOUTS = 4 /**< this one must be last! */
} H5D_layout_t;
//! <!-- [H5D_layout_t_snip] -->
@@ -75,11 +76,11 @@ typedef enum H5D_chunk_index_t {
* Values for the space allocation time property
*/
typedef enum H5D_alloc_time_t {
- H5D_ALLOC_TIME_ERROR = -1,
- H5D_ALLOC_TIME_DEFAULT = 0,
- H5D_ALLOC_TIME_EARLY = 1,
- H5D_ALLOC_TIME_LATE = 2,
- H5D_ALLOC_TIME_INCR = 3
+ H5D_ALLOC_TIME_ERROR = -1, /**< Error */
+ H5D_ALLOC_TIME_DEFAULT = 0, /**< \todo Define this! */
+ H5D_ALLOC_TIME_EARLY = 1, /**< Allocate on creation */
+ H5D_ALLOC_TIME_LATE = 2, /**< Allocate on first write */
+ H5D_ALLOC_TIME_INCR = 3 /**< Allocate incrementally (by chunk) */
} H5D_alloc_time_t;
//! <!-- [H5D_alloc_time_t_snip] -->
@@ -88,10 +89,11 @@ typedef enum H5D_alloc_time_t {
* Values for the status of space allocation
*/
typedef enum H5D_space_status_t {
- H5D_SPACE_STATUS_ERROR = -1,
- H5D_SPACE_STATUS_NOT_ALLOCATED = 0,
- H5D_SPACE_STATUS_PART_ALLOCATED = 1,
- H5D_SPACE_STATUS_ALLOCATED = 2
+ H5D_SPACE_STATUS_ERROR = -1, /**< Error */
+ H5D_SPACE_STATUS_NOT_ALLOCATED = 0, /**< Space has not been allocated for this dataset. */
+ H5D_SPACE_STATUS_PART_ALLOCATED = 1, /**< Space has been allocated for this dataset. */
+ H5D_SPACE_STATUS_ALLOCATED = 2 /**< Space has been partially allocated for this dataset. (Used only for
+ datasets with chunked storage.) */
} H5D_space_status_t;
//! <!-- [H5D_space_status_t_snip] -->
@@ -100,10 +102,10 @@ typedef enum H5D_space_status_t {
* Values for time of writing fill value property
*/
typedef enum H5D_fill_time_t {
- H5D_FILL_TIME_ERROR = -1,
- H5D_FILL_TIME_ALLOC = 0,
- H5D_FILL_TIME_NEVER = 1,
- H5D_FILL_TIME_IFSET = 2
+ H5D_FILL_TIME_ERROR = -1, /**< Error */
+ H5D_FILL_TIME_ALLOC = 0, /**< Fill on allocation */
+ H5D_FILL_TIME_NEVER = 1, /**< Never write fill values */
+ H5D_FILL_TIME_IFSET = 2 /**< Fill if fill-value was set */
} H5D_fill_time_t;
//! <!-- [H5D_fill_time_t_snip] -->
@@ -112,10 +114,10 @@ typedef enum H5D_fill_time_t {
* Values for fill value status
*/
typedef enum H5D_fill_value_t {
- H5D_FILL_VALUE_ERROR = -1,
- H5D_FILL_VALUE_UNDEFINED = 0,
- H5D_FILL_VALUE_DEFAULT = 1,
- H5D_FILL_VALUE_USER_DEFINED = 2
+ H5D_FILL_VALUE_ERROR = -1, /**< Error */
+ H5D_FILL_VALUE_UNDEFINED = 0, /**< No fill value defined */
+ H5D_FILL_VALUE_DEFAULT = 1, /**< Default fill-value */
+ H5D_FILL_VALUE_USER_DEFINED = 2 /**< User-defined fill-value */
} H5D_fill_value_t;
//! <!-- [H5D_fill_value_t_snip] -->
@@ -124,22 +126,40 @@ typedef enum H5D_fill_value_t {
* Values for VDS bounds option
*/
typedef enum H5D_vds_view_t {
- H5D_VDS_ERROR = -1,
- H5D_VDS_FIRST_MISSING = 0,
- H5D_VDS_LAST_AVAILABLE = 1
+ H5D_VDS_ERROR = -1, /**< Error */
+ H5D_VDS_FIRST_MISSING = 0, /**< \todo Define this! */
+ H5D_VDS_LAST_AVAILABLE = 1 /**< \todo Define this! */
} H5D_vds_view_t;
//! <!-- [H5D_vds_view_t_snip] -->
//! <!-- [H5D_append_cb_t_snip] -->
/**
- * Callback for H5Pset_append_flush() in a dataset access property list
+ * \brief Callback for H5Pset_append_flush()
+ *
+ * \dset_id{dataset_id}
+ * \param[in] cur_dims The current extent of the dataset's dimensions
+ * \param[in,out] op_data User context
+ *
+ * \return \herr_t
+ *
*/
typedef herr_t (*H5D_append_cb_t)(hid_t dataset_id, hsize_t *cur_dims, void *op_data);
//! <!-- [H5D_append_cb_t_snip] -->
//! <!-- [H5D_operator_t_snip] -->
/**
- * Define the operator function pointer for H5Diterate()
+ * \brief Callback for H5Diterate()
+ *
+ * \param[in,out] elem Pointer to the memory buffer containing the current dataset
+ * element
+ * \param[in] type_id Datatype identifier of the elements stored in \pelem
+ * \param[in] ndim Number of dimensions for the \p point array
+ * \param[in] point Array containing the location of the element within
+ * the original dataspace
+ * \param[in,out] operator_data Pointer to any user-defined data associated with
+ * the operation
+ * \return \herr_t_iter
+ *
*/
typedef herr_t (*H5D_operator_t)(void *elem, hid_t type_id, unsigned ndim, const hsize_t *point,
void *operator_data);
@@ -147,7 +167,29 @@ typedef herr_t (*H5D_operator_t)(void *elem, hid_t type_id, unsigned ndim, const
//! <!-- [H5D_scatter_func_t_snip] -->
/**
- * Define the operator function pointer for H5Dscatter()
+ * \brief Callback for H5Dscatter()
+ *
+ * \param[out] src_buf Pointer to the buffer holding the next set of elements to
+ * scatter. On entry, the value of where \p src_buf points to
+ * is undefined. The callback function should set \p src_buf
+ * to point to the next set of elements.
+ * \param[out] src_buf_bytes_used Pointer to the number of valid bytes in \p src_buf.
+ * On entry, the value where \p src_buf_bytes_used points
+ * to is undefined. The callback function should set
+ * \p src_buf_bytes_used to the of valid bytes in \p src_buf.
+ * This number must be a multiple of the datatype size.
+ * \param[in,out] op_data User-defined pointer to data required by the callback
+ * function. A pass-through of the \p op_data pointer provided
+ * with the H5Dscatter() function call.
+ * \return herr_t
+ *
+ * \details The callback function should always return at least one
+ * element in \p src_buf, and must not return more elements
+ * than are remaining to be scattered. This function will be
+ * repeatedly called until all elements to be scattered have
+ * been returned. The callback function should return zero (0)
+ * to indicate success, and a negative value to indicate failure.
+ *
*/
typedef herr_t (*H5D_scatter_func_t)(const void **src_buf /*out*/, size_t *src_buf_bytes_used /*out*/,
void *op_data);
@@ -155,7 +197,27 @@ typedef herr_t (*H5D_scatter_func_t)(const void **src_buf /*out*/, size_t *src_b
//! <!-- [H5D_gather_func_t_snip] -->
/**
- * Define the operator function pointer for H5Dgather()
+ * \brief Callback for H5Dgather()
+ *
+ * \param[in] dst_buf Pointer to the destination buffer which has been filled
+ * with the next set of elements gathered. This will always
+ * be identical to the \p dst_buf passed to H5Dgather()
+ * \param[in] dst_buf_bytes_used Pointer to the number of valid bytes in
+ * \p dst_buf. This number must be a multiple of
+ * the datatype size.
+ * \param[in,out] op_data User-defined pointer to data required by the callback
+ * function; a pass-through of the \p op_data pointer
+ * provided with the H5Dgather() function call.
+ * \returns \herr_t
+ *
+ * \details The callback function should process, store, or otherwise make use
+ * of the data returned in dst_buf before it returns, because the
+ * buffer will be overwritten unless it is the last call to the
+ * callback. This function will be repeatedly called until all gathered
+ * elements have been passed to the callback in dst_buf. The callback
+ * function should return zero (0) to indicate success, and a negative
+ * value to indicate failure.
+ *
*/
typedef herr_t (*H5D_gather_func_t)(const void *dst_buf, size_t dst_buf_bytes_used, void *op_data);
//! <!-- [H5D_gather_func_t_snip] -->
@@ -178,7 +240,7 @@ extern "C" {
* \brief Creates a new dataset and links it into the file
*
* \fgdta_loc_id
- * \param[in] name Name of the dataset to create
+ * \param[in] name Name of the dataset to create
* \type_id
* \space_id
* \lcpl_id
@@ -203,13 +265,6 @@ extern "C" {
* \p name may be either an absolute path in the file or a relative
* path from \p loc_id naming the dataset.
*
- * \p dtype_id specifies the datatype of each data element as stored
- * in the file. If \p dtype_id is either a fixed-length or
- * variable-length string, it is important to set the string length
- * when defining the datatype. String datatypes are derived from
- * #H5T_C_S1 (or #H5T_FORTRAN_S1 for Fortran codes), which defaults
- * to 1 character in size.
- *
* If \p dtype_id is a committed datatype, and if the file location
* associated with the committed datatype is different from the
* file location where the dataset will be created, the datatype
@@ -217,7 +272,7 @@ extern "C" {
*
* The link creation property list, \p lcpl_id, governs creation
* of the link(s) by which the new dataset is accessed and the
- * creation of any * intermediate groups that may be missing.
+ * creation of any intermediate groups that may be missing.
*
* The datatype and dataspace properties and the dataset creation
* and access property lists are attached to the dataset, so the
@@ -228,8 +283,8 @@ extern "C" {
* not previously written, the HDF5 library will return default
* or user-defined fill values.
*
- * To conserve and release resources, the dataset should be closed
- * when access is no longer required.
+ * \par Example
+ * \snippet H5D_examples.c create
*
* \since 1.8.0
*
@@ -268,34 +323,14 @@ H5_DLL hid_t H5Dcreate2(hid_t loc_id, const char *name, hid_t type_id, hid_t spa
* the file, which may differ from the datatype and dataspace
* in application memory.
*
- * Dataset creation property list and dataset access creation
- * property list are specified by \p dcpl_id and \p dapl_id.
- *
* H5Dcreate_anon() returns a new dataset identifier. Using
* this identifier, the new dataset must be linked into the
* HDF5 file structure with H5Olink() or it will be deleted
- * from the file when the file is closed.
- *
- * See H5Dcreate2() for further details and considerations on
- * the use of H5Dcreate2() and H5Dcreate_anon().
- *
- * The differences between this function and H5Dcreate2() are
- * as follows:
- * \li H5Dcreate_anon() explicitly includes a dataset access property
- * list. H5Dcreate() always uses default dataset access properties.
- *
- * \li H5Dcreate_anon() neither provides the new dataset’s name nor
- * links it into the HDF5 file structure; those actions must be
- * performed separately through a call to H5Olink(), which offers
- * greater control over linking.
- *
- * A dataset created with this function should be closed with
- * H5Dclose() when the dataset is no longer needed so that resource
- * leaks will not develop.
+ * when the file is closed.
*
* \since 1.8.0
*
- * \see H5Olink(), H5Dcreate(), Using Identifiers
+ * \see H5Olink(), H5Dcreate()
*
*/
H5_DLL hid_t H5Dcreate_anon(hid_t loc_id, hid_t type_id, hid_t space_id, hid_t dcpl_id, hid_t dapl_id);
@@ -321,12 +356,6 @@ H5_DLL hid_t H5Dcreate_anon(hid_t loc_id, hid_t type_id, hid_t space_id, hid_t d
* specified then the dataset will be opened at the location
* where the attribute, dataset, or named datatype is attached.
*
- * The dataset access property list, \p dapl_id, provides
- * information regarding access to the dataset.
- *
- * To conserve and release resources, the dataset should be closed
- * when access is no longer required.
- *
* \since 1.8.0
*
* \see H5Dcreate2(), H5Dclose()
@@ -352,6 +381,9 @@ H5_DLL hid_t H5Dopen2(hid_t loc_id, const char *name, hid_t dapl_id);
* be released with H5Sclose() when the identifier is no longer
* needed so that resource leaks will not occur.
*
+ * \par Example
+ * \snippet H5D_examples.c update
+ *
* \see H5Sclose()
*
*/
@@ -360,7 +392,19 @@ H5_DLL hid_t H5Dget_space(hid_t dset_id);
/**
* --------------------------------------------------------------------------
* \ingroup H5D
- * \todo Document this function!
+ *
+ * \brief Determines whether space has been allocated for a dataset
+ *
+ * \dset_id
+ * \param[out] allocation Space allocation status
+ *
+ * \return \herr_t
+ *
+ * \details H5Dget_space_status() determines whether space has been allocated
+ * for the dataset \p dset_id.
+ *
+ * \since 1.6.0
+ *
*/
H5_DLL herr_t H5Dget_space_status(hid_t dset_id, H5D_space_status_t *allocation);
@@ -379,27 +423,7 @@ H5_DLL herr_t H5Dget_space_status(hid_t dset_id, H5D_space_status_t *allocation)
*
* If a dataset has a named datatype, then an identifier to the
* opened datatype is returned. Otherwise, the returned datatype
- * is read-only. If atomization of the datatype fails, then the
- * datatype is closed.
- *
- * A datatype identifier returned from this function should be
- * released with H5Tclose() when the identifier is no longer
- * needed to prevent resource leaks.
- *
- * \note Datatype Identifiers
- *
- * Please note that the datatype identifier is actually an object
- * identifier or a handle returned from opening the datatype. It
- * is not persistent and its value can be different from one HDF5
- * session to the next.
- *
- * H5Tequal() can be used to compare datatypes.
- *
- * HDF5 High Level APIs that may also be of interest are:
- *
- * H5LTdtype_to_text() creates a text description of a
- * datatype. H5LTtext_to_dtype() creates an HDF5 datatype
- * given a text description.
+ * is read-only.
*
*/
H5_DLL hid_t H5Dget_type(hid_t dset_id);
@@ -419,9 +443,6 @@ H5_DLL hid_t H5Dget_type(hid_t dset_id);
* a copy of the dataset creation property list associated with
* the dataset specified by \p dset_id.
*
- * The creation property list identifier should be released
- * with H5Pclose() to prevent resource leaks.
- *
*/
H5_DLL hid_t H5Dget_create_plist(hid_t dset_id);
@@ -455,10 +476,6 @@ H5_DLL hid_t H5Dget_create_plist(hid_t dset_id);
* All link access properties in the returned list will be set
* to the default values.
*
- * The access property list identifier should be released with
- * H5Pclose() when the identifier is no longer needed so that
- * resource leaks will not develop.
- *
* \since 1.8.3
*
*/
@@ -477,11 +494,8 @@ H5_DLL hid_t H5Dget_access_plist(hid_t dset_id);
* \details H5Dget_storage_size() returns the amount of storage,
* in bytes, that is allocated in the file for the raw data of
* the dataset specified by \p dset_id.
- *
- * \note The amount of storage in this case is the storage
- * allocated in the written file, which will typically differ
- * from the space required to hold a dataset in working memory.
- *
+ * H5Dget_storage_size() reports only the space required to store
+ * the dataset elements, excluding any metadata.
* \li For contiguous datasets, the returned size equals the current
* allocated size of the raw data.
* \li For unfiltered chunked datasets, the returned size is the
@@ -491,21 +505,19 @@ H5_DLL hid_t H5Dget_access_plist(hid_t dset_id);
* compression filter is in use, H5Dget_storage_size() will return
* the total space required to store the compressed chunks.
*
- * H5Dget_storage_size() reports only the space required to store
- * the data, not including that of any metadata.
+ * \note Note that H5Dget_storage_size() is not generally an
+ * appropriate function to use when determining the amount
+ * of memory required to work with a dataset. In such
+ * circumstances, you must determine the number of data
+ * points in a dataset and the size of an individual dataset
+ * element. H5Sget_simple_extent_npoints() and H5Tget_size()
+ * can be used to calculate that amount.
*
- * \attention H5Dget_storage_size() does not differentiate between 0 (zero),
+ * \warning H5Dget_storage_size() does not differentiate between 0 (zero),
* the value returned for the storage size of a dataset
* with no stored values, and 0 (zero), the value returned to
* indicate an error.
*
- * \note Note that H5Dget_storage_size() is not generally an
- * appropriate function to use when determining the amount
- * of memory required to work with a dataset. In such
- * circumstances, you must determine the number of data
- * points in a dataset and the size of an individual data
- * element. H5Sget_simple_extent_npoints() and H5Tget_size()
- * can be used to get that information.
*
*/
H5_DLL hsize_t H5Dget_storage_size(hid_t dset_id);
@@ -562,7 +574,7 @@ H5_DLL herr_t H5Dget_chunk_storage_size(hid_t dset_id, const hsize_t *offset, hs
* effect. Also, the implementation does not handle the #H5S_ALL
* macro correctly. As a workaround, application can get
* the dataspace for the dataset using H5Dget_space() and pass that
- * in for \p fspace_id. This will be fixed in coming releases.
+ * in for \p fspace_id. This will be fixed in a future release.
*
* \since 1.10.5
*
@@ -617,16 +629,16 @@ H5_DLL herr_t H5Dget_chunk_info_by_coord(hid_t dset_id, const hsize_t *offset, u
*
* \return \herr_t
*
- * \details H5Dget_chunk_info() retrieves the offset coordinates
- * offset, filter mask filter_mask, size size and address addr for
- * the dataset specified by the identifier dset_id and the chunk
- * specified by the index index. The chunk belongs to a set of
- * chunks in the selection specified by fspace_id. If the queried
+ * \details H5Dget_chunk_info() retrieves the offset coordinates,
+ * \p offset, filter mask, \p filter_mask, size, \p size, and address
+ * \p addr for the dataset specified by the identifier \p dset_id and the chunk
+ * specified by the index \p index. The chunk belongs to a set of
+ * chunks in the selection specified by \p fspace_id. If the queried
* chunk does not exist in the file, the size will be set to 0 and
- * address to \c HADDR_UNDEF. The value pointed to by filter_mask will
- * not be modified. NULL can be passed in for any \p out parameters.
+ * address to #HADDR_UNDEF. The value pointed to by filter_mask will
+ * not be modified. \c NULL can be passed in for any \p out parameters.
*
- * \p chk_idx is the chunk index in the selection. Index value
+ * \p chk_idx is the chunk index in the selection. The index value
* may have a value of 0 up to the number of chunks stored in
* the file that have a nonempty intersection with the file
* dataspace selection
@@ -640,9 +652,9 @@ H5_DLL herr_t H5Dget_chunk_info_by_coord(hid_t dset_id, const hsize_t *offset, u
* \note Please be aware that this function currently does not
* support non-trivial selections, thus \p fspace_id has no
* effect. Also, the implementation does not handle the #H5S_ALL
- * macro correctly. As a workaround, application can get
+ * macro correctly. As a workaround, an application can get
* the dataspace for the dataset using H5Dget_space() and pass that
- * in for \p fspace_id. This will be fixed in coming releases.
+ * in for \p fspace_id. This will be fixed in a future release.
*
* \since 1.10.5
*
@@ -658,7 +670,7 @@ H5_DLL herr_t H5Dget_chunk_info(hid_t dset_id, hid_t fspace_id, hsize_t chk_idx,
*
* \dset_id
*
- * \return Returns the offset in bytes; otherwise, returns \c HADDR_UNDEF,
+ * \return Returns the offset in bytes; otherwise, returns #HADDR_UNDEF,
* a negative value.
*
* \details H5Dget_offset() returns the address in the file of
@@ -707,9 +719,8 @@ H5_DLL haddr_t H5Dget_offset(hid_t dset_id);
* used for the memory dataspace and the selection defined with \p
* file_space_id is used for the selection within that dataspace.
*
- * If raw data storage space has not been allocated for the dataset
- * and a fill value has been defined, the returned buffer \p buf
- * is filled with the fill value.
+ * The number of elements selected in the memory dataspace \Emph{must}
+ * be equal to the number of elements selected in the file dataspace.
*
* The behavior of the library for the various combinations of
* valid dataspace identifiers and #H5S_ALL for the \p mem_space_id
@@ -754,14 +765,12 @@ H5_DLL haddr_t H5Dget_offset(hid_t dset_id);
* </tr>
* </table>
*
- * \details Setting an #H5S_ALL selection indicates that the entire
- * dataspace, as defined by the current dimensions of a dataspace,
- * will be selected. The number of elements selected in the memory
- * dataspace must match the number of elements selected in the
- * file dataspace.
+ * \note If no storage space was allocated for the dataset
+ * and a fill value is defined, the returned buffer \p buf
+ * is filled with the fill value.
*
- * \p dxpl_id can be the constant #H5P_DEFAULT, in which case the
- * default data transfer properties are used.
+ * \par Example
+ * \snippet H5D_examples.c read
*
*/
H5_DLL herr_t H5Dread(hid_t dset_id, hid_t mem_type_id, hid_t mem_space_id, hid_t file_space_id,
@@ -865,6 +874,8 @@ H5_DLL herr_t H5Dread(hid_t dset_id, hid_t mem_type_id, hid_t mem_space_id, hid_
* time if the dataset's fill time is set to #H5D_FILL_TIME_IFSET
* or #H5D_FILL_TIME_ALLOC.
*
+ * \par_compr_note
+ *
* \attention If a dataset's storage layout is 'compact', care must be
* taken when writing data to the dataset in parallel. A compact
* dataset's raw data is cached in memory and may be flushed
@@ -872,6 +883,9 @@ H5_DLL herr_t H5Dread(hid_t dset_id, hid_t mem_type_id, hid_t mem_space_id, hid_
* applications should always attempt to write identical data to
* the dataset from all processes.
*
+ * \par Example
+ * \snippet H5D_examples.c update
+ *
* \see H5Pset_fill_time(), H5Pset_alloc_time()
*
*/
@@ -903,11 +917,6 @@ H5_DLL herr_t H5Dwrite(hid_t dset_id, hid_t mem_type_id, hid_t mem_space_id, hid
* pipeline, including filters, and will be written directly to
* the file. Only one chunk can be written with this function.
*
- * H5Dwrite_chunk() replaces the now deprecated H5DOwrite_chunk()
- * function, which was located in the high level optimization
- * library. The parameters and behavior are identical to the
- * original.
- *
* \p filters is a mask providing a record of which filters are
* used with the the chunk. The default value of the mask is
* zero (0), indicating that all enabled filters are applied. A
@@ -935,11 +944,10 @@ H5_DLL herr_t H5Dwrite(hid_t dset_id, hid_t mem_type_id, hid_t mem_space_id, hid
* in a file. H5Dwrite_chunk() bypasses hyperslab selection, the
* conversion of data from one datatype to another, and the filter
* pipeline to write the chunk. Developers should have experience
- * with these processes before using this function. Please see
- * Using the Direct Chunk Write Function for more information.
+ * with these processes before using this function.
*
- * \note H5Dread_chunk() and H5Dwrite_chunk() are not supported under
- * parallel and do not support variable length types.
+ * \note H5Dread_chunk() and H5Dwrite_chunk() are currently not supported
+ * with parallel HDF5 and do not support variable-length types.
*
* \since 1.10.2
*
@@ -977,10 +985,10 @@ H5_DLL herr_t H5Dwrite_chunk(hid_t dset_id, hid_t dxpl_id, uint32_t filters, con
* the dimension limits and must specify a point that falls on
* a dataset chunk boundary.
*
- * The mask \p filters indicates which filters are used with the
- * chunk when written. A zero value indicates that all enabled
- * filters are applied on the chunk. A filter is skipped if the
- * bit corresponding to the filter’s position in the pipeline
+ * The mask \p filters indicates which filters were used when the
+ * chunk was written. A zero value (all bits 0) indicates that all
+ * enabled filters are applied on the chunk. A filter is skipped if
+ * the bit corresponding to the filter’s position in the pipeline
* (0 ≤ position < 32) is turned on.
*
* \p buf is the memory buffer containing the chunk read from
@@ -994,8 +1002,8 @@ H5_DLL herr_t H5Dwrite_chunk(hid_t dset_id, hid_t dxpl_id, uint32_t filters, con
* with these processes before using this function. Please see
* Using the Direct Chunk Write Function for more information.
*
- * \note H5Dread_chunk() and H5Dwrite_chunk() are not supported under
- * parallel and do not support variable length types.
+ * \note H5Dread_chunk() and H5Dwrite_chunk() are currently not supported
+ * with parallel HDF5 and do not support variable-length datatypes.
*
* \since 1.10.2
*
@@ -1025,52 +1033,9 @@ H5_DLL herr_t H5Dread_chunk(hid_t dset_id, hid_t dxpl_id, const hsize_t *offset,
* in the memory buffer \p buf, executing the callback function
* \p op once for each such data element.
*
- * The prototype of the callback function \p op is as follows
- * (as defined in the source code file H5Lpublic.h):
- * \snippet this H5D_operator_t_snip
- * The parameters of this callback function are:
- *
- * <table>
- * <tr><td>\c elem</td>
- * <td><tt>[in,out]</tt></td>
- * <td>Pointer to the memory buffer containing the current
- * data element</td></tr>
- * <tr><td>\c type_id</td>
- * <td><tt>[in]</tt></td>
- * <td>Datatype identifier of the elements stored in elem</td></tr>
- * <tr><td>\c ndim</td>
- * <td><tt>[in]</tt></td>
- * <td>Number of dimensions for the point array</td></tr>
- * <tr><td>\c point</td>
- * <td><tt>[in]</tt></td>
- * <td>Array containing the location of the element within
- * the original dataspace</td></tr>
- * <tr><td>\c operator_data</td>
- * <td><tt>[in,out]</tt></td>
- * <td>Pointer to any user-defined data associated with the
- * operation</td></tr>
- * </table>
- *
- * The possible return values from the callback function, and
- * the effect ofeach,are as follows:
- *
- * \li Zero causes the iterator to continue, returning zero
- * when all data elements have been processed.
- * \li A positive value causes the iterator to immediately
- * return that positive value, indicating short-circuit success.
- * \li A negative value causes the iterator to immediately return
- * that value, indicating failure.
- *
- * The \p operator_data parameter is a user-defined pointer to
- * the data required to process dataset elements in the course
- * of the iteration. If operator needs to pass data back to the
- * application, such data can be returned in this same buffer. This
- * pointer is passed back to each step of the iteration in the
- * operator callback function’s operator_data parameter.
- *
- * Unlike other HDF5 iterators, this iteration operation cannot
- * be restarted at the point of exit; a second H5Diterate()
- * call will always restart at the beginning.
+ * \attention Unlike other HDF5 iterators, this iteration operation cannot
+ * be restarted at the point of exit; a second H5Diterate()
+ * call will always restart at the beginning.
*
*
* \since 1.10.2
@@ -1120,30 +1085,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);
@@ -1190,22 +1150,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
*
@@ -1232,6 +1191,8 @@ H5_DLL herr_t H5Dset_extent(hid_t dset_id, const hsize_t size[]);
* open files. After that, the OS is responsible for ensuring
* that the data is actually flushed to disk.
*
+ * \since 1.10.0
+ *
*/
H5_DLL herr_t H5Dflush(hid_t dset_id);
@@ -1290,40 +1251,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
*
@@ -1375,27 +1303,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
@@ -1419,11 +1329,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
*
@@ -1476,8 +1386,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
@@ -1543,8 +1452,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,
@@ -1574,10 +1482,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:
@@ -1597,7 +1505,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.
*
*/
@@ -1615,8 +1523,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.
@@ -1634,7 +1541,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/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 e0aecac..9dfd1fc 100644
--- a/src/H5Epublic.h
+++ b/src/H5Epublic.h
@@ -295,6 +295,26 @@ H5_DLL hid_t H5Eget_current_stack(void);
* --------------------------------------------------------------------------
* \ingroup H5E
*
+ * \brief Appends one error stack to another, optionally closing the source
+ * stack.
+ *
+ * \estack_id{dst_stack_id}
+ * \estack_id{src_stack_id}
+ * \param[in] close_source_stack Flag to indicate whether to close the source stack
+ * \return \herr_t
+ *
+ * \details H5Eappend_stack() appends the messages from error stack
+ * \p src_stack_id to the error stack \p dst_stack_id.
+ * If \p close_source_stack is \c TRUE, the source error stack
+ * will be closed.
+ *
+ * \since 1.13.0
+ */
+H5_DLL herr_t H5Eappend_stack(hid_t dst_stack_id, hid_t src_stack_id, hbool_t close_source_stack);
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5E
+ *
* \brief Closes an error stack handle
*
* \estack_id{stack_id}
@@ -696,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);
/**
@@ -717,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
@@ -743,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);
/**
@@ -761,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
@@ -771,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);
@@ -785,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:
@@ -795,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);
/**
@@ -809,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
@@ -825,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);
/**
@@ -840,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.
*
@@ -857,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);
/**
@@ -871,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.
*
@@ -878,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);
/**
@@ -891,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.
*
@@ -900,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 96ac0e1..41ad559 100644
--- a/src/H5Fpublic.h
+++ b/src/H5Fpublic.h
@@ -189,7 +189,7 @@ typedef enum H5F_libver_t {
H5F_LIBVER_V18 = 1, /**< Use the latest v18 format for storing objects */
H5F_LIBVER_V110 = 2, /**< Use the latest v110 format for storing objects */
H5F_LIBVER_V112 = 3, /**< Use the latest v112 format for storing objects */
- H5F_LIBVER_NBOUNDS
+ H5F_LIBVER_NBOUNDS /**< Sentinel */
} H5F_libver_t;
#define H5F_LIBVER_LATEST H5F_LIBVER_V112
diff --git a/src/H5Gmodule.h b/src/H5Gmodule.h
index fe26bd2..a0e121d 100644
--- a/src/H5Gmodule.h
+++ b/src/H5Gmodule.h
@@ -29,8 +29,29 @@
#define H5_MY_PKG_ERR H5E_SYM
#define H5_MY_PKG_INIT YES
-/**
- * \defgroup H5G H5G
+/** \defgroup H5G H5G
+ *
+ * Use the functions in this module to manage HDF5 groups.
+ *
+ * <table>
+ * <tr><th>Create</th><th>Read</th></tr>
+ * <tr valign="top">
+ * <td>
+ * \snippet{lineno} H5G_examples.c create
+ * </td>
+ * <td>
+ * \snippet{lineno} H5G_examples.c read
+ * </td>
+ * <tr><th>Update</th><th>Delete</th></tr>
+ * <tr valign="top">
+ * <td>
+ * \snippet{lineno} H5G_examples.c update
+ * </td>
+ * <td>
+ * \snippet{lineno} H5G_examples.c delete
+ * </td>
+ * </tr>
+ * </table>
*
* \details \Bold{Groups in HDF5:} A group associates names with objects and
* provides a mechanism for mapping a name to an object. Since all
diff --git a/src/H5Imodule.h b/src/H5Imodule.h
index a2174d7..d77591d 100644
--- a/src/H5Imodule.h
+++ b/src/H5Imodule.h
@@ -30,8 +30,85 @@
#define H5_MY_PKG_INIT NO
/**\defgroup H5I H5I
- * \brief Identifier Interface
- * \todo Describe concisely what the functions in this module are about.
+ *
+ * Use the functions in this module to manage identifiers defined by the HDF5
+ * library. See \ref H5IUD for user-defined identifiers and identifier
+ * types.
+ *
+ * HDF5 identifiers are usually created as a side-effect of creating HDF5
+ * entities such as groups, datasets, attributes, or property lists.
+ *
+ * Identifiers defined by the HDF5 library can be used to retrieve information
+ * such as path names and reference counts, and their validity can be checked.
+ *
+ * Identifiers can be updated by manipulating their reference counts.
+ *
+ * Unused identifiers should be reclaimed by closing the associated item, e.g.,
+ * HDF5 object, or decrementing the reference count to 0.
+ *
+ * \note Identifiers (of type \ref hid_t) are run-time auxiliaries and
+ * not persisted in the file.
+ *
+ * <table>
+ * <tr><th>Create</th><th>Read</th></tr>
+ * <tr valign="top">
+ * <td>
+ * \snippet{lineno} H5I_examples.c create
+ * </td>
+ * <td>
+ * \snippet{lineno} H5I_examples.c read
+ * </td>
+ * <tr><th>Update</th><th>Delete</th></tr>
+ * <tr valign="top">
+ * <td>
+ * \snippet{lineno} H5I_examples.c update
+ * </td>
+ * <td>
+ * \snippet{lineno} H5I_examples.c delete
+ * </td>
+ * </tr>
+ * </table>
+ *
+ * \defgroup H5IUD User-defined ID Types
+ * \ingroup H5I
+ *
+ * The \ref H5I module contains functions to define new identifier types.
+ * For convenience, handles of type \ref hid_t can then be associated with the
+ * new identifier types and user objects.
+ *
+ * New identifier types can be created by registering a new identifier type
+ * with the HDF5 library. Once a new identifier type has bee registered,
+ * it can be used to generate identifiers for user objects.
+ *
+ * User-defined identifier types can be searched and iterated.
+ *
+ * Like library-defined identifiers, user-defined identifiers \Emph{and}
+ * identifier types are reference counted, and the reference counts can be
+ * manipulated accordingly.
+ *
+ * User-defined identifiers no longer in use should be deleted or reclaimed,
+ * and identifier types should be destroyed if they are no longer required.
+ *
+ * <table>
+ * <tr><th>Create</th><th>Read</th></tr>
+ * <tr valign="top">
+ * <td>
+ * \snippet{lineno} H5I_examples.c create_ud
+ * </td>
+ * <td>
+ * \snippet{lineno} H5I_examples.c read_ud
+ * </td>
+ * <tr><th>Update</th><th>Delete</th></tr>
+ * <tr valign="top">
+ * <td>
+ * \snippet{lineno} H5I_examples.c update_ud
+ * </td>
+ * <td>
+ * \snippet{lineno} H5I_examples.c delete_ud
+ * </td>
+ * </tr>
+ * </table>
+ *
*/
#endif /* H5Imodule_H */
diff --git a/src/H5Ipublic.h b/src/H5Ipublic.h
index 6442a0d..ed7633d 100644
--- a/src/H5Ipublic.h
+++ b/src/H5Ipublic.h
@@ -105,7 +105,7 @@ extern "C" {
/* Public API functions */
/**
- * \ingroup H5I
+ * \ingroup H5IUD
*
* \brief Registers an object under a type and returns an ID for it
*
@@ -127,7 +127,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
*
@@ -150,7 +150,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
*
@@ -189,12 +189,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
@@ -390,7 +385,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
*
@@ -422,7 +417,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
*
@@ -446,7 +441,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
*
@@ -469,7 +464,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
*
@@ -488,7 +483,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
*
@@ -508,7 +503,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
*
@@ -527,7 +522,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
@@ -568,7 +563,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
*
@@ -597,7 +592,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
*
@@ -617,7 +612,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 54b94a4..cffd25c 100644
--- a/src/H5Lmodule.h
+++ b/src/H5Lmodule.h
@@ -30,11 +30,34 @@
#define H5_MY_PKG_INIT YES
/**\defgroup H5L H5L
- * \brief Link Interface
- * \todo Describe concisely what the functions in this module are about.
+ *
+ * Use the functions in this module to manage HDF5 links and link types.
+ *
+ * <table>
+ * <tr><th>Create</th><th>Read</th></tr>
+ * <tr valign="top">
+ * <td>
+ * \snippet{lineno} H5L_examples.c create
+ * </td>
+ * <td>
+ * \snippet{lineno} H5L_examples.c iter_cb
+ * \snippet{lineno} H5L_examples.c read
+ * </td>
+ * <tr><th>Update</th><th>Delete</th></tr>
+ * <tr valign="top">
+ * <td>
+ * \snippet{lineno} H5L_examples.c update
+ * </td>
+ * <td>
+ * \snippet{lineno} H5L_examples.c delete
+ * </td>
+ * </tr>
+ * </table>
*
* \defgroup TRAV Link Traversal
* \ingroup H5L
+ * \defgroup H5LA Advanced Link Functions
+ * \ingroup H5L
*/
#endif /* H5Lmodule_H */
diff --git a/src/H5Lpublic.h b/src/H5Lpublic.h
index f82f263..106eea1 100644
--- a/src/H5Lpublic.h
+++ b/src/H5Lpublic.h
@@ -963,7 +963,7 @@ H5_DLL herr_t H5Literate2(hid_t grp_id, H5_index_t idx_type, H5_iter_order_t ord
* following:
* \orders
*
- * \p idx_p allows an interrupted iteration to be resumed; it is
+ * \p idx allows an interrupted iteration to be resumed; it is
* passed in by the application with a starting point and returned by
* the library with the point at which the iteration stopped.
*
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/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 3c44421..ec9e073 100644
--- a/src/H5Opublic.h
+++ b/src/H5Opublic.h
@@ -35,14 +35,14 @@
/*****************/
/* Flags for object copy (H5Ocopy) */
-#define H5O_COPY_SHALLOW_HIERARCHY_FLAG (0x0001u) /* Copy only immediate members */
-#define H5O_COPY_EXPAND_SOFT_LINK_FLAG (0x0002u) /* Expand soft links into new objects */
-#define H5O_COPY_EXPAND_EXT_LINK_FLAG (0x0004u) /* Expand external links into new objects */
-#define H5O_COPY_EXPAND_REFERENCE_FLAG (0x0008u) /* Copy objects that are pointed by references */
-#define H5O_COPY_WITHOUT_ATTR_FLAG (0x0010u) /* Copy object without copying attributes */
-#define H5O_COPY_PRESERVE_NULL_FLAG (0x0020u) /* Copy NULL messages (empty space) */
-#define H5O_COPY_MERGE_COMMITTED_DTYPE_FLAG (0x0040u) /* Merge committed datatypes in dest file */
-#define H5O_COPY_ALL (0x007Fu) /* All object copying flags (for internal checking) */
+#define H5O_COPY_SHALLOW_HIERARCHY_FLAG (0x0001u) /**< Copy only immediate members */
+#define H5O_COPY_EXPAND_SOFT_LINK_FLAG (0x0002u) /**< Expand soft links into new objects */
+#define H5O_COPY_EXPAND_EXT_LINK_FLAG (0x0004u) /**< Expand external links into new objects */
+#define H5O_COPY_EXPAND_REFERENCE_FLAG (0x0008u) /**< Copy objects that are pointed by references */
+#define H5O_COPY_WITHOUT_ATTR_FLAG (0x0010u) /**< Copy object without copying attributes */
+#define H5O_COPY_PRESERVE_NULL_FLAG (0x0020u) /**< Copy NULL messages (empty space) */
+#define H5O_COPY_MERGE_COMMITTED_DTYPE_FLAG (0x0040u) /**< Merge committed datatypes in dest file */
+#define H5O_COPY_ALL (0x007Fu) /**< All object copying flags (for internal checking) */
/* Flags for shared message indexes.
* Pass these flags in using the mesg_type_flags parameter in
@@ -51,25 +51,27 @@
* but we need to assign each kind of message to a different bit so that
* one index can hold multiple types.)
*/
-#define H5O_SHMESG_NONE_FLAG 0x0000 /* No shared messages */
-#define H5O_SHMESG_SDSPACE_FLAG ((unsigned)1 << 0x0001) /* Simple Dataspace Message. */
-#define H5O_SHMESG_DTYPE_FLAG ((unsigned)1 << 0x0003) /* Datatype Message. */
-#define H5O_SHMESG_FILL_FLAG ((unsigned)1 << 0x0005) /* Fill Value Message. */
-#define H5O_SHMESG_PLINE_FLAG ((unsigned)1 << 0x000b) /* Filter pipeline message. */
-#define H5O_SHMESG_ATTR_FLAG ((unsigned)1 << 0x000c) /* Attribute Message. */
+#define H5O_SHMESG_NONE_FLAG 0x0000 /**< No shared messages */
+#define H5O_SHMESG_SDSPACE_FLAG ((unsigned)1 << 0x0001) /**< Simple Dataspace Message. */
+#define H5O_SHMESG_DTYPE_FLAG ((unsigned)1 << 0x0003) /**< Datatype Message. */
+#define H5O_SHMESG_FILL_FLAG ((unsigned)1 << 0x0005) /**< Fill Value Message. */
+#define H5O_SHMESG_PLINE_FLAG ((unsigned)1 << 0x000b) /**< Filter pipeline message. */
+#define H5O_SHMESG_ATTR_FLAG ((unsigned)1 << 0x000c) /**< Attribute Message. */
#define H5O_SHMESG_ALL_FLAG \
(H5O_SHMESG_SDSPACE_FLAG | H5O_SHMESG_DTYPE_FLAG | H5O_SHMESG_FILL_FLAG | H5O_SHMESG_PLINE_FLAG | \
H5O_SHMESG_ATTR_FLAG)
+/* clang-format off */
/* Object header status flag definitions */
-#define H5O_HDR_CHUNK0_SIZE 0x03 /* 2-bit field indicating # of bytes to store the size of chunk 0's data */
-#define H5O_HDR_ATTR_CRT_ORDER_TRACKED 0x04 /* Attribute creation order is tracked */
-#define H5O_HDR_ATTR_CRT_ORDER_INDEXED 0x08 /* Attribute creation order has index */
-#define H5O_HDR_ATTR_STORE_PHASE_CHANGE 0x10 /* Non-default attribute storage phase change values stored */
-#define H5O_HDR_STORE_TIMES 0x20 /* Store access, modification, change & birth times for object */
+#define H5O_HDR_CHUNK0_SIZE 0x03 /**< 2-bit field indicating # of bytes to store the size of chunk 0's data */
+#define H5O_HDR_ATTR_CRT_ORDER_TRACKED 0x04 /**< Attribute creation order is tracked */
+#define H5O_HDR_ATTR_CRT_ORDER_INDEXED 0x08 /**< Attribute creation order has index */
+#define H5O_HDR_ATTR_STORE_PHASE_CHANGE 0x10 /**< Non-default attribute storage phase change values stored */
+#define H5O_HDR_STORE_TIMES 0x20 /**< Store access, modification, change & birth times for object */
#define H5O_HDR_ALL_FLAGS \
(H5O_HDR_CHUNK0_SIZE | H5O_HDR_ATTR_CRT_ORDER_TRACKED | H5O_HDR_ATTR_CRT_ORDER_INDEXED | \
H5O_HDR_ATTR_STORE_PHASE_CHANGE | H5O_HDR_STORE_TIMES)
+/* clang-format on */
/* Maximum shared message values. Number of indexes is 8 to allow room to add
* new types of messages.
@@ -81,9 +83,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 +93,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 +148,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 +167,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 +182,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] -->
@@ -445,28 +457,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.
@@ -515,29 +506,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:
@@ -585,34 +553,6 @@ H5_DLL herr_t H5Oget_info_by_name3(hid_t loc_id, const char *name, H5O_info2_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_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:
@@ -645,11 +585,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:
@@ -680,12 +616,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:
@@ -724,16 +657,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:
@@ -1205,11 +1129,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
@@ -1219,62 +1140,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
@@ -1298,24 +1164,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
@@ -1380,10 +1228,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
@@ -1394,49 +1239,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
@@ -1464,24 +1267,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
@@ -1541,32 +1326,16 @@ H5_DLL herr_t H5Oclose(hid_t object_id);
* files. After that, the OS is responsible for ensuring that
* the data is actually flushed to disk.
*
- * \par See Also:
- * - H5Dflush()
- * - H5Drefresh()
- * - H5Oflush()
- * - H5Grefresh()
- * - H5Oflush()
- * - H5Orefresh()
- * - H5Tflush()
- * - H5Trefresh()
- * \par
- * - \c H5DOappend()
- * - H5Fstart_swmr_write()
- * - H5Pget_append_flush()
- * - H5Pget_object_flush_cb()
- * - H5Pset_append_flush()
- * - H5Pset_object_flush_cb()
- * \par
- * - H5Oare_mdc_flushes_disabled()
- * - H5Odisable_mdc_flushes()
- * - H5Oenable_mdc_flushes()
+ * \see H5Dflush(), H5Drefresh(), H5Oflush(), H5Grefresh(), H5Oflush(),
+ * H5Orefresh(), H5Tflush(), H5Trefresh()
+ * \see H5DOappend(), H5Fstart_swmr_write(), H5Pget_append_flush(),
+ * H5Pget_object_flush_cb(), H5Pset_append_flush(), H5Pset_object_flush_cb()
+ * \see H5Oare_mdc_flushes_disabled(), H5Odisable_mdc_flushes(), H5Oenable_mdc_flushes()
*
* \since 1.10.0
*
*/
H5_DLL herr_t H5Oflush(hid_t obj_id);
-
/**
*-------------------------------------------------------------------------
* \ingroup H5O
@@ -1619,21 +1388,17 @@ H5_DLL herr_t H5Orefresh(hid_t oid);
* HDF5 object level (datasets, groups, committed datatypes)
* and the entire metadata cache level.
*
- * \note HDF5 objects include datasets, groups, and committed datatypes.
- * Only #hid_t identifiers that represent these objects can be passed to the function.
- * \note Passing in a #hid_t identifier that represents any other HDF5 entity is
- * considered an error.
- * \note It is an error to pass an HDF5 file identifier
- * (obtained from H5Fopen() or H5Fcreate())
- * to this function.
- * \note Misuse of this function can cause the cache to exhaust
- * available memory.
- * \note Objects can be returned to the default automatic flush behavior
- * with H5Oenable_mdc_flushes().
- * \note Flush prevention only pertains to new or dirty metadata entries.
- * Clean entries can be evicted from the cache.
- * \note Calling this function on an object that has already had flushes
- * disabled will return an error.
+ * \note HDF5 objects include datasets, groups, and committed datatypes. Only
+ * #hid_t identifiers that represent these objects can be passed to the
+ * function. Passing in a #hid_t identifier that represents any other
+ * HDF5 entity is considered an error. It is an error to pass an HDF5
+ * file identifier (obtained from H5Fopen() or H5Fcreate()) to this
+ * function. Misuse of this function can cause the cache to exhaust
+ * available memory. Objects can be returned to the default automatic
+ * flush behavior with H5Oenable_mdc_flushes(). Flush prevention only
+ * pertains to new or dirty metadata entries. Clean entries can be
+ * evicted from the cache. Calling this function on an object that has
+ * already had flushes disabled will return an error.
*
* \since 1.10.0
*
@@ -1663,28 +1428,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
*
@@ -1833,8 +1588,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)
@@ -1867,7 +1622,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 {
@@ -1880,6 +1635,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] -->
@@ -1952,36 +1717,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,
@@ -2081,16 +1817,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.
*
@@ -2199,7 +1925,7 @@ H5_DLL herr_t H5Oget_info_by_name2(hid_t loc_id, const char *name, H5O_info1_t *
* \param[in] group_name Name of group in which object is located
* \idx_type
* \order
- * \param[in] n Position within the index
+ * \param[in] n Position within the index
* \param[out] oinfo Buffer in which to return object information
* \param[in] fields Flags specifying the fields to include in \p oinfo
* \lapl_id
@@ -2286,10 +2012,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
@@ -2300,56 +2023,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
@@ -2363,24 +2037,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(),
@@ -2448,10 +2104,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
@@ -2462,10 +2115,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
@@ -2495,24 +2145,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(),
@@ -2575,10 +2207,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
@@ -2589,57 +2218,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
@@ -2658,23 +2237,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
*
@@ -2739,10 +2301,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
@@ -2753,10 +2312,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
@@ -2791,24 +2347,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 3d6968e..ee1ba04 100644
--- a/src/H5Ppublic.h
+++ b/src/H5Ppublic.h
@@ -22,16 +22,17 @@
/* Public headers needed by this file */
#include "H5public.h"
-#include "H5ACpublic.h"
-#include "H5Dpublic.h"
-#include "H5Fpublic.h"
-#include "H5FDpublic.h"
-#include "H5Ipublic.h"
-#include "H5Lpublic.h"
-#include "H5Opublic.h"
-#include "H5MMpublic.h"
-#include "H5Tpublic.h"
-#include "H5Zpublic.h"
+#include "H5ACpublic.h" /* Metadata cache */
+#include "H5Dpublic.h" /* Datasets */
+#include "H5Fpublic.h" /* Files */
+#include "H5FDpublic.h" /* File drivers */
+#include "H5Ipublic.h" /* ID management */
+#include "H5Lpublic.h" /* Links */
+#include "H5MMpublic.h" /* Memory management */
+#include "H5Opublic.h" /* Object headers */
+#include "H5Spublic.h" /* Dataspaces */
+#include "H5Tpublic.h" /* Datatypes */
+#include "H5Zpublic.h" /* Data filters */
/*****************/
/* Public Macros */
@@ -99,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
@@ -112,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] -->
@@ -158,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] -->
@@ -171,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] -->
@@ -2210,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
*
@@ -2219,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.
@@ -3699,7 +3729,7 @@ H5_DLL herr_t H5Pget_libver_bounds(hid_t plist_id, H5F_libver_t *low, H5F_libver
* \since 1.8.0
*
*/
-H5_DLL herr_t H5Pget_mdc_config(hid_t plist_id, H5AC_cache_config_t *config_ptr); /* out */
+H5_DLL herr_t H5Pget_mdc_config(hid_t plist_id, H5AC_cache_config_t *config_ptr);
/**
* \ingroup FAPL
*
@@ -5208,7 +5238,7 @@ H5_DLL herr_t H5Pset_vol(hid_t plist_id, hid_t new_vol_id, const void *new_vol_i
#ifdef H5_HAVE_PARALLEL
/**
- * \ingroup GACPL
+ * \ingroup GAPL
*
* \brief Sets metadata I/O mode for read operations to collective or independent (default)
*
@@ -5277,7 +5307,7 @@ H5_DLL herr_t H5Pset_vol(hid_t plist_id, hid_t new_vol_id, const void *new_vol_i
*/
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
*
@@ -6237,6 +6267,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.
@@ -6308,6 +6340,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.
*
@@ -6401,6 +6435,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.
*
@@ -6510,6 +6546,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.
@@ -9388,9 +9426,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 */
@@ -9504,8 +9539,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 e26a72c..f8950e9 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)
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 331e5ee..80e45e2 100644
--- a/src/H5Spublic.h
+++ b/src/H5Spublic.h
@@ -21,99 +21,103 @@
#include "H5public.h"
#include "H5Ipublic.h"
-/* Define atomic datatypes */
+/* Define special dataspaces for dataset I/O operations */
#define H5S_ALL (hid_t)0
-#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
@@ -1314,9 +1318,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
@@ -1325,10 +1326,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 78c5986..8fcb961 100644
--- a/src/H5VLmodule.h
+++ b/src/H5VLmodule.h
@@ -27,10 +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
*
* \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..f7d3cd6 100644
--- a/src/H5module.h
+++ b/src/H5module.h
@@ -11,9 +11,9 @@
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
/*
- * Purpose: This file contains declarations which define macros for the
- * H5 package. Including this header means that the source file
- * is part of the H5 package.
+ * Purpose: This file contains declarations which define macros for the
+ * H5 package. Including this header means that the source file
+ * is part of the H5 package.
*/
#ifndef H5module_H
#define H5module_H
@@ -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 9ff8252..c0541b1 100644
--- a/src/H5public.h
+++ b/src/H5public.h
@@ -197,8 +197,9 @@ extern "C" {
* Status return values. Failed integer functions in HDF5 result almost
* always in a negative value (unsigned failing functions sometimes return
* zero for failure) while successful return is non-negative (often zero).
- * The negative failure value is most commonly -1, but don't bet on it. The
- * proper way to detect failure is something like:
+ * The negative failure value is most commonly -1, but don't bet on it.
+ *
+ * The proper way to detect failure is something like:
* \code
* if((dset = H5Dopen2(file, name)) < 0)
* fprintf(stderr, "unable to open the requested dataset\n");
@@ -419,9 +420,9 @@ typedef enum {
/* (Actually, any positive value will cause the iterator to stop and pass back
* that positive value to the function that called the iterator)
*/
-#define H5_ITER_ERROR (-1)
-#define H5_ITER_CONT (0)
-#define H5_ITER_STOP (1)
+#define H5_ITER_ERROR (-1) /**< Error, stop iteration */
+#define H5_ITER_CONT (0) /**< Continue iteration */
+#define H5_ITER_STOP (1) /**< Stop iteration, short-circuit success */
//! <!-- [H5_index_t_snip] -->
/**
generated by cgit v0.12 at 2024-07-16 15:49:16 (GMT)