diff --git a/doxygen/hdf5doxy_layout.xml b/doxygen/hdf5doxy_layout.xml
index 7f71c24..fc20aa1 100644
--- a/doxygen/hdf5doxy_layout.xml
+++ b/doxygen/hdf5doxy_layout.xml
@@ -11,6 +11,7 @@
+
diff --git a/src/CMakeLists.txt b/src/CMakeLists.txt
index fbde308..aaff5e4 100644
--- a/src/CMakeLists.txt
+++ b/src/CMakeLists.txt
@@ -1325,15 +1325,17 @@ if (DOXYGEN_FOUND)
set (DOXYGEN_OPTIMIZE_OUTPUT_FOR_C YES)
set (DOXYGEN_MACRO_EXPANSION YES)
set (DOXYGEN_OUTPUT_DIRECTORY ${HDF5_BINARY_DIR}/hdf5lib_docs)
- set (DOXYGEN_EXAMPLES_DIRECTORY "${HDF5_DOXYGEN_DIR}/examples ${HDF5_SRC_DIR} ${HDF5_SOURCE_DIR}/examples ${HDF5_TEST_SRC_DIR}")
+ set (DOXYGEN_EXAMPLES_DIRECTORY "${HDF5_DOXYGEN_DIR}/dox/cookbook ${HDF5_DOXYGEN_DIR}/examples ${HDF5_SRC_DIR} ${HDF5_SOURCE_DIR}/examples ${HDF5_TEST_SRC_DIR}")
set (DOXYGEN_LAYOUT_FILE ${HDF5_DOXYGEN_DIR}/hdf5doxy_layout.xml)
set (DOXYGEN_HTML_HEADER ${HDF5_DOXYGEN_DIR}/hdf5_header.html)
set (DOXYGEN_HTML_FOOTER ${HDF5_DOXYGEN_DIR}/hdf5_footer.html)
set (DOXYGEN_HTML_EXTRA_STYLESHEET ${HDF5_DOXYGEN_DIR}/hdf5doxy.css)
set (DOXYGEN_HTML_EXTRA_FILES "${HDF5_DOXYGEN_DIR}/hdf5_navtree_hacks.js ${HDF5_DOXYGEN_DIR}/img/ftv2node.png ${HDF5_DOXYGEN_DIR}/img/ftv2pnode.png")
+ set (DOXYGEN_TAG_FILE ${HDF5_BINARY_DIR}/hdf5.tag)
set (DOXYGEN_SERVER_BASED_SEARCH NO)
set (DOXYGEN_EXTERNAL_SEARCH NO)
set (DOXYGEN_SEARCHENGINE_URL)
+ set (DOXYGEN_PREDEFINED H5_HAVE_DIRECT H5_HAVE_LIBHDFS H5_HAVE_MAP_API H5_HAVE_PARALLEL H5_HAVE_ROS3_VFD)
# This configure and custom target work together
# Replace variables inside @@ with the current values
diff --git a/src/H5Amodule.h b/src/H5Amodule.h
index c89c93f..9f86ddd 100644
--- a/src/H5Amodule.h
+++ b/src/H5Amodule.h
@@ -33,33 +33,29 @@
*
* Use the functions in this module to manage HDF5 attributes.
*
- * The Attribute Interface, H5A, provides a mechanism for attaching additional
- * information to a dataset, group, or named datatype.
- *
- * Attributes are accessed by opening the object that they are attached to and
- * are not independent objects. Typically an attribute is small in size and
- * contains user metadata about the object that it is attached to.
- *
- * Attributes look similar to HDF5 datasets in that they have a datatype and
- * dataspace. However, they do not support partial I/O operations and cannot be
- * compressed or extended.
+ * Like HDF5 datasets, HDF5 attributes are array variables which have an element
+ * datatype and a shape (dataspace). However, they perform a different function:
+ * Attributes decorate other HDF5 objects, and are typically used to
+ * represent application metadata. Unlike datasets, the HDF5 library does not
+ * support partial I/O operations for attributes and they cannot be compressed
+ * or extended.
*
*
* | Create | Read |
|---|
*
* |
- * \snippet H5A_examples.c create
+ * \snippet{lineno} H5A_examples.c create
* |
*
- * \snippet H5A_examples.c read
+ * \snippet{lineno} H5A_examples.c read
* |
*
| Update | Delete |
|---|
*
* |
- * \snippet H5A_examples.c update
+ * \snippet{lineno} H5A_examples.c update
* |
*
- * \snippet H5A_examples.c delete
+ * \snippet{lineno} H5A_examples.c delete
* |
*
*
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 @@
*
| Create | Read |
|---|
*
* |
- * \snippet H5D_examples.c create
+ * \snippet{lineno} H5D_examples.c create
* |
*
- * \snippet H5D_examples.c read
+ * \snippet{lineno} H5D_examples.c read
* |
*
| Update | Delete |
|---|
*
* |
- * \snippet H5D_examples.c update
+ * \snippet{lineno} H5D_examples.c update
* |
*
- * \snippet H5D_examples.c delete
+ * \snippet{lineno} H5D_examples.c delete
* |
*
*
diff --git a/src/H5Dpublic.h b/src/H5Dpublic.h
index b708422..a4de5b2 100644
--- a/src/H5Dpublic.h
+++ b/src/H5Dpublic.h
@@ -32,7 +32,9 @@
#define H5D_CHUNK_CACHE_NBYTES_DEFAULT ((size_t)-1)
#define H5D_CHUNK_CACHE_W0_DEFAULT (-1.0)
-/* Bit flags for the H5Pset_chunk_opts() and H5Pget_chunk_opts() */
+/**
+ * Bit flags for the H5Pset_chunk_opts() and H5Pget_chunk_opts()
+ */
#define H5D_CHUNK_DONT_FILTER_PARTIAL_CHUNKS (0x0002u)
/*******************/
@@ -44,13 +46,12 @@
* Values for the H5D_LAYOUT property
*/
typedef enum H5D_layout_t {
- H5D_LAYOUT_ERROR = -1,
-
- H5D_COMPACT = 0, /**< raw data is very small */
- H5D_CONTIGUOUS = 1, /**< the default */
- H5D_CHUNKED = 2, /**< slow and fancy */
- H5D_VIRTUAL = 3, /**< actual data is stored in other datasets */
- H5D_NLAYOUTS = 4 /**< this one must be last! */
+ H5D_LAYOUT_ERROR = -1, /**< error */
+ H5D_COMPACT = 0, /**< raw data is small (< 64KB) */
+ H5D_CONTIGUOUS = 1, /**< contiguous layout */
+ H5D_CHUNKED = 2, /**< chunked or tiled layout */
+ H5D_VIRTUAL = 3, /**< actual data is stored in other datasets */
+ H5D_NLAYOUTS = 4 /**< this one must be last! */
} H5D_layout_t;
//!
@@ -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;
//!
@@ -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;
//!
@@ -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;
//!
@@ -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;
//!
@@ -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;
//!
//!
/**
- * 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);
//!
//!
/**
- * 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
//!
/**
- * 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
//!
/**
- * 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);
//!
@@ -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);
*
*
*
- * \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:
- *
- *
- * | \c elem |
- * [in,out] |
- * Pointer to the memory buffer containing the current
- * data element |
- * | \c type_id |
- * [in] |
- * Datatype identifier of the elements stored in elem |
- * | \c ndim |
- * [in] |
- * Number of dimensions for the point array |
- * | \c point |
- * [in] |
- * Array containing the location of the element within
- * the original dataspace |
- * | \c operator_data |
- * [in,out] |
- * Pointer to any user-defined data associated with the
- * operation |
- *
- *
- * The possible return values from the callback function, and
- * the effect ofeach,are as follows:
- *
- * \li Zero causes the iterator to continue, returning zero
- * when all data elements have been processed.
- * \li A positive value causes the iterator to immediately
- * return that positive value, indicating short-circuit success.
- * \li A negative value causes the iterator to immediately return
- * that value, indicating failure.
- *
- * The \p operator_data parameter is a user-defined pointer to
- * the data required to process dataset elements in the course
- * of the iteration. If operator needs to pass data back to the
- * application, such data can be returned in this same buffer. This
- * pointer is passed back to each step of the iteration in the
- * operator callback function’s operator_data parameter.
- *
- * Unlike other HDF5 iterators, this iteration operation cannot
- * be restarted at the point of exit; a second H5Diterate()
- * call will always restart at the beginning.
+ * \attention Unlike other HDF5 iterators, this iteration operation cannot
+ * be restarted at the point of exit; a second H5Diterate()
+ * call will always restart at the beginning.
*
*
* \since 1.10.2
@@ -1154,30 +1119,25 @@ H5_DLL herr_t H5Dvlen_get_buf_size(hid_t dset_id, hid_t type_id, hid_t space_id,
*
* \return \herr_t
*
- * \details H5Dfill() fills the dataspace selection in memory, \p space_id,
+ * \details H5Dfill() fills the dataspace selection, \p space_id, in memory
* with the fill value specified in \p fill. If \p fill is NULL,
* a fill value of 0 (zero) is used.
*
* \p fill_type_id specifies the datatype of the fill value.
- * \p buf specifies the buffer in which the dataspace elements
- * will be written.
- * \p buf_type_id specifies the datatype of those data elements.
+ * \p buf specifies the buffer in which the fill elements
+ * will be written. \p buf_type_id specifies the datatype of
+ * those data elements.
*
* \note Note that if the fill value datatype differs from the memory
- * buffer datatype, the fill value will be converted to the memory
- * buffer datatype before filling the selection.
+ * buffer datatype, the fill value will be converted to the memory
+ * buffer datatype before filling the selection.
*
* \note Applications sometimes write data only to portions of an
- * allocated dataset. It is often useful in such cases to fill
- * the unused space with a known fill value. See the following
- * function for more information:
- * - H5Pset_fill_value()
- * - H5Pget_fill_value()
- * - H5Pfill_value_defined()
- * - H5Pset_fill_time()
- * - H5Pget_fill_time()
- * - H5Pcreate()
- * - H5Pcreate_anon()
+ * allocated dataset. It is often useful in such cases to fill
+ * the unused space with a known fill value.
+ *
+ * \see H5Pset_fill_value(), H5Pget_fill_value(), H5Pfill_value_defined(),
+ * H5Pset_fill_time(), H5Pget_fill_time(), H5Pcreate(), H5Dcreate_anon()
*
*/
H5_DLL herr_t H5Dfill(const void *fill, hid_t fill_type_id, void *buf, hid_t buf_type_id, hid_t space_id);
@@ -1224,22 +1184,21 @@ H5_DLL herr_t H5Dfill(const void *fill, hid_t fill_type_id, void *buf, hid_t buf
* - If the dataset’s fill time is set to #H5D_FILL_TIME_ALLOC
* (see H5Pset_alloc_time())
*
- * \note
- * \li If the sizes specified in \p size array are smaller than
- * the dataset’s current dimension sizes, H5Dset_extent() will reduce
- * the dataset’s dimension sizes to the specified values. It is the
- * user application’s responsibility to ensure that valuable data is
- * not lost as H5Dset_extent() does not check.
+ * \note If the sizes specified in \p size array are smaller than the dataset’s
+ * current dimension sizes, H5Dset_extent() will reduce the dataset’s
+ * dimension sizes to the specified values. It is the user application’s
+ * responsibility to ensure that valuable data is not lost as
+ * H5Dset_extent() does not check.
*
- * \li Except for external datasets, H5Dset_extent() is for use with
- * chunked datasets only, not contiguous datasets.
+ * \note Except for external datasets, H5Dset_extent() is for use with
+ * chunked datasets only, not contiguous datasets.
*
- * \li A call to H5Dset_extent() affects the dataspace of a dataset.
- * If a dataspace handle was opened for a dataset prior to a call to
- * H5Dset_extent() then that dataspace handle will no longer reflect
- * the correct dataspace extent of the dataset. H5Dget_space() must
- * be called (after closing the previous handle) to obtain the current
- * dataspace extent.
+ * \note A call to H5Dset_extent() affects the dataspace of a dataset. If a
+ * dataspace handle was opened for a dataset prior to a call to
+ * H5Dset_extent() then that dataspace handle will no longer reflect the
+ * correct dataspace extent of the dataset. H5Dget_space() must be called
+ * (after closing the previous handle) to obtain the current dataspace
+ * extent.
*
* \since 1.8.0
*
@@ -1266,6 +1225,8 @@ H5_DLL herr_t H5Dset_extent(hid_t dset_id, const hsize_t size[]);
* open files. After that, the OS is responsible for ensuring
* that the data is actually flushed to disk.
*
+ * \since 1.10.0
+ *
*/
H5_DLL herr_t H5Dflush(hid_t dset_id);
@@ -1324,40 +1285,7 @@ H5_DLL herr_t H5Drefresh(hid_t dset_id);
*
* To retrieve the data to be scattered, H5Dscatter() repeatedly
* calls \p op, which should return a valid source buffer, until
- * enough data to fill the selection has been retrieved. The
- * prototype of the callback function \p op is as follows (as
- * defined in the source code file H5Dpublic.h):
- * \snippet this H5D_scatter_func_t_snip
- * The parameters of this callback function are described below:
- *
- *
- * | \c src_buf |
- * [out] |
- * 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. |
- * | \c src_buf_bytes_used |
- * [out] |
- * 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.
- * |
- * | \c op_data |
- * [in,out] |
- * 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. |
- *
- *
- * The callback function should always return at least one
- * element in \p src_buf, and must not return more elements
- * than are remaining to be scattered. This function will be
- * repeatedly called until all elements to be scattered have
- * been returned. The callback function should return zero (0)
- * to indicate success, and a negative value to indicate failure.
+ * enough data to fill the selection has been retrieved.
*
* \since 1.10.2
*
@@ -1409,27 +1337,9 @@ H5_DLL herr_t H5Dscatter(H5D_scatter_func_t op, void *op_data, hid_t type_id, hi
* If no callback function is provided, H5Dgather() simply gathers
* the data into \p dst_buf and returns. If a callback function is
* provided, H5Dgather() repeatedly gathers up to \p dst_buf_size
- * bytes to process the serialized data. The prototype of the
- * callback function \p op is as follows (as defined in the source
- * code file H5Dpublic.h):
- * \snippet this H5D_gather_func_t_snip
- * The parameters of this callback function are described in the
- * table below.
- *
- * | \c 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(). |
- * | \c 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. |
- * | \c 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. |
- *
- * The callback function should process, store, or otherwise,
+ * bytes to process the serialized data.
+ *
+ * The callback function \p op should process, store, or otherwise,
* make use of the data returned in \p dst_buf before it returns,
* because the buffer will be overwritten unless it is the last
* call to the callback. This function will be repeatedly called
@@ -1453,11 +1363,11 @@ H5_DLL herr_t H5Dgather(hid_t src_space_id, const void *src_buf, hid_t type_id,
*
* \return \herr_t
*
- * \details H5Dclose() ends access to a dataset specified by \p dset_id
- * and releases resources used by it.
+ * \details H5Dclose() terminates access to a dataset via the identifier
+ * \p dset_id and releases the underlying resources.
*
- * \attention Further use of a released dataset identifier is illegal; a
- * function using such an identifier will generate an error.
+ * \par Example
+ * \snippet H5D_examples.c read
*
* \since 1.8.0
*
@@ -1510,8 +1420,7 @@ H5_DLL herr_t H5Dget_chunk_index_type(hid_t did, H5D_chunk_index_t *idx_type);
*
* \return \hid_t{dataset}
*
- * \deprecated This function is deprecated in favor of the function H5Dcreate2()
- * or the macro H5Dcreate().
+ * \deprecation_note{H5Dcreate2() or the macro H5Dcreate()}
*
* \details H5Dcreate1() creates a data set with a name, \p name, in the
* location specified by the identifier \p loc_id. \p loc_id may be a
@@ -1577,8 +1486,7 @@ H5_DLL hid_t H5Dcreate1(hid_t loc_id, const char *name, hid_t type_id, hid_t spa
*
* \return \hid_t{dataset}
*
- * \deprecated This function is deprecated in favor of the function H5Dopen2()
- * or the macro H5Dopen().
+ * \deprecation_note{H5Dopen2() or the macro H5Dopen()}
*
* \details H5Dopen1() opens an existing dataset for access at the location
* specified by \p loc_id. \p loc_id may be a file, group, dataset,
@@ -1608,10 +1516,10 @@ H5_DLL hid_t H5Dopen1(hid_t loc_id, const char *name);
*
* \return \herr_t
*
- * \deprecated This function is deprecated in favor of the function H5Dset_extent().
+ * \deprecation_note{H5Dset_extent()}
*
* \details H5Dextend() verifies that the dataset is at least of size \p size,
- * extending it if necessary. The dimensionality of size is the same as
+ * extending it if necessary. The length of \p size is the same as
* that of the dataspace of the dataset being changed.
*
* This function can be applied to the following datasets:
@@ -1631,7 +1539,7 @@ H5_DLL hid_t H5Dopen1(hid_t loc_id, const char *name);
* the sizes specified in size. The function H5Dset_extent() must be
* used if the dataset dimension sizes are are to be reduced.
*
- * \version 1.8.0 Function Function deprecated in this release. Parameter size
+ * \version 1.8.0 Function deprecated in this release. Parameter size
* syntax changed to \Code{const hsize_t size[]} in this release.
*
*/
diff --git a/src/H5Emodule.h b/src/H5Emodule.h
index 1670c03..58a3517 100644
--- a/src/H5Emodule.h
+++ b/src/H5Emodule.h
@@ -29,4 +29,54 @@
#define H5_MY_PKG_ERR H5E_ERROR
#define H5_MY_PKG_INIT YES
+/**\defgroup H5E H5E
+ *
+ * Use the functions in this module to manage HDF5 error stacks and error
+ * messages.
+ *
+ *
+ * | Create | Read |
|---|
+ *
+ * |
+ * \snippet{lineno} H5E_examples.c create
+ * |
+ *
+ * \snippet{lineno} H5E_examples.c read
+ * |
+ *
| Update | Delete |
|---|
+ *
+ * |
+ * \snippet{lineno} H5E_examples.c update
+ * |
+ *
+ * \snippet{lineno} H5E_examples.c delete
+ * |
+ *
+ *
+ *
+ * \internal The \c FUNC_ENTER macro clears the error stack whenever an
+ * interface function is entered. When an error is detected, an entry
+ * is pushed onto the stack. As the functions unwind, additional
+ * entries are pushed onto the stack. The API function will return
+ * some indication that an error occurred and the application can
+ * print the error stack.
+ *
+ * \internal Certain API functions in the \ref H5E package, such as H5Eprint(),
+ * do not clear the error stack. Otherwise, any function which does
+ * not have an underscore immediately after the package name will
+ * clear the error stack. For instance, H5Fopen() clears the error
+ * stack while \Code{H5F_open} does not.
+ *
+ * \internal An error stack has a fixed maximum size. If this size is exceeded
+ * then the stack will be truncated and only the inner-most functions
+ * will have entries on the stack. This is expected to be a rare
+ * condition.
+ *
+ * \internal Each thread has its own error stack, but since multi-threading has
+ * not been added to the library yet, this package maintains a single
+ * error stack. The error stack is statically allocated to reduce the
+ * complexity of handling errors within the \ref H5E package.
+ *
+ */
+
#endif /* H5Emodule_H */
diff --git a/src/H5Epublic.h b/src/H5Epublic.h
index 1c7055a..43eb4fc 100644
--- a/src/H5Epublic.h
+++ b/src/H5Epublic.h
@@ -38,9 +38,9 @@ typedef struct H5E_error2_t {
hid_t cls_id;
/**< Class ID */
hid_t maj_num;
- /**< Major error ID */
+ /**< Major error ID */
hid_t min_num;
- /**< Minor error number */
+ /**< Minor error number */
unsigned line;
/**< Line in file where error occurs */
const char *func_name;
@@ -696,12 +696,13 @@ typedef herr_t (*H5E_auto1_t)(void *client_data);
*
* \return \herr_t
*
+ * \deprecated 1.8.0 Function H5Eclear() renamed to H5Eclear1() and deprecated
+ * in this release.
+ *
* \details H5Eclear1() clears the error stack for the current thread.\n
* The stack is also cleared whenever an API function is called, with
* certain exceptions (for instance, H5Eprint1()).
*
- * \deprecated 1.8.0 Function H5Eclear() renamed to H5Eclear1() and deprecated
- * in this release.
*/
H5_DLL herr_t H5Eclear1(void);
/**
@@ -717,6 +718,9 @@ H5_DLL herr_t H5Eclear1(void);
* function
* \return \herr_t
*
+ * \deprecated 1.8.0 Function H5Eget_auto() renamed to H5Eget_auto1() and
+ * deprecated in this release.
+ *
* \details H5Eget_auto1() returns the current settings for the automatic error
* stack traversal function, \p func, and its data,
* \p client_data. Either or both arguments may be \c NULL, in which case the
@@ -743,8 +747,6 @@ H5_DLL herr_t H5Eclear1(void);
* H5Eprint2(), mixing H5Eset_auto1() and H5Eget_auto2() or mixing
* H5Eset_auto2() and H5Eget_auto1() does not fail.
*
- * \deprecated 1.8.0 Function H5Eget_auto() renamed to H5Eget_auto1() and
- * deprecated in this release.
*/
H5_DLL herr_t H5Eget_auto1(H5E_auto1_t *func, void **client_data);
/**
@@ -761,6 +763,9 @@ H5_DLL herr_t H5Eget_auto1(H5E_auto1_t *func, void **client_data);
* \param[in] str Error description string
* \return \herr_t
*
+ * \deprecated 1.8.0 Function H5Epush() renamed to H5Epush1() and
+ * deprecated in this release.
+ *
* \details H5Epush1() pushes a new error record onto the error stack for the
* current thread.\n
* The error has major and minor numbers \p maj_num
@@ -771,8 +776,6 @@ H5_DLL herr_t H5Eget_auto1(H5E_auto1_t *func, void **client_data);
* allocated.
*
* \since 1.4.0
- * \deprecated 1.8.0 Function H5Epush() renamed to H5Epush1() and
- * deprecated in this release.
*/
H5_DLL herr_t H5Epush1(const char *file, const char *func, unsigned line, H5E_major_t maj, H5E_minor_t min,
const char *str);
@@ -785,6 +788,9 @@ H5_DLL herr_t H5Epush1(const char *file, const char *func, unsigned line, H5E_ma
* \param[in] stream File pointer, or \c NULL for \c stderr
* \return \herr_t
*
+ * \deprecated 1.8.0 Function H5Eprint() renamed to H5Eprint1() and
+ * deprecated in this release.
+ *
* \details H5Eprint1() prints prints the error stack for the current thread
* on the specified stream, \p stream. Even if the error stack is empty, a
* one-line message of the following form will be printed:
@@ -795,8 +801,6 @@ H5_DLL herr_t H5Epush1(const char *file, const char *func, unsigned line, H5E_ma
* that prints error messages. Users are encouraged to write their own
* more specific error handlers.
*
- * \deprecated 1.8.0 Function H5Eprint() renamed to H5Eprint1() and
- * deprecated in this release.
*/
H5_DLL herr_t H5Eprint1(FILE *stream);
/**
@@ -809,6 +813,9 @@ H5_DLL herr_t H5Eprint1(FILE *stream);
* \param[in] client_data Data passed to the error function
* \return \herr_t
*
+ * \deprecated 1.8.0 Function H5Eset_auto() renamed to H5Eset_auto1() and
+ * deprecated in this release.
+ *
* \details H5Eset_auto1() turns on or off automatic printing of errors. When
* turned on (non-null \p func pointer), any API function which returns
* an error indication will first call \p func, passing it \p
@@ -825,8 +832,6 @@ H5_DLL herr_t H5Eprint1(FILE *stream);
* Automatic stack traversal is always in the #H5E_WALK_DOWNWARD
* direction.
*
- * \deprecated 1.8.0 Function H5Eset_auto() renamed to H5Eset_auto1() and
- * deprecated in this release.
*/
H5_DLL herr_t H5Eset_auto1(H5E_auto1_t func, void *client_data);
/**
@@ -840,6 +845,9 @@ H5_DLL herr_t H5Eset_auto1(H5E_auto1_t func, void *client_data);
* \param[in] client_data Data to be passed to \p func
* \return \herr_t
*
+ * \deprecated 1.8.0 Function H5Ewalk() renamed to H5Ewalk1() and
+ * deprecated in this release.
+ *
* \details H5Ewalk1() walks the error stack for the current thread and calls
* the function specified in \p func for each error along the way.
*
@@ -857,8 +865,6 @@ H5_DLL herr_t H5Eset_auto1(H5E_auto1_t func, void *client_data);
* is as follows:
* \snippet this H5E_walk1_t_snip
*
- * \deprecated 1.8.0 Function H5Ewalk() renamed to H5Ewalk1() and
- * deprecated in this release.
*/
H5_DLL herr_t H5Ewalk1(H5E_direction_t direction, H5E_walk1_t func, void *client_data);
/**
@@ -871,6 +877,8 @@ H5_DLL herr_t H5Ewalk1(H5E_direction_t direction, H5E_walk1_t func, void *client
* \param[in] maj Major error number
* \return \herr_t
*
+ * \deprecated 1.8.0 Function deprecated in this release.
+ *
* \details Given a major error number, H5Eget_major() returns a constant
* character string that describes the error.
*
@@ -878,7 +886,6 @@ H5_DLL herr_t H5Ewalk1(H5E_direction_t direction, H5E_walk1_t func, void *client
* array). An application calling this function must free the memory
* associated with the return value to prevent a memory leak.
*
- * \deprecated 1.8.0 Function deprecated in this release.
*/
H5_DLL char *H5Eget_major(H5E_major_t maj);
/**
@@ -891,6 +898,8 @@ H5_DLL char *H5Eget_major(H5E_major_t maj);
* \param[in] min Minor error number
* \return \herr_t
*
+ * \deprecated 1.8.0 Function deprecated and return type changed in this release.
+ *
* \details Given a minor error number, H5Eget_minor() returns a constant
* character string that describes the error.
*
@@ -900,7 +909,6 @@ H5_DLL char *H5Eget_major(H5E_major_t maj);
* the memory associated with the return value to prevent a memory
* leak. This is a change from the 1.6.x release series.
*
- * \deprecated 1.8.0 Function deprecated and return type changed in this release.
*/
H5_DLL char *H5Eget_minor(H5E_minor_t min);
#endif /* H5_NO_DEPRECATED_SYMBOLS */
diff --git a/src/H5Fmodule.h b/src/H5Fmodule.h
index 7f0299a..81c1ede 100644
--- a/src/H5Fmodule.h
+++ b/src/H5Fmodule.h
@@ -29,8 +29,7 @@
#define H5_MY_PKG_ERR H5E_FILE
#define H5_MY_PKG_INIT YES
-/**
- * \defgroup H5F H5F
+/**\defgroup H5F H5F
*
* Use the functions in this module to manage HDF5 files.
*
@@ -41,15 +40,23 @@
* creation or access \c mode control the interaction with the underlying
* storage such as file systems.
*
- * \Emph{Proper error handling is part of the life cycle.}
*
- * | Create | Open |
|---|
+ * | Create | Read |
|---|
*
* |
- * \snippet H5F_examples.c life_cycle
+ * \snippet{lineno} H5F_examples.c create
* |
*
- * \snippet H5F_examples.c life_cycle_w_open
+ * \snippet{lineno} H5F_examples.c read
+ * |
+ *
+ * | Update | Delete |
|---|
+ *
+ * |
+ * \snippet{lineno} H5F_examples.c update
+ * |
+ *
+ * \snippet{lineno} H5F_examples.c delete
* |
*
*
diff --git a/src/H5Fpublic.h b/src/H5Fpublic.h
index 2fe1c9f..58fa3b8 100644
--- a/src/H5Fpublic.h
+++ b/src/H5Fpublic.h
@@ -188,7 +188,7 @@ typedef enum H5F_libver_t {
H5F_LIBVER_EARLIEST = 0, /**< Use the earliest possible format for storing objects */
H5F_LIBVER_V18 = 1, /**< Use the latest v18 format for storing objects */
H5F_LIBVER_V110 = 2, /**< Use the latest v110 format for storing objects */
- H5F_LIBVER_NBOUNDS
+ H5F_LIBVER_NBOUNDS /**< Sentinel */
} H5F_libver_t;
#define H5F_LIBVER_LATEST H5F_LIBVER_V110
diff --git a/src/H5Gmodule.h b/src/H5Gmodule.h
index fe26bd2..a0e121d 100644
--- a/src/H5Gmodule.h
+++ b/src/H5Gmodule.h
@@ -29,8 +29,29 @@
#define H5_MY_PKG_ERR H5E_SYM
#define H5_MY_PKG_INIT YES
-/**
- * \defgroup H5G H5G
+/** \defgroup H5G H5G
+ *
+ * Use the functions in this module to manage HDF5 groups.
+ *
+ *
+ * | Create | Read |
|---|
+ *
+ * |
+ * \snippet{lineno} H5G_examples.c create
+ * |
+ *
+ * \snippet{lineno} H5G_examples.c read
+ * |
+ *
| Update | Delete |
|---|
+ *
+ * |
+ * \snippet{lineno} H5G_examples.c update
+ * |
+ *
+ * \snippet{lineno} H5G_examples.c delete
+ * |
+ *
+ *
*
* \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.
+ *
+ *
+ * | Create | Read |
|---|
+ *
+ * |
+ * \snippet{lineno} H5I_examples.c create
+ * |
+ *
+ * \snippet{lineno} H5I_examples.c read
+ * |
+ *
| Update | Delete |
|---|
+ *
+ * |
+ * \snippet{lineno} H5I_examples.c update
+ * |
+ *
+ * \snippet{lineno} H5I_examples.c delete
+ * |
+ *
+ *
+ *
+ * \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.
+ *
+ *
+ * | Create | Read |
|---|
+ *
+ * |
+ * \snippet{lineno} H5I_examples.c create_ud
+ * |
+ *
+ * \snippet{lineno} H5I_examples.c read_ud
+ * |
+ *
| Update | Delete |
|---|
+ *
+ * |
+ * \snippet{lineno} H5I_examples.c update_ud
+ * |
+ *
+ * \snippet{lineno} H5I_examples.c delete_ud
+ * |
+ *
+ *
+ *
*/
#endif /* H5Imodule_H */
diff --git a/src/H5Ipublic.h b/src/H5Ipublic.h
index a632881..d07347b 100644
--- a/src/H5Ipublic.h
+++ b/src/H5Ipublic.h
@@ -94,7 +94,7 @@ extern "C" {
/* Public API functions */
/**
- * \ingroup H5I
+ * \ingroup H5IUD
*
* \brief Registers an object under a type and returns an ID for it
*
@@ -116,7 +116,7 @@ extern "C" {
*/
H5_DLL hid_t H5Iregister(H5I_type_t type, const void *object);
/**
- * \ingroup H5I
+ * \ingroup H5IUD
*
* \brief Returns the object referenced by an ID
*
@@ -139,7 +139,7 @@ H5_DLL hid_t H5Iregister(H5I_type_t type, const void *object);
*/
H5_DLL void *H5Iobject_verify(hid_t id, H5I_type_t type);
/**
- * \ingroup H5I
+ * \ingroup H5IUD
*
* \brief Removes an ID from its type
*
@@ -178,12 +178,7 @@ H5_DLL void *H5Iremove_verify(hid_t id, H5I_type_t type);
* \return Returns the object type if successful; otherwise #H5I_BADID.
*
* \details H5Iget_type() retrieves the type of the object identified by
- * \p id.
- *
- * Valid types returned by the function are:
- * \id_types
- *
- * If no valid type can be determined or the identifier submitted is
+ * \p id. If no valid type can be determined or the identifier submitted is
* invalid, the function returns #H5I_BADID.
*
* This function is of particular use in determining the type of
@@ -379,7 +374,7 @@ H5_DLL int H5Idec_ref(hid_t id);
*/
H5_DLL int H5Iget_ref(hid_t id);
/**
- * \ingroup H5I
+ * \ingroup H5IUD
*
* \brief Creates and returns a new ID type
*
@@ -411,7 +406,7 @@ H5_DLL int H5Iget_ref(hid_t id);
*/
H5_DLL H5I_type_t H5Iregister_type(size_t hash_size, unsigned reserved, H5I_free_t free_func);
/**
- * \ingroup H5I
+ * \ingroup H5IUD
*
* \brief Deletes all identifiers of the given type
*
@@ -435,7 +430,7 @@ H5_DLL H5I_type_t H5Iregister_type(size_t hash_size, unsigned reserved, H5I_free
*/
H5_DLL herr_t H5Iclear_type(H5I_type_t type, hbool_t force);
/**
- * \ingroup H5I
+ * \ingroup H5IUD
*
* \brief Removes an identifier type and all identifiers within that type
*
@@ -458,7 +453,7 @@ H5_DLL herr_t H5Iclear_type(H5I_type_t type, hbool_t force);
*/
H5_DLL herr_t H5Idestroy_type(H5I_type_t type);
/**
- * \ingroup H5I
+ * \ingroup H5IUD
*
* \brief Increments the reference count on an ID type
*
@@ -477,7 +472,7 @@ H5_DLL herr_t H5Idestroy_type(H5I_type_t type);
*/
H5_DLL int H5Iinc_type_ref(H5I_type_t type);
/**
- * \ingroup H5I
+ * \ingroup H5IUD
*
* \brief Decrements the reference count on an identifier type
*
@@ -497,7 +492,7 @@ H5_DLL int H5Iinc_type_ref(H5I_type_t type);
*/
H5_DLL int H5Idec_type_ref(H5I_type_t type);
/**
- * \ingroup H5I
+ * \ingroup H5IUD
*
* \brief Retrieves the reference count on an ID type
*
@@ -516,7 +511,7 @@ H5_DLL int H5Idec_type_ref(H5I_type_t type);
*/
H5_DLL int H5Iget_type_ref(H5I_type_t type);
/**
- * \ingroup H5I
+ * \ingroup H5IUD
*
* \brief Finds the memory referred to by an ID within the given ID type such
* that some criterion is satisfied
@@ -557,7 +552,7 @@ H5_DLL int H5Iget_type_ref(H5I_type_t type);
*/
H5_DLL void *H5Isearch(H5I_type_t type, H5I_search_func_t func, void *key);
/**
- * \ingroup H5I
+ * \ingroup H5IUD
*
* \brief Returns the number of identifiers in a given identifier type
*
@@ -577,7 +572,7 @@ H5_DLL void *H5Isearch(H5I_type_t type, H5I_search_func_t func, void *key);
*/
H5_DLL herr_t H5Inmembers(H5I_type_t type, hsize_t *num_members);
/**
- * \ingroup H5I
+ * \ingroup H5IUD
*
* \brief Determines whether an identifier type is registered
*
diff --git a/src/H5Lmodule.h b/src/H5Lmodule.h
index 54b94a4..cffd25c 100644
--- a/src/H5Lmodule.h
+++ b/src/H5Lmodule.h
@@ -30,11 +30,34 @@
#define H5_MY_PKG_INIT YES
/**\defgroup H5L H5L
- * \brief Link Interface
- * \todo Describe concisely what the functions in this module are about.
+ *
+ * Use the functions in this module to manage HDF5 links and link types.
+ *
+ *
+ * | Create | Read |
|---|
+ *
+ * |
+ * \snippet{lineno} H5L_examples.c create
+ * |
+ *
+ * \snippet{lineno} H5L_examples.c iter_cb
+ * \snippet{lineno} H5L_examples.c read
+ * |
+ *
| Update | Delete |
|---|
+ *
+ * |
+ * \snippet{lineno} H5L_examples.c update
+ * |
+ *
+ * \snippet{lineno} H5L_examples.c delete
+ * |
+ *
+ *
*
* \defgroup TRAV Link Traversal
* \ingroup H5L
+ * \defgroup H5LA Advanced Link Functions
+ * \ingroup H5L
*/
#endif /* H5Lmodule_H */
diff --git a/src/H5Lpublic.h b/src/H5Lpublic.h
index a87edfe..be0d065 100644
--- a/src/H5Lpublic.h
+++ b/src/H5Lpublic.h
@@ -713,38 +713,37 @@ H5_DLL htri_t H5Lexists(hid_t loc_id, const char *name, hid_t lapl_id);
* specifies the link being queried.
*
* \p lapl_id is the link access property list associated with the
- * link \p name. In the general case, when default link access
- * properties are acceptable, this can be passed in as #H5P_DEFAULT.
- * An example of a situation that requires a non-default link access
- * property list is when the link is an external link; an external
- * link may require that a link prefix be set in a link access
- * property list (see H5Pset_elink_prefix()).
+ * link name. In the general case, when default link access properties
+ * are acceptable, this can be passed in as #H5P_DEFAULT. An example
+ * of a situation that requires a non-default link access property
+ * list is when the link is an external link; an external link may
+ * require that a link prefix be set in a link access property list
+ * (see H5Pset_elink_prefix()).
*
* H5Lget_info() returns information about name in the data structure
- * \ref H5L_info_t, which is described below and defined in
- * H5Lpublic.h. This structure is returned in the buffer \p linfo.
+ * H5L_info_t, which is described below and defined in H5Lpublic.h.
+ * This structure is returned in the buffer \p linfo.
* \snippet this H5L_info_t_snip
- * In the above struct, type specifies the link class. Valid values
+ * In the above struct, \c type specifies the link class. Valid values
* include the following:
* \link_types
* There will be additional valid values if user-defined links have
* been registered.
*
- * \c corder specifies the link’s creation order position while
- * \c corder_valid indicates whether the value in \c corder is valid.
- *
- * If \c corder_valid is \c TRUE, the value in \c corder is known to
- * be valid; if \c corder_valid is \c FALSE, the value in \c corder is
- * presumed to be invalid;
+ * \p corder specifies the link’s creation order position while
+ * \p corder_valid indicates whether the value in corder is valid.
*
- * \c corder starts at zero (0) and is incremented by one (1) as new
- * links are created. But higher-numbered entries are not adjusted
- * when a lower-numbered link is deleted; the deleted link’s creation
- * order position is simply left vacant. In such situations, the value
- * of \c corder for the last link created will be larger than the
- * number of links remaining in the group.
+ * If \p corder_valid is \c TRUE, the value in \p corder is known to
+ * be valid; if \p corder_valid is \c FALSE, the value in \p corder is
+ * presumed to be invalid; \p corder starts at zero (0) and is
+ * incremented by one (1) as new links are created. But
+ * higher-numbered entries are not adjusted when a lower-numbered link
+ * is deleted; the deleted link's creation order position is simply
+ * left vacant. In such situations, the value of \p corder for the
+ * last link created will be larger than the number of links remaining
+ * in the group.
*
- * \c cset specifies the character set in which the link name is
+ * \p cset specifies the character set in which the link name is
* encoded. Valid values include the following:
* \csets
* This value is set with H5Pset_char_encoding().
@@ -784,9 +783,8 @@ H5_DLL herr_t H5Lget_info(hid_t loc_id, const char *name, H5L_info_t *linfo, hid
* \return \herr_t
*
* \details H5get_info_by_idx() returns the metadata for a link in a group
- * according to a specified field or index and a specified order.
- *
- * The link for which information is to be returned is specified by \p
+ * according to a specified field or index and a specified order. The
+ * link for which information is to be returned is specified by \p
* idx_type, \p order, and \p n as follows:
*
* - \p idx_type specifies the field by which the links in \p
@@ -947,19 +945,18 @@ H5_DLL herr_t H5Literate(hid_t grp_id, H5_index_t idx_type, H5_iter_order_t orde
/**
* \ingroup TRAV
*
- * \brief Iterates through links in a group by its name
+ * \brief Iterates through links in a group
*
* \loc_id
* \param[in] group_name Group name
* \idx_type
* \order
* \param[in,out] idx iteration position at which to start (\Emph{IN}) or
- * position at which an interrupted iteration may be restarted
- * (\Emph{OUT})
+ * position at which an interrupted iteration may be restarted
+ * (\Emph{OUT})
* \op
* \op_data
* \lapl_id
- *
* \return \success{The return value of the first operator that returns
* non-zero, or zero if all members were processed with no
* operator returning non-zero.}
@@ -1022,7 +1019,6 @@ H5_DLL herr_t H5Literate_by_name(hid_t loc_id, const char *group_name, H5_index_
* \order
* \op
* \op_data
- *
* \return \success{The return value of the first operator that returns
* non-zero, or zero if all members were processed with no
* operator returning non-zero.}
@@ -1109,11 +1105,7 @@ H5_DLL herr_t H5Lvisit(hid_t grp_id, H5_index_t idx_type, H5_iter_order_t order,
* \op_data
* \lapl_id
*
- * \return \success{The return value of the first operator that returns
- * non-zero, or zero if all members were processed with no
- * operator returning non-zero.}
- * \return \failure{Negative if an error occurs in the library, or the negative
- * value returned by one of the operators.}
+ * \return \herr_t
*
* \details H5Lvisit_by_name() is a recursive iteration function to visit all
* links in and below a group in an HDF5 file, thus providing a
diff --git a/src/H5Omodule.h b/src/H5Omodule.h
index 134aa92..8afba29 100644
--- a/src/H5Omodule.h
+++ b/src/H5Omodule.h
@@ -30,9 +30,46 @@
#define H5_MY_PKG_INIT YES
/**\defgroup H5O H5O
- * \brief Object Interface
*
- * \todo Describe concisely what the functions in this module are about.
+ * Use the functions in this module to manage HDF5 objects.
+ *
+ * HDF5 objects (groups, datasets, datatype objects) are usually created
+ * using functions in the object-specific modules (\ref H5G, \ref H5D,
+ * \ref H5T). However, new objects can also be created by copying existing
+ * objects.
+ *
+ * Many functions in this module are variations on object introspection,
+ * that is, the retrieval of detailed information about HDF5 objects in a file.
+ * Objects in an HDF5 file can be "visited" in an iterative fashion.
+ *
+ * HDF5 objects are usually updated using functions in the object-specific
+ * modules. However, there are certain generic object properties, such as
+ * reference counts, that can be manipulated using functions in this module.
+ *
+ * HDF5 objects are deleted as a side effect of rendering them unreachable
+ * from the root group. The net effect is the diminution of the object's
+ * reference count to zero, which can (but should not usually) be effected
+ * by a function in this module.
+ *
+ *
+ * | Create | Read |
|---|
+ *
+ * |
+ * \snippet{lineno} H5O_examples.c create
+ * |
+ *
+ * \snippet{lineno} H5O_examples.c read
+ * |
+ *
| Update | Delete |
|---|
+ *
+ * |
+ * \snippet{lineno} H5O_examples.c update
+ * |
+ *
+ * \snippet{lineno} H5O_examples.c delete
+ * |
+ *
+ *
*
*/
#endif /* H5Omodule_H */
diff --git a/src/H5Opublic.h b/src/H5Opublic.h
index 3cb7372..769df60 100644
--- a/src/H5Opublic.h
+++ b/src/H5Opublic.h
@@ -35,14 +35,14 @@
/*****************/
/* Flags for object copy (H5Ocopy) */
-#define H5O_COPY_SHALLOW_HIERARCHY_FLAG (0x0001u) /* Copy only immediate members */
-#define H5O_COPY_EXPAND_SOFT_LINK_FLAG (0x0002u) /* Expand soft links into new objects */
-#define H5O_COPY_EXPAND_EXT_LINK_FLAG (0x0004u) /* Expand external links into new objects */
-#define H5O_COPY_EXPAND_REFERENCE_FLAG (0x0008u) /* Copy objects that are pointed by references */
-#define H5O_COPY_WITHOUT_ATTR_FLAG (0x0010u) /* Copy object without copying attributes */
-#define H5O_COPY_PRESERVE_NULL_FLAG (0x0020u) /* Copy NULL messages (empty space) */
-#define H5O_COPY_MERGE_COMMITTED_DTYPE_FLAG (0x0040u) /* Merge committed datatypes in dest file */
-#define H5O_COPY_ALL (0x007Fu) /* All object copying flags (for internal checking) */
+#define H5O_COPY_SHALLOW_HIERARCHY_FLAG (0x0001u) /**< Copy only immediate members */
+#define H5O_COPY_EXPAND_SOFT_LINK_FLAG (0x0002u) /**< Expand soft links into new objects */
+#define H5O_COPY_EXPAND_EXT_LINK_FLAG (0x0004u) /**< Expand external links into new objects */
+#define H5O_COPY_EXPAND_REFERENCE_FLAG (0x0008u) /**< Copy objects that are pointed by references */
+#define H5O_COPY_WITHOUT_ATTR_FLAG (0x0010u) /**< Copy object without copying attributes */
+#define H5O_COPY_PRESERVE_NULL_FLAG (0x0020u) /**< Copy NULL messages (empty space) */
+#define H5O_COPY_MERGE_COMMITTED_DTYPE_FLAG (0x0040u) /**< Merge committed datatypes in dest file */
+#define H5O_COPY_ALL (0x007Fu) /**< All object copying flags (for internal checking) */
/* Flags for shared message indexes.
* Pass these flags in using the mesg_type_flags parameter in
@@ -51,25 +51,27 @@
* but we need to assign each kind of message to a different bit so that
* one index can hold multiple types.)
*/
-#define H5O_SHMESG_NONE_FLAG 0x0000 /* No shared messages */
-#define H5O_SHMESG_SDSPACE_FLAG ((unsigned)1 << 0x0001) /* Simple Dataspace Message. */
-#define H5O_SHMESG_DTYPE_FLAG ((unsigned)1 << 0x0003) /* Datatype Message. */
-#define H5O_SHMESG_FILL_FLAG ((unsigned)1 << 0x0005) /* Fill Value Message. */
-#define H5O_SHMESG_PLINE_FLAG ((unsigned)1 << 0x000b) /* Filter pipeline message. */
-#define H5O_SHMESG_ATTR_FLAG ((unsigned)1 << 0x000c) /* Attribute Message. */
+#define H5O_SHMESG_NONE_FLAG 0x0000 /**< No shared messages */
+#define H5O_SHMESG_SDSPACE_FLAG ((unsigned)1 << 0x0001) /**< Simple Dataspace Message. */
+#define H5O_SHMESG_DTYPE_FLAG ((unsigned)1 << 0x0003) /**< Datatype Message. */
+#define H5O_SHMESG_FILL_FLAG ((unsigned)1 << 0x0005) /**< Fill Value Message. */
+#define H5O_SHMESG_PLINE_FLAG ((unsigned)1 << 0x000b) /**< Filter pipeline message. */
+#define H5O_SHMESG_ATTR_FLAG ((unsigned)1 << 0x000c) /**< Attribute Message. */
#define H5O_SHMESG_ALL_FLAG \
(H5O_SHMESG_SDSPACE_FLAG | H5O_SHMESG_DTYPE_FLAG | H5O_SHMESG_FILL_FLAG | H5O_SHMESG_PLINE_FLAG | \
H5O_SHMESG_ATTR_FLAG)
+/* clang-format off */
/* Object header status flag definitions */
-#define H5O_HDR_CHUNK0_SIZE 0x03 /* 2-bit field indicating # of bytes to store the size of chunk 0's data */
-#define H5O_HDR_ATTR_CRT_ORDER_TRACKED 0x04 /* Attribute creation order is tracked */
-#define H5O_HDR_ATTR_CRT_ORDER_INDEXED 0x08 /* Attribute creation order has index */
-#define H5O_HDR_ATTR_STORE_PHASE_CHANGE 0x10 /* Non-default attribute storage phase change values stored */
-#define H5O_HDR_STORE_TIMES 0x20 /* Store access, modification, change & birth times for object */
+#define H5O_HDR_CHUNK0_SIZE 0x03 /**< 2-bit field indicating # of bytes to store the size of chunk 0's data */
+#define H5O_HDR_ATTR_CRT_ORDER_TRACKED 0x04 /**< Attribute creation order is tracked */
+#define H5O_HDR_ATTR_CRT_ORDER_INDEXED 0x08 /**< Attribute creation order has index */
+#define H5O_HDR_ATTR_STORE_PHASE_CHANGE 0x10 /**< Non-default attribute storage phase change values stored */
+#define H5O_HDR_STORE_TIMES 0x20 /**< Store access, modification, change & birth times for object */
#define H5O_HDR_ALL_FLAGS \
(H5O_HDR_CHUNK0_SIZE | H5O_HDR_ATTR_CRT_ORDER_TRACKED | H5O_HDR_ATTR_CRT_ORDER_INDEXED | \
H5O_HDR_ATTR_STORE_PHASE_CHANGE | H5O_HDR_STORE_TIMES)
+/* clang-format on */
/* Maximum shared message values. Number of indexes is 8 to allow room to add
* new types of messages.
@@ -81,11 +83,11 @@
* Theses flags determine which fields will be filled in in the H5O_info_t
* struct.
*/
-#define H5O_INFO_BASIC 0x0001u /* Fill in the fileno, addr, type, and rc fields */
-#define H5O_INFO_TIME 0x0002u /* Fill in the atime, mtime, ctime, and btime fields */
-#define H5O_INFO_NUM_ATTRS 0x0004u /* Fill in the num_attrs field */
-#define H5O_INFO_HDR 0x0008u /* Fill in the hdr field */
-#define H5O_INFO_META_SIZE 0x0010u /* Fill in the meta_size field */
+#define H5O_INFO_BASIC 0x0001u /**< Fill in the fileno, addr, type, and rc fields */
+#define H5O_INFO_TIME 0x0002u /**< Fill in the atime, mtime, ctime, and btime fields */
+#define H5O_INFO_NUM_ATTRS 0x0004u /**< Fill in the num_attrs field */
+#define H5O_INFO_HDR 0x0008u /**< Fill in the hdr field */
+#define H5O_INFO_META_SIZE 0x0010u /**< Fill in the meta_size field */
#define H5O_INFO_ALL (H5O_INFO_BASIC | H5O_INFO_TIME | H5O_INFO_NUM_ATTRS | H5O_INFO_HDR | H5O_INFO_META_SIZE)
/*******************/
@@ -144,11 +146,10 @@ typedef struct H5O_info_t {
time_t btime; /**< Birth time */
hsize_t num_attrs; /**< # of attributes attached to object */
H5O_hdr_info_t hdr; /**< Object header information */
- /* Extra metadata storage for obj & attributes */
struct {
H5_ih_info_t obj; /**< v1/v2 B-tree & local/fractal heap for groups, B-tree for chunked datasets */
H5_ih_info_t attr; /**< v2 B-tree & heap for attributes */
- } meta_size;
+ } meta_size; /**< Extra metadata storage for obj & attributes */
} H5O_info_t;
//!
@@ -160,6 +161,17 @@ typedef uint32_t H5O_msg_crt_idx_t;
//!
/**
* Prototype for H5Ovisit(), H5Ovisit_by_name() operator (version 3)
+ *
+ * \param[in] obj Object that serves as the root of the iteration;
+ * the same value as the H5Ovisit() \c obj_id parameter
+ * \param[in] name Name of object, relative to \p obj, being examined at current
+ * step of the iteration
+ * \param[out] info Information about that object
+ * \param[in,out] op_data User-defined pointer to data required by the application
+ * in processing the object; a pass-through of the \c op_data
+ * pointer provided with the H5Ovisit3() function call
+ * \return \herr_t_iter
+ *
*/
typedef herr_t (*H5O_iterate_t)(hid_t obj, const char *name, const H5O_info_t *info, void *op_data);
//!
@@ -448,8 +460,7 @@ H5_DLL htri_t H5Oexists_by_name(hid_t loc_id, const char *name, hid_t lapl_id);
* \return \herr_t
*
* \details H5Oget_info2() specifies an object by its identifier, \p loc_id , and
- * retrieves the metadata describing that object in \p oinfo , an H5O_info1_t \c struct.
- * This \c struct type is described in H5Oget_info1().
+ * retrieves the metadata describing that object in \p oinfo.
*
* The \p fields parameter contains flags to determine which fields will be filled in
* the H5O_info1_t \c struct returned in \p oinfo.
@@ -457,6 +468,11 @@ H5_DLL htri_t H5Oexists_by_name(hid_t loc_id, const char *name, hid_t lapl_id);
*
* \obj_info_fields
*
+ * \par Example
+ * An example snippet from examples/h5_attribute.c:
+ * \par
+ * \snippet h5_attribute.c H5Oget_info2_snip
+ *
* \note If you are iterating through a lot of different objects to
* retrieve information via the H5Oget_info() family of routines,
* you may see memory building up. This can be due to memory
@@ -477,8 +493,8 @@ H5_DLL herr_t H5Oget_info2(hid_t loc_id, H5O_info_t *oinfo, unsigned fields);
*-------------------------------------------------------------------------
* \ingroup H5O
*
- * \brief Retrieves the metadata for an object, identifying the object
- * by location and relative name
+ * \brief Retrieves the metadata for an object, identifying the object by
+ * location and relative name
*
* \fgdta_loc_obj_id{loc_id}
* \param[in] name Name of group, relative to \p loc_id
@@ -488,20 +504,17 @@ H5_DLL herr_t H5Oget_info2(hid_t loc_id, H5O_info_t *oinfo, unsigned fields);
*
* \return \herr_t
*
- * \details H5Oget_info_by_name2() specifies an object’s location and name, \p loc_id and
- * \p name, respectively, and retrieves the metadata describing
- * that object in \p oinfo, an H5O_info1_t \c struct.
+ * \details H5Oget_info_by_name2() specifies an object’s location and name,
+ * \p loc_id and \p name, respectively, and retrieves the metadata
+ * describing that object in \p oinfo, an H5O_info1_t struct.
*
- * The \c struct H5O_info1_t is defined in H5Opublic.h and described
- * in the H5Oget_info1() function entry.
- *
- * The \p fields parameter contains flags to determine which fields
- * will be filled in in the H5O_info1_t \c struct returned in
- * \p oinfo. These flags are defined in the H5Opublic.h file:
+ * The \p fields parameter contains flags to determine which fields will be filled in
+ * the H5O_info1_t \c struct returned in \p oinfo.
+ * These flags are defined in the H5Opublic.h file:
*
* \obj_info_fields
*
- * The link access property list, \p lapl_id, is not currently used;
+ * The link access property list, \c lapl_id, is not currently used;
* it should be passed in as #H5P_DEFAULT.
*
* \since 1.10.3
@@ -509,6 +522,7 @@ H5_DLL herr_t H5Oget_info2(hid_t loc_id, H5O_info_t *oinfo, unsigned fields);
*/
H5_DLL herr_t H5Oget_info_by_name2(hid_t loc_id, const char *name, H5O_info_t *oinfo, unsigned fields,
hid_t lapl_id);
+
/**
*-------------------------------------------------------------------------
* \ingroup H5O
@@ -520,7 +534,7 @@ H5_DLL herr_t H5Oget_info_by_name2(hid_t loc_id, const char *name, H5O_info_t *o
* \param[in] group_name Name of group in which object is located
* \idx_type
* \order
- * \param[in] n Position within the index
+ * \param[in] n Position within the index
* \param[out] oinfo Buffer in which to return object information
* \param[in] fields Flags specifying the fields to include in \p oinfo
* \lapl_id
@@ -534,15 +548,11 @@ H5_DLL herr_t H5Oget_info_by_name2(hid_t loc_id, const char *name, H5O_info_t *o
* index is to be traversed, \p order, and an object’s position
* \p n within that index.
*
- * \p oinfo, in which the object information is returned, is a \c struct of
- * type H5O_info1_t. This and other \c struct types used
- * by H5Oget_info_by_idx2() are described in H5Oget_info_by_idx1().
- *
* If \p loc_id fully specifies the group in which the object resides,
- * i\p group_name can be a dot (\c .).
+ * \p group_name can be a dot (\c .).
*
- * The \p fields parameter contains flags to determine which fields will be
- * filled in the H5O_info1_t \c struct returned in \p oinfo.
+ * The \p fields parameter contains flags to determine which fields will be filled in
+ * the H5O_info1_t \c struct returned in \p oinfo.
* These flags are defined in the H5Opublic.h file:
* \obj_info_fields
*
@@ -991,9 +1001,9 @@ H5_DLL ssize_t H5Oget_comment_by_name(hid_t loc_id, const char *name, char *comm
* \details H5Ovisit2() is a recursive iteration function to visit the
* object \p obj_id and, if \p obj_id is a group, all objects in
* and below it in an HDF5 file, thus providing a mechanism for
- * an application to perform a common set of operations across all
- * of those objects or a dynamically selected subset. For
- * non-recursive iteration across the members of a group,
+ * an application to perform a common set of operations across
+ * all of those objects or a dynamically selected subset.
+ * For non-recursive iteration across the members of a group,
* see H5Literate1().
*
* If \p obj_id is a group identifier, that group serves as the
@@ -1011,11 +1021,8 @@ H5_DLL ssize_t H5Oget_comment_by_name(hid_t loc_id, const char *name, char *comm
* a group have not been indexed by the index type, they will
* first be sorted by that index then the iteration will begin;
* if the links have been so indexed, the sorting step will be
- * unnecessary, so the iteration may begin more quickly. Valid
- * values include the following:
- *
- * \indexes
- *
+ * unnecessary, so the iteration may begin more quickly.
+
* Note that the index type passed in \p idx_type is a
*
best effort setting. If the application passes in
* a value indicating iteration in creation order and a group is
@@ -1025,52 +1032,7 @@ H5_DLL ssize_t H5Oget_comment_by_name(hid_t loc_id, const char *name, char *comm
* used by the HDF5 library and is always available.)
*
* \p order specifies the order in which objects are to be inspected
- * along the index specified in \p idx_type. Valid values include
- * the following:
- *
- * \orders
- *
- * The prototype of the callback function op is as follows (as
- * defined in the source code file H5Opublic.h):
- *
- * \snippet this H5O_iterate1_t_snip
- *
- * The parameters of this callback function have the following values
- * or meanings:
- *
- *
- * | \c obj |
- * Object that serves as root of the iteration;
- * same value as the H5Ovisit1() \p obj_id parameter |
- *
- *
- * | \c name |
- * Name of object, relative to \c obj, being examined at
- * current step of the iteration |
- *
- *
- * | \c info |
- * H5O_info1_t \c struct containing information
- * regarding that object |
- *
- *
- * | \c 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 H5Ovisit() function call |
- *
- *
- *
- * The H5O_info1_t \c struct is defined in H5Opublic.h and
- * described in the H5Oget_info1() function entry.
- *
- * The return values from an operator are:
- * - Zero causes the visit iterator to continue, returning zero when all
- * group members have been processed.
- * - A positive value causes the visit iterator to immediately return that
- * positive value, indicating short-circuit success.
- * - A negative value causes the visit iterator to immediately return that
- * value, indicating failure.
+ * along the index specified in \p idx_type.
*
* The H5Ovisit2() \p op_data parameter is a user-defined pointer to the data
* required to process objects in the course of the iteration. This pointer
@@ -1117,11 +1079,12 @@ H5_DLL ssize_t H5Oget_comment_by_name(hid_t loc_id, const char *name, char *comm
*/
H5_DLL herr_t H5Ovisit2(hid_t obj_id, H5_index_t idx_type, H5_iter_order_t order, H5O_iterate_t op,
void *op_data, unsigned fields);
+
/**
*-------------------------------------------------------------------------
* \ingroup H5O
*
- * \brief Recursively visits all objects starting from a specified object
+ * \brief Recursively visits all objects accessible from a specified object
*
* \fgdta_loc_obj_id{loc_id}
* \param[in] obj_name Name of the object, generally relative to
@@ -1150,7 +1113,7 @@ H5_DLL herr_t H5Ovisit2(hid_t obj_id, H5_index_t idx_type, H5_iter_order_t order
* in an HDF5 file, thus providing a mechanism for an application to
* perform a common set of operations across all of those objects or
* a dynamically selected subset. For non-recursive iteration across
- * the members of a group, see #H5Literate.
+ * the members of a group, see H5Literate().
*
* The object serving as the root of the iteration is specified
* by the \p loc_id / \p obj_name parameter pair. \p loc_id specifies
@@ -1162,7 +1125,7 @@ H5_DLL herr_t H5Ovisit2(hid_t obj_id, H5_index_t idx_type, H5_iter_order_t order
* as the root of the iteration, \p obj_name should be '\c .' (a dot).
* (Note that when \p loc_id fully specifies the object that is to serve
* as the root of the iteration, the user may wish to consider
- * using H5Ovisit2() instead of #H5Ovisit_by_name.)
+ * using H5Ovisit2() instead of H5Ovisit_by_name().)
*
* Two parameters are used to establish the iteration: \p idx_type
* and \p order.
@@ -1174,8 +1137,6 @@ H5_DLL herr_t H5Ovisit2(hid_t obj_id, H5_index_t idx_type, H5_iter_order_t order
* unnecessary, so the iteration may begin more quickly. Valid
* values include the following:
*
- * \indexes
- *
* Note that the index type passed in \p idx_type is a
*
best effort setting. If the application passes in a
* value indicating iteration in creation order and a group is
@@ -1185,17 +1146,7 @@ H5_DLL herr_t H5Ovisit2(hid_t obj_id, H5_index_t idx_type, H5_iter_order_t order
* used by the HDF5 library and is always available.)
*
* \p order specifies the order in which objects are to be inspected
- * along the index specified in \p idx_type. Valid values include
- * the following:
- *
- * \orders
- *
- * The \p op callback function and the effect of the callback
- * function’s return value on the application are described
- * in H5Ovisit2().
- *
- * The H5O_info1_t \c struct is defined in H5Opublic.h
- * and described in the H5Oget_info1() function entry.
+ * along the index specified in \p idx_type.
*
* The H5Ovisit_by_name2() \p op_data parameter is a user-defined
* pointer to the data required to process objects in the course
@@ -1215,7 +1166,7 @@ H5_DLL herr_t H5Ovisit2(hid_t obj_id, H5_index_t idx_type, H5_iter_order_t order
* in the H5Opublic.h file:
* \obj_info_fields
*
- * #H5Lvisit_by_name and #H5Ovisit_by_name are companion
+ * H5Lvisit_by_name() and H5Ovisit_by_name() are companion
* functions: one for examining and operating on links; the other
* for examining and operating on the objects that those links point to.
* Both functions ensure that by the time the function completes
@@ -1247,6 +1198,7 @@ H5_DLL herr_t H5Ovisit2(hid_t obj_id, H5_index_t idx_type, H5_iter_order_t order
H5_DLL herr_t H5Ovisit_by_name2(hid_t loc_id, const char *obj_name, H5_index_t idx_type,
H5_iter_order_t order, H5O_iterate_t op, void *op_data, unsigned fields,
hid_t lapl_id);
+
/**
*-------------------------------------------------------------------------
* \ingroup H5O
@@ -1295,32 +1247,16 @@ H5_DLL herr_t H5Oclose(hid_t object_id);
* files. After that, the OS is responsible for ensuring that
* the data is actually flushed to disk.
*
- * \par See Also:
- * - H5Dflush()
- * - H5Drefresh()
- * - H5Oflush()
- * - H5Grefresh()
- * - H5Oflush()
- * - H5Orefresh()
- * - H5Tflush()
- * - H5Trefresh()
- * \par
- * - \c H5DOappend()
- * - H5Fstart_swmr_write()
- * - H5Pget_append_flush()
- * - H5Pget_object_flush_cb()
- * - H5Pset_append_flush()
- * - H5Pset_object_flush_cb()
- * \par
- * - H5Oare_mdc_flushes_disabled()
- * - H5Odisable_mdc_flushes()
- * - H5Oenable_mdc_flushes()
+ * \see H5Dflush(), H5Drefresh(), H5Oflush(), H5Grefresh(), H5Oflush(),
+ * H5Orefresh(), H5Tflush(), H5Trefresh()
+ * \see H5DOappend(), H5Fstart_swmr_write(), H5Pget_append_flush(),
+ * H5Pget_object_flush_cb(), H5Pset_append_flush(), H5Pset_object_flush_cb()
+ * \see H5Oare_mdc_flushes_disabled(), H5Odisable_mdc_flushes(), H5Oenable_mdc_flushes()
*
* \since 1.10.0
*
*/
H5_DLL herr_t H5Oflush(hid_t obj_id);
-
/**
*-------------------------------------------------------------------------
* \ingroup H5O
@@ -1373,21 +1309,17 @@ H5_DLL herr_t H5Orefresh(hid_t oid);
* HDF5 object level (datasets, groups, committed datatypes)
* and the entire metadata cache level.
*
- * \note HDF5 objects include datasets, groups, and committed datatypes.
- * Only #hid_t identifiers that represent these objects can be passed to the function.
- * \note Passing in a #hid_t identifier that represents any other HDF5 entity is
- * considered an error.
- * \note It is an error to pass an HDF5 file identifier
- * (obtained from H5Fopen() or H5Fcreate())
- * to this function.
- * \note Misuse of this function can cause the cache to exhaust
- * available memory.
- * \note Objects can be returned to the default automatic flush behavior
- * with H5Oenable_mdc_flushes().
- * \note Flush prevention only pertains to new or dirty metadata entries.
- * Clean entries can be evicted from the cache.
- * \note Calling this function on an object that has already had flushes
- * disabled will return an error.
+ * \note HDF5 objects include datasets, groups, and committed datatypes. Only
+ * #hid_t identifiers that represent these objects can be passed to the
+ * function. Passing in a #hid_t identifier that represents any other
+ * HDF5 entity is considered an error. It is an error to pass an HDF5
+ * file identifier (obtained from H5Fopen() or H5Fcreate()) to this
+ * function. Misuse of this function can cause the cache to exhaust
+ * available memory. Objects can be returned to the default automatic
+ * flush behavior with H5Oenable_mdc_flushes(). Flush prevention only
+ * pertains to new or dirty metadata entries. Clean entries can be
+ * evicted from the cache. Calling this function on an object that has
+ * already had flushes disabled will return an error.
*
* \since 1.10.0
*
@@ -1417,28 +1349,18 @@ H5_DLL herr_t H5Odisable_mdc_flushes(hid_t object_id);
* metadata cache level.
*
*
- * \note HDF5 objects include datasets, groups, and committed datatypes.
- * Only #hid_t identifiers that represent these objects can be
- * passed to the function.
- *
- * \note Passing in a #hid_t identifier that represents any other HDF5 entity
- * is considered an error.
- *
- * \note It is an error to pass an HDF5 file identifier
- * (obtained from H5Fopen() or H5Fcreate())
- * to this function.
- *
- * \note Using this function on an object that has not had flushes disabled
- * is considered an error. The state of an object can be determined
- * with H5Oare_mdc_flushes_disabled().
- *
- * \note An object will be returned to the default flush algorithm when it is closed.
- *
- * \note All objects will be returned to the default flush algorithm when
- * the file is closed.
- *
- * \note An object’s entries will not necessarily be flushed as a result of
- * calling this function.
+ * \note HDF5 objects include datasets, groups, and committed datatypes. Only
+ * #hid_t identifiers that represent these objects can be passed to the
+ * function. Passing in a #hid_t identifier that represents any other
+ * HDF5 entity is considered an error. It is an error to pass an HDF5
+ * file identifier (obtained from H5Fopen() or H5Fcreate()) to this
+ * function. Using this function on an object that has not had flushes
+ * disabled is considered an error. The state of an object can be
+ * determined with H5Oare_mdc_flushes_disabled(). An object will be
+ * returned to the default flush algorithm when it is closed. All objects
+ * will be returned to the default flush algorithm when the file is
+ * closed. An object’s entries will not necessarily be flushed as a
+ * result of calling this function.
*
* \since 1.10.0
*
@@ -1480,7 +1402,6 @@ H5_DLL herr_t H5Oenable_mdc_flushes(hid_t object_id);
*/
H5_DLL herr_t H5Oare_mdc_flushes_disabled(hid_t object_id, hbool_t *are_disabled);
-/* Future function prototypes to be deprecated in next version */
/**
*-------------------------------------------------------------------------
* \ingroup H5O
@@ -1489,19 +1410,11 @@ H5_DLL herr_t H5Oare_mdc_flushes_disabled(hid_t object_id, hbool_t *are_disabled
*
* \fgdta_loc_obj_id{loc_id}
* \param[out] oinfo Buffer in which to return object information
- * \param[in] fields Flags specifying the fields to include in \p oinfo
*
* \return \herr_t
*
* \details H5Oget_info specifies an object by its identifier, \p loc_id , and
- * retrieves the metadata describing that object in \p oinfo , an H5O_info_t \c struct.
- * This \c struct type is described in H5Oget_info().
- *
- * The \p fields parameter contains flags to determine which fields will be filled in
- * the H5O_info_t \c struct returned in \p oinfo.
- * These flags are defined in the H5Opublic.h file:
- *
- * \obj_info_fields
+ * retrieves the metadata describing that object in \p oinfo.
*
* \note If you are iterating through a lot of different objects to
* retrieve information via the H5Oget_info() family of routines,
@@ -1529,24 +1442,17 @@ H5_DLL herr_t H5Oget_info(hid_t loc_id, H5O_info_t *oinfo);
* \fgdta_loc_obj_id{loc_id}
* \param[in] name Name of group, relative to \p loc_id
* \param[out] oinfo Buffer in which to return object information
- * \param[in] fields Flags specifying the fields to include in \p oinfo
* \lapl_id
*
* \return \herr_t
*
- * \details H5Oget_info_by_name() specifies an object’s location and name, \p loc_id and
- * \p name, respectively, and retrieves the metadata describing
- * that object in \p oinfo, an H5O_info1_t \c struct.
+ * \details H5Oget_info_by_name() specifies an object’s location and name, \p loc_id
+ * and \p name, respectively, and retrieves the metadata describing that object
+ * in \p oinfo, an H5O_info1_t \c struct.
*
* The \c struct H5O_info_t is defined in H5Opublic.h and described
* in the H5Oget_info() function entry.
*
- * The \p fields parameter contains flags to determine which fields
- * will be filled in in the H5O_info_t \c struct returned in
- * \p oinfo. These flags are defined in the H5Opublic.h file:
- *
- * \obj_info_fields
- *
* The link access property list, \p lapl_id, is not currently used;
* it should be passed in as #H5P_DEFAULT.
*
@@ -1565,9 +1471,8 @@ H5_DLL herr_t H5Oget_info_by_name(hid_t loc_id, const char *name, H5O_info_t *oi
* \param[in] group_name Name of group in which object is located
* \idx_type
* \order
- * \param[in] n Position within the index
+ * \param[in] n Position within the index
* \param[out] oinfo Buffer in which to return object information
- * \param[in] fields Flags specifying the fields to include in \p oinfo
* \lapl_id
*
* \return \herr_t
@@ -1579,17 +1484,8 @@ H5_DLL herr_t H5Oget_info_by_name(hid_t loc_id, const char *name, H5O_info_t *oi
* index is to be traversed, \p order, and an object’s position
* \p n within that index.
*
- * \p oinfo, in which the object information is returned, is a \c struct of
- * type H5O_info1_t. This and other \c struct types used
- * by H5Oget_info_by_idx() are described in H5Oget_info_by_idx1().
- *
* If \p loc_id fully specifies the group in which the object resides,
- * i\p group_name can be a dot (\c .).
- *
- * The \p fields parameter contains flags to determine which fields will be
- * filled in the H5O_info_t \c struct returned in \p oinfo.
- * These flags are defined in the H5Opublic.h file:
- * \obj_info_fields
+ * \p group_name can be a dot (\c .).
*
* The link access property list, \c lapl_id, is not currently used;
* it should be passed in as #H5P_DEFAULT.
@@ -1808,10 +1704,7 @@ H5_DLL herr_t H5Oget_info_by_idx1(hid_t loc_id, const char *group_name, H5_index
* a group have not been indexed by the index type, they will
* first be sorted by that index then the iteration will begin;
* if the links have been so indexed, the sorting step will be
- * unnecessary, so the iteration may begin more quickly. Valid
- * values include the following:
- *
- * \indexes
+ * unnecessary, so the iteration may begin more quickly.
*
* Note that the index type passed in \p idx_type is a
*
best effort setting. If the application passes in
@@ -1822,56 +1715,7 @@ H5_DLL herr_t H5Oget_info_by_idx1(hid_t loc_id, const char *group_name, H5_index
* used by the HDF5 library and is always available.)
*
* \p order specifies the order in which objects are to be inspected
- * along the index specified in \p idx_type. Valid values include
- * the following:
- *
- * \orders
- *
- * The prototype of the callback function op is as follows (as
- * defined in the source code file H5Opublic.h):
- *
- * \snippet this H5O_iterate1_t_snip
- *
- * The parameters of this callback function have the following values
- * or meanings:
- *
- *
- * | \c obj |
- * Object that serves as root of the iteration;
- * same value as the H5Ovisit1() \p obj_id parameter |
- *
- *
- * | \c name |
- * Name of object, relative to \c obj, being examined at
- * current step of the iteration |
- *
- *
- * | \c info |
- * H5O_info1_t \c struct containing information
- * regarding that object |
- *
- *
- * | \c op_data |
- * User-defined pointer to data required by the application in
- * processing the object |
- *
- *
- *
- * The H5O_info1_t \c struct is defined in H5Opublic.h:
- * \snippet this H5O_info1_t_snip
- *
- * The return values from an operator are:
- * - Zero causes the visit iterator to continue, returning zero when all
- * group members have been processed.
- * - A positive value causes the visit iterator to immediately return that
- * positive value, indicating short-circuit success.
- * - A negative value causes the visit iterator to immediately return that
- * value, indicating failure.
- *
- * The H5Ovisit1() \p op_data parameter is a user-defined pointer to the data
- * required to process objects in the course of the iteration. This pointer
- * is passed back to each step of the iteration in the callback
- * function’s \p op_data parameter.
+ * along the index specified in \p idx_type.
*
* H5Lvisit1() and H5Ovisit1() are companion functions: one for
* examining and operating on links; the other for examining
@@ -1967,10 +1811,7 @@ H5_DLL herr_t H5Ovisit1(hid_t obj_id, H5_index_t idx_type, H5_iter_order_t order
* a group have not been indexed by the index type, they will
* first be sorted by that index then the iteration will begin;
* if the links have been so indexed, the sorting step will be
- * unnecessary, so the iteration may begin more quickly. Valid
- * values include the following:
- *
- * \indexes
+ * unnecessary, so the iteration may begin more quickly.
*
* Note that the index type passed in \p idx_type is a
*
best effort setting. If the application passes in a
@@ -1981,10 +1822,7 @@ H5_DLL herr_t H5Ovisit1(hid_t obj_id, H5_index_t idx_type, H5_iter_order_t order
* used by the HDF5 library and is always available.)
*
* \p order specifies the order in which objects are to be inspected
- * along the index specified in \p idx_type. Valid values include
- * the following:
- *
- * \orders
+ * along the index specified in \p idx_type.
*
* The \p op callback function and the effect of the callback
* function’s return value on the application are described
diff --git a/src/H5PLmodule.h b/src/H5PLmodule.h
index ab9f1d5..a093096 100644
--- a/src/H5PLmodule.h
+++ b/src/H5PLmodule.h
@@ -28,8 +28,34 @@
#define H5_MY_PKG_INIT YES
/**\defgroup H5PL H5PL
- * \brief Plugins
- * \todo Describe what programmatically controlling dynamically loaded plugins (H5PL) is all about
+ *
+ * Use the functions in this module to manage the loading behavior of HDF5
+ * plugins.
+ *
+ *
+ * | Create | Read |
|---|
+ *
+ * |
+ * \snippet H5PL_examples.c create
+ * |
+ *
+ * \snippet H5PL_examples.c read
+ * |
+ *
| Update | Delete |
|---|
+ *
+ * |
+ * \snippet H5PL_examples.c update
+ * |
+ *
+ * \snippet H5PL_examples.c delete
+ * |
+ *
+ *
+ *
+ * \attention The loading behavior of HDF5 plugins can be controlled via the
+ * functions described below and certain environment variables, such
+ * as \c HDF5_PLUGIN_PRELOAD and \c HDF5_PLUGIN_PATH.
+ *
*/
#endif /* H5PLmodule_H */
diff --git a/src/H5Pmodule.h b/src/H5Pmodule.h
index 18f30c6..3c28615 100644
--- a/src/H5Pmodule.h
+++ b/src/H5Pmodule.h
@@ -30,49 +30,162 @@
#define H5_MY_PKG_INIT YES
/**\defgroup H5P H5P
- * \brief Property List Interface
*
- * \details The HDF5 Property List Interface provides a mechanism to take
- * advantage of more powerful or unusual features in HDF5.
+ * Use the functions in this module to manage HDF5 property lists and property
+ * list classes. HDF5 property lists are the main vehicle to configure the
+ * behavior of HDF5 API functions.
*
- * HDF5 objects have properties or characteristics associated with
- * them, and there are default properties that handle the most
- * common needs. These default properties can be modified using the
- * HDF5 Property List Interface. For example, the data storage
- * layout property of a dataset is contiguous by default. For better
- * performance, the layout can be modified to be chunked or chunked
- * and compressed.
+ * Typically, property lists are created by instantiating one of the built-in
+ * or user-defined property list classes. After adding suitable properties,
+ * property lists are used when opening or creating HDF5 items, or when reading
+ * or writing data. Property lists can be modified by adding or changing
+ * properties. Property lists are deleted by closing the associated handles.
*
- * \todo Describe concisely what the functions in this module are about.
+ *
+ * | Create | Read |
|---|
+ *
+ * |
+ * \snippet{lineno} H5P_examples.c create
+ * |
+ *
+ * \snippet{lineno} H5P_examples.c read
+ * |
+ *
| Update | Delete |
|---|
+ *
+ * |
+ * \snippet{lineno} H5P_examples.c update
+ * |
+ *
+ * \snippet{lineno} H5P_examples.c delete
+ * |
+ *
+ *
*
- * \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.
+ *
+ *
+ * | Create | Read |
|---|
+ *
+ * |
+ * \snippet{lineno} H5P_examples.c create
+ * |
+ *
+ * \snippet{lineno} H5P_examples.c read
+ * |
+ *
| Update | Delete |
|---|
+ *
+ * |
+ * \snippet{lineno} H5P_examples.c update
+ * |
+ *
+ * \snippet{lineno} H5P_examples.c delete
+ * |
+ *
+ *
+ *
+ * \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.
+ *
+ *
+ * | Create | Read |
|---|
+ *
+ *
+ * |
+ * \snippet{lineno} H5P_examples.c create_class
+ * |
+ *
+ * \snippet{lineno} H5P_examples.c read_class
+ * |
+ *
| Update | Delete |
|---|
+ *
+ * |
+ * \snippet{lineno} H5P_examples.c update_class
+ * |
+ *
+ * \snippet{lineno} H5P_examples.c delete_class
+ * |
+ *
+ *
+ *
+ * \defgroup LAPL Link Access Properties
* \ingroup H5P
+ *
+ *
* \defgroup OCPL Object Creation Properties
* \ingroup H5P
+ *
+ *
* \defgroup OCPPL Object Copy Properties
* \ingroup H5P
- * \defgroup GACPL General Access Properties
- * \ingroup H5P
- * \defgroup MAPL Map Access Properties
- * \ingroup H5P
+ *
+ *
*/
#endif /* H5Pmodule_H */
diff --git a/src/H5Ppublic.h b/src/H5Ppublic.h
index ca79494..6961c13 100644
--- a/src/H5Ppublic.h
+++ b/src/H5Ppublic.h
@@ -22,16 +22,17 @@
/* Public headers needed by this file */
#include "H5public.h"
-#include "H5ACpublic.h"
-#include "H5Dpublic.h"
-#include "H5Fpublic.h"
-#include "H5FDpublic.h"
-#include "H5Ipublic.h"
-#include "H5Lpublic.h"
-#include "H5Opublic.h"
-#include "H5MMpublic.h"
-#include "H5Tpublic.h"
-#include "H5Zpublic.h"
+#include "H5ACpublic.h" /* Metadata cache */
+#include "H5Dpublic.h" /* Datasets */
+#include "H5Fpublic.h" /* Files */
+#include "H5FDpublic.h" /* File drivers */
+#include "H5Ipublic.h" /* ID management */
+#include "H5Lpublic.h" /* Links */
+#include "H5MMpublic.h" /* Memory management */
+#include "H5Opublic.h" /* Object headers */
+#include "H5Spublic.h" /* Dataspaces */
+#include "H5Tpublic.h" /* Datatypes */
+#include "H5Zpublic.h" /* Data filters */
/*****************/
/* Public Macros */
@@ -91,7 +92,9 @@
#define H5P_CRT_ORDER_TRACKED 0x0001
#define H5P_CRT_ORDER_INDEXED 0x0002
-/* Default value for all property list classes */
+/**
+ * Default value of type \ref hid_t for all property list classes
+ */
#define H5P_DEFAULT 0 /* (hid_t) */
#ifdef __cplusplus
@@ -104,14 +107,23 @@ extern "C" {
/* Define property list class callback function pointer types */
//!
+/**
+ * \todo Document me!
+ */
typedef herr_t (*H5P_cls_create_func_t)(hid_t prop_id, void *create_data);
//!
//!
+/**
+ * \todo Document me!
+ */
typedef herr_t (*H5P_cls_copy_func_t)(hid_t new_prop_id, hid_t old_prop_id, void *copy_data);
//!
//!
+/**
+ * \todo Document me!
+ */
typedef herr_t (*H5P_cls_close_func_t)(hid_t prop_id, void *close_data);
//!
@@ -154,6 +166,9 @@ typedef H5P_prp_cb2_t H5P_prp_delete_func_t;
typedef H5P_prp_cb1_t H5P_prp_copy_func_t;
//!
+/**
+ * \todo Document me!
+ */
typedef int (*H5P_prp_compare_func_t)(const void *value1, const void *value2, size_t size);
//!
@@ -161,6 +176,9 @@ typedef H5P_prp_cb1_t H5P_prp_close_func_t;
/* Define property list iteration function type */
//!
+/**
+ * \todo Document me!
+ */
typedef herr_t (*H5P_iterate_t)(hid_t id, const char *name, void *iter_data);
//!
@@ -2171,7 +2189,7 @@ H5_DLL herr_t H5Pset_attr_creation_order(hid_t plist_id, unsigned crt_order_flag
*/
H5_DLL herr_t H5Pset_attr_phase_change(hid_t plist_id, unsigned max_compact, unsigned min_dense);
/**
- * \ingroup OCPL
+ * \ingroup DCPL
*
* \brief Sets deflate (GNU gzip) compression method and compression level
*
@@ -2180,6 +2198,8 @@ H5_DLL herr_t H5Pset_attr_phase_change(hid_t plist_id, unsigned max_compact, uns
*
* \return \herr_t
*
+ * \par_compr_note
+ *
* \details H5Pset_deflate() sets the deflate compression method and the
* compression level, \p level, for a dataset or group creation
* property list, \p plist_id.
@@ -5113,7 +5133,7 @@ H5_DLL herr_t H5Pset_sieve_buf_size(hid_t fapl_id, size_t size);
H5_DLL herr_t H5Pset_small_data_block_size(hid_t fapl_id, hsize_t size);
#ifdef H5_HAVE_PARALLEL
/**
- * \ingroup GACPL
+ * \ingroup GAPL
*
* \brief Sets metadata I/O mode for read operations to collective or independent (default)
*
@@ -5182,7 +5202,7 @@ H5_DLL herr_t H5Pset_small_data_block_size(hid_t fapl_id, hsize_t size);
*/
H5_DLL herr_t H5Pset_all_coll_metadata_ops(hid_t plist_id, hbool_t is_collective);
/**
- * \ingroup GACPL
+ * \ingroup GAPL
*
* \brief Retrieves metadata read mode setting
*
@@ -6132,6 +6152,8 @@ H5_DLL herr_t H5Pset_fill_value(hid_t plist_id, hid_t type_id, const void *value
*
* \return \herr_t
*
+ * \par_compr_note
+ *
* \details H5Pset_shuffle() sets the shuffle filter, #H5Z_FILTER_SHUFFLE,
* in the dataset creation property list \p plist_id. The shuffle
* filter de-interlaces a block of data by reordering the bytes.
@@ -6203,6 +6225,8 @@ H5_DLL herr_t H5Pset_layout(hid_t plist_id, H5D_layout_t layout);
*
* \return \herr_t
*
+ * \par_compr_note
+ *
* \details H5Pset_nbit() sets the N-Bit filter, #H5Z_FILTER_NBIT, in the
* dataset creation property list \p plist_id.
*
@@ -6296,6 +6320,8 @@ H5_DLL herr_t H5Pset_nbit(hid_t plist_id);
*
* \return \herr_t
*
+ * \par_compr_note
+ *
* \details H5Pset_scaleoffset() sets the scale-offset filter,
* #H5Z_FILTER_SCALEOFFSET, for a dataset.
*
@@ -6405,6 +6431,8 @@ H5_DLL herr_t H5Pset_scaleoffset(hid_t plist_id, H5Z_SO_scale_type_t scale_type,
*
* \return \herr_t
*
+ * \par_compr_note
+ *
* \details H5Pset_szip() sets an SZIP compression filter, #H5Z_FILTER_SZIP,
* for a dataset. SZIP is a compression method designed for use with
* scientific data.
@@ -9235,9 +9263,6 @@ H5_DLL herr_t H5Pset_mcdt_search_cb(hid_t plist_id, H5O_mcdt_search_cb_t func, v
* The #H5P_prp_cb2_t is as follows:
* \snippet this H5P_prp_cb2_t_snip
*
- *
- * \cpp_c_api_note
- *
*/
/* Function prototypes */
@@ -9351,8 +9376,7 @@ H5_DLL herr_t H5Pregister1(hid_t cls_id, const char *name, size_t size, void *de
*
* The #H5P_prp_cb2_t is as follows:
* \snippet this H5P_prp_cb2_t_snip
-
- * \cpp_c_api_note
+ *
*/
H5_DLL herr_t H5Pinsert1(hid_t plist_id, const char *name, size_t size, void *value,
H5P_prp_set_func_t prp_set, H5P_prp_get_func_t prp_get,
diff --git a/src/H5Rmodule.h b/src/H5Rmodule.h
index 2a34d56..fe28bb2 100644
--- a/src/H5Rmodule.h
+++ b/src/H5Rmodule.h
@@ -27,9 +27,32 @@
/**
* \defgroup H5R H5R
- * \brief Reference Interface
- * \details The HDF5 Reference Interface, H5R, provides a mechanism for managing
- * HDF5 referenced objects.
+ *
+ * Use the functions in this module to manage HDF5 references. Referents can
+ * be HDF5 objects, attributes, and selections on datasets a.k.a. dataset
+ * regions.
+ *
+ *
+ *
+ * | Create | Read |
|---|
+ *
+ * |
+ * \snippet{lineno} H5R_examples.c create
+ * |
+ *
+ * \snippet{lineno} H5R_examples.c read
+ * |
+ *
| Update | Delete |
|---|
+ *
+ * |
+ * \snippet{lineno} H5R_examples.c update
+ * |
+ *
+ * \snippet{lineno} H5R_examples.c delete
+ * |
+ *
+ *
+ *
*/
#endif /* H5Rmodule_H */
diff --git a/src/H5Rpublic.h b/src/H5Rpublic.h
index 348a7a2..9682bf2 100644
--- a/src/H5Rpublic.h
+++ b/src/H5Rpublic.h
@@ -53,7 +53,7 @@ typedef enum {
H5R_BADTYPE = (-1), /**< Invalid reference type */
H5R_OBJECT, /**< Object reference */
H5R_DATASET_REGION, /**< Dataset Region Reference */
- H5R_MAXTYPE /**< Highest type (Invalid as true type) */
+ H5R_MAXTYPE /**< Highest type (invalid) */
} H5R_type_t;
//!
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.
+ *
+ * | Create | Read |
|---|
+ *
+ * |
+ * \snippet{lineno} H5S_examples.c create
+ * |
+ *
+ * \snippet{lineno} H5S_examples.c read
+ * |
+ *
| Update | Delete |
|---|
+ *
+ * |
+ * \snippet{lineno} H5S_examples.c update
+ * |
+ *
+ * \snippet{lineno} H5S_examples.c delete
+ * |
+ *
+ *
*
*/
diff --git a/src/H5Spublic.h b/src/H5Spublic.h
index e3fe37e..376c3e4 100644
--- a/src/H5Spublic.h
+++ b/src/H5Spublic.h
@@ -21,75 +21,94 @@
#include "H5public.h"
#include "H5Ipublic.h"
-/* Define atomic datatypes */
-#define H5S_ALL 0 /* (hid_t) */
-#define H5S_UNLIMITED HSIZE_UNDEF
+/* Define special dataspaces for dataset I/O operations */
+#define H5S_ALL (hid_t)0
+#define H5S_UNLIMITED HSIZE_UNDEF /**< Value for 'unlimited' dimensions */
-/* Define user-level maximum number of dimensions */
+/**
+ * The maximum dataspace rank or number of dimensions
+ */
#define H5S_MAX_RANK 32
-/* Different types of dataspaces */
+/**
+ * Types of dataspaces
+ */
typedef enum H5S_class_t {
- H5S_NO_CLASS = -1, /*error */
- H5S_SCALAR = 0, /*scalar variable */
- H5S_SIMPLE = 1, /*simple dataspace */
- H5S_NULL = 2 /*null dataspace */
+ H5S_NO_CLASS = -1, /**< Error */
+ H5S_SCALAR = 0, /**< Singleton (scalar) */
+ H5S_SIMPLE = 1, /**< Regular grid */
+ H5S_NULL = 2 /**< Empty set */
} H5S_class_t;
-/* Different ways of combining selections */
+/**
+ * Different ways of combining selections
+ */
typedef enum H5S_seloper_t {
- H5S_SELECT_NOOP = -1, /* error */
- H5S_SELECT_SET = 0, /* Select "set" operation */
- H5S_SELECT_OR, /* Binary "or" operation for hyperslabs
+ H5S_SELECT_NOOP = -1, /**< Error */
+ H5S_SELECT_SET = 0, /**< Select "set" operation */
+ H5S_SELECT_OR, /**< Binary "or" operation for hyperslabs
* (add new selection to existing selection)
+ * \code
* Original region: AAAAAAAAAA
* New region: BBBBBBBBBB
* A or B: CCCCCCCCCCCCCCCC
+ * \endcode
*/
- H5S_SELECT_AND, /* Binary "and" operation for hyperslabs
+ H5S_SELECT_AND, /**< Binary "and" operation for hyperslabs
* (only leave overlapped regions in selection)
+ * \code
* Original region: AAAAAAAAAA
* New region: BBBBBBBBBB
* A and B: CCCC
+ * \endcode
*/
- H5S_SELECT_XOR, /* Binary "xor" operation for hyperslabs
+ H5S_SELECT_XOR, /**< Binary "xor" operation for hyperslabs
* (only leave non-overlapped regions in selection)
+ * \code
* Original region: AAAAAAAAAA
* New region: BBBBBBBBBB
* A xor B: CCCCCC CCCCCC
+ * \endcode
*/
- H5S_SELECT_NOTB, /* Binary "not" operation for hyperslabs
+ H5S_SELECT_NOTB, /**< Binary "not" operation for hyperslabs
* (only leave non-overlapped regions in original selection)
+ * \code
* Original region: AAAAAAAAAA
* New region: BBBBBBBBBB
* A not B: CCCCCC
+ * \endcode
*/
- H5S_SELECT_NOTA, /* Binary "not" operation for hyperslabs
+ H5S_SELECT_NOTA, /**< Binary "not" operation for hyperslabs
* (only leave non-overlapped regions in new selection)
+ * \code
* Original region: AAAAAAAAAA
* New region: BBBBBBBBBB
* B not A: CCCCCC
+ * \endcode
*/
- H5S_SELECT_APPEND, /* Append elements to end of point selection */
- H5S_SELECT_PREPEND, /* Prepend elements to beginning of point selection */
- H5S_SELECT_INVALID /* Invalid upper bound on selection operations */
+ H5S_SELECT_APPEND, /**< Append elements to end of point selection */
+ H5S_SELECT_PREPEND, /**< Prepend elements to beginning of point selection */
+ H5S_SELECT_INVALID /**< Invalid upper bound on selection operations */
} H5S_seloper_t;
-/* Enumerated type for the type of selection */
+/**
+ * Selection type
+ */
typedef enum {
- H5S_SEL_ERROR = -1, /* Error */
- H5S_SEL_NONE = 0, /* Nothing selected */
- H5S_SEL_POINTS = 1, /* Points / elements selected */
- H5S_SEL_HYPERSLABS = 2, /* Hyperslab selected */
- H5S_SEL_ALL = 3, /* Entire extent selected */
- H5S_SEL_N /*THIS MUST BE LAST */
+ H5S_SEL_ERROR = -1, /**< Error */
+ H5S_SEL_NONE = 0, /**< Empty selection */
+ H5S_SEL_POINTS = 1, /**< Set of points */
+ H5S_SEL_HYPERSLABS = 2, /**< Hyperslab */
+ H5S_SEL_ALL = 3, /**< Everything */
+ H5S_SEL_N /**< Sentinel \internal THIS MUST BE LAST */
} H5S_sel_type;
#ifdef __cplusplus
extern "C" {
#endif
-/* Operations on dataspaces */
+/* Operations on dataspaces, dataspace selections and selection iterators */
+
/**
* \ingroup H5S
*
@@ -243,31 +262,31 @@ H5_DLL hid_t H5Sdecode(const void *buf);
*
* \space_id{obj_id}
* \param[in,out] buf Buffer for the object to be encoded into;
- * If the provided buffer is NULL, only the size of
- * buffer needed is returned through \p nalloc.
+ * If the provided buffer is NULL, only the size
+ * of buffer needed is returned through \p nalloc.
* \param[in,out] nalloc The size of the allocated buffer
*
* \return \herr_t
*
* \details Given the data space identifier \p obj_id, H5Sencode() converts
- * a data space description into binary form in a buffer. Using
- * this binary form in the buffer, a data space object can be
- * reconstructed using H5Sdecode() to return a new object handle
- * (\p hid_t) for this data space.
+ * a data space description into binary form in a buffer. Using this
+ * binary form in the buffer, a data space object can be
+ * reconstructed with H5Sdecode() to return a new object handle
+ * (#hid_t) for this data space.
*
- * A preliminary H5Sencode() call can be made to find out the size
- * of the buffer needed. This value is returned as \p nalloc. That
- * value can then be assigned to \p nalloc for a second H5Sencode1()
- * call, which will retrieve the actual encoded object.
+ * A preliminary H5Sencode() call can be made to determine the
+ * size of the buffer needed. This value is returned in \p nalloc.
+ * That value can then be assigned to \p nalloc for a second
+ * H5Sencode()call, which will retrieve the actual encoded object.
*
- * If the library finds out \p nalloc is not big enough for the
+ * If the library determines that \p nalloc is not big enough for the
* object, it simply returns the size of the buffer needed through
* \p nalloc without encoding the provided buffer.
*
- * The types of data space addressed in this function are null,
- * scalar, and simple space. For a simple data space, the information
- * on the selection, for example, hyperslab selection, is also
- * encoded and decoded. A complex data space has not been
+ * The types of data space that are addressed in this function are
+ * null, scalar, and simple space. For a simple data space, the
+ * information on the selection, for example, hyperslab selection,
+ * is also encoded and decoded. A complex data space has not been
* implemented in the library.
*
* \since 1.8.0
diff --git a/src/H5Tmodule.h b/src/H5Tmodule.h
index c489edc..73424fb 100644
--- a/src/H5Tmodule.h
+++ b/src/H5Tmodule.h
@@ -29,10 +29,38 @@
#define H5_MY_PKG_ERR H5E_DATATYPE
#define H5_MY_PKG_INIT YES
-/**
- * \defgroup H5T H5T
- * \brief Datatype Interface
- * \todo Describe concisely what the functions in this module are about.
+/**\defgroup H5T H5T
+ *
+ * Use the functions in this module to manage HDF5 datatypes.
+ *
+ * HDF5 datatypes describe the element type of HDF5 datasets and attributes.
+ * There's a large set of predefined datatypes, but users may find it useful
+ * to define new datatypes through a process called \Emph{derivation}.
+ *
+ * The element type is automatically persisted as part of the HDF5 metadata of
+ * attributes and datasets. Additionally, datatype definitions can be persisted
+ * to HDF5 files and linked to groups as HDF5 datatype objects or so-called
+ * \Emph{committed datatypes}.
+ *
+ *
+ * | Create | Read |
|---|
+ *
+ * |
+ * \snippet{lineno} H5T_examples.c create
+ * |
+ *
+ * \snippet{lineno} H5T_examples.c read
+ * |
+ *
| Update | Delete |
|---|
+ *
+ * |
+ * \snippet{lineno} H5T_examples.c update
+ * |
+ *
+ * \snippet{lineno} H5T_examples.c delete
+ * |
+ *
+ *
*
* \defgroup ARRAY Array Datatypes
* \ingroup H5T
diff --git a/src/H5Tpublic.h b/src/H5Tpublic.h
index 9711178..10a4b06 100644
--- a/src/H5Tpublic.h
+++ b/src/H5Tpublic.h
@@ -196,9 +196,9 @@ typedef enum H5T_pers_t {
*/
//!
typedef enum H5T_direction_t {
- H5T_DIR_DEFAULT = 0, /**< default direction is inscendent */
- H5T_DIR_ASCEND = 1, /**< in inscendent order */
- H5T_DIR_DESCEND = 2 /**< in descendent order */
+ H5T_DIR_DEFAULT = 0, /**< default direction is ascending */
+ H5T_DIR_ASCEND = 1, /**< in ascending order */
+ H5T_DIR_DESCEND = 2 /**< in descending order */
} H5T_direction_t;
//!
@@ -245,7 +245,7 @@ typedef struct {
* Indicate that a string is variable length (null-terminated in C, instead of
* fixed length)
*/
-#define H5T_VARIABLE ((size_t)-1)
+#define H5T_VARIABLE ((size_t)(-1))
/* Opaque information */
/**
@@ -279,7 +279,7 @@ typedef herr_t (*H5T_conv_t)(hid_t src_id, hid_t dst_id, H5T_cdata_t *cdata, siz
* \returns Valid callback function return values are #H5T_CONV_ABORT,
* #H5T_CONV_UNHANDLED and #H5T_CONV_HANDLED.
*
- * \details If an exception like overflow happenes during conversion, this
+ * \details If an exception like overflow happens during conversion, this
* function is called if it's registered through H5Pset_type_conv_cb().
*
*/
@@ -3021,4 +3021,4 @@ H5_DLL int H5Tget_array_dims1(hid_t type_id, hsize_t dims[], int perm[]);
#ifdef __cplusplus
}
#endif
-#endif /* H5Tpublic_H */
\ No newline at end of file
+#endif /* H5Tpublic_H */
diff --git a/src/H5Zmodule.h b/src/H5Zmodule.h
index 76a2380..9312b72 100644
--- a/src/H5Zmodule.h
+++ b/src/H5Zmodule.h
@@ -29,57 +29,80 @@
#define H5_MY_PKG_ERR H5E_PLINE
#define H5_MY_PKG_INIT YES
-/**
- * \defgroup H5Z H5Z
+/**\defgroup H5Z H5Z
*
+ * Use the functions in this module to manage HDF5 filters.
*
- * \brief Filter and Compression Interface
+ * User-defined filters are created by registering a filter descriptor of
+ * type #H5Z_class_t with the library.
*
- * \details The functions in this module let you configure filters that process
- * data during I/O operation.
+ * Available filters can be read or examined at runtime.
*
- * HDF5 supports a filter pipeline that provides the capability for
- * standard and customized raw data processing during I/O operations.
- * HDF5 is distributed with a small set of standard filters such as
- * compression (gzip, SZIP, and a shuffling algorithm) and error
- * checking (Fletcher32 checksum). For further flexibility, the
- * library allows a user application to extend the pipeline through
- * the creation and registration of customized filters.
+ * It is conceivable that filters are stateful and that that state be
+ * updated at runtime.
*
- * The flexibility of the filter pipeline implementation enables the
- * definition of additional filters by a user application. A filter
- * \li is associated with a dataset when the dataset is created,
- * \li can be used only with chunked data (i.e., datasets stored in
- * the #H5D_CHUNKED storage layout), and
- * \li is applied independently to each chunk of the dataset.
+ * Filters are deleted by unregistering.
*
- * The HDF5 library does not support filters for contiguous datasets
- * because of the difficulty of implementing random access for partial
- * I/O. Compact dataset filters are not supported because it would not
- * produce significant results.
+ *
+ * | Create | Read |
|---|
+ *
+ * |
+ * \snippet{lineno} H5Z_examples.c filter
+ * \snippet{lineno} H5Z_examples.c create
+ * |
+ *
+ * \snippet{lineno} H5Z_examples.c read
+ * |
+ *
+ * | Update | Delete |
|---|
+ *
+ * |
+ * \snippet{lineno} H5Z_examples.c update
+ * |
+ *
+ * \snippet{lineno} H5Z_examples.c delete
+ * |
+ *
*
- * Filter identifiers for the filters distributed with the HDF5
- * Library are as follows:
- *
- * | #H5Z_FILTER_DEFLATE | The gzip compression, or
- * deflation, filter |
- * | #H5Z_FILTER_SZIP | The SZIP compression
- * filter |
- * | #H5Z_FILTER_NBIT | The N-bit compression
- * filter |
- * | #H5Z_FILTER_SCALEOFFSET | The scale-offset
- * compression filter |
- * | #H5Z_FILTER_SHUFFLE | The shuffle algorithm
- * filter |
- * | #H5Z_FILTER_FLETCHER32 | The Fletcher32 checksum,
- * or error checking, filter |
- *
- * 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:
+ *
+ * | #H5Z_FILTER_DEFLATE | The gzip compression, or
+ * deflation, filter |
+ * | #H5Z_FILTER_SZIP | The SZIP compression
+ * filter |
+ * | #H5Z_FILTER_NBIT | The N-bit compression
+ * filter |
+ * | #H5Z_FILTER_SCALEOFFSET | The scale-offset
+ * compression filter |
+ * | #H5Z_FILTER_SHUFFLE | The shuffle algorithm
+ * filter |
+ * | #H5Z_FILTER_FLETCHER32 | The Fletcher32 checksum,
+ * or error checking, filter |
+ *
+ * Custom filters that have been registered with the library will have
+ * additional unique identifiers.
+ *
+ * See \ref_dld_filters for more information on how an HDF5 application can
+ * apply a filter that is not registered with the HDF5 library.
*
* \defgroup H5ZPRE Predefined Filters
* \ingroup H5Z
diff --git a/src/H5module.h b/src/H5module.h
index 96bead8..f37dfc7 100644
--- a/src/H5module.h
+++ b/src/H5module.h
@@ -27,8 +27,31 @@
#define H5_MY_PKG_INIT NO
/**\defgroup H5 H5
- * \brief General Library Functions
- * \todo Describe concisely what the functions in this module are about.
+ *
+ * Use the functions in this module to manage the life cycle of HDF5 library
+ * instances.
+ *
+ *
+ * | Create | Read |
|---|
+ *
+ * |
+ * \snippet{lineno} H5_examples.c create
+ * |
+ *
+ * \snippet{lineno} H5_examples.c read
+ * |
+ *
| Update | Delete |
|---|
+ *
+ * |
+ * \snippet{lineno} H5_examples.c update
+ * |
+ *
+ * \snippet{lineno} H5_examples.c closing_shop
+ * \snippet{lineno} H5_examples.c delete
+ * |
+ *
+ *
+ *
*/
#endif /* H5module_H */
diff --git a/src/H5public.h b/src/H5public.h
index 6dffcf6..1c5496b 100644
--- a/src/H5public.h
+++ b/src/H5public.h
@@ -34,30 +34,37 @@
#ifdef H5_HAVE_FEATURES_H
#include
/* For setting POSIX, BSD, etc. compatibility */
#endif
-
-/* C library header files for things that appear in HDF5 public headers */
-#ifdef __cplusplus
-#define __STDC_FORMAT_MACROS
-#endif
-#include
-#include
-#include
-#include
-#include
-#include
-
-/* Unlike most sys/ headers, which are POSIX-only, sys/types.h is avaible
- * on Windows, though it doesn't necessarily contain all the POSIX types
- * we need for HDF5 (e.g. ssize_t).
- */
#ifdef H5_HAVE_SYS_TYPES_H
#include
#endif
+#ifdef H5_STDC_HEADERS
+#include /* For H5T_NATIVE_CHAR defn in H5Tpublic.h */
+#include /* For variadic functions in H5VLpublic.h */
+#endif
+#ifndef __cplusplus
+#ifdef H5_HAVE_STDINT_H
+#include /* For C9x types */
+#endif
+#else
+#ifdef H5_HAVE_STDINT_H_CXX
+#include /* For C9x types (when included from C++) */
+#endif
+#endif
+#ifdef H5_HAVE_INTTYPES_H
+#include /* C99/POSIX.1 header for uint64_t, PRIu64 */
+#endif
+#ifdef H5_HAVE_STDDEF_H
+#include
+#endif
#ifdef H5_HAVE_PARALLEL
/* Don't link against MPI C++ bindings */
+#ifndef MPICH_SKIP_MPICXX
#define MPICH_SKIP_MPICXX 1
-#define OMPI_SKIP_MPICXX 1
+#endif
+#ifndef OMPI_SKIP_MPICXX
+#define OMPI_SKIP_MPICXX 1
+#endif
#include
#ifndef MPI_FILE_NULL /* MPIO may be defined in mpi.h already */
#include
@@ -190,8 +197,9 @@ extern "C" {
* Status return values. Failed integer functions in HDF5 result almost
* always in a negative value (unsigned failing functions sometimes return
* zero for failure) while successful return is non-negative (often zero).
- * The negative failure value is most commonly -1, but don't bet on it. The
- * proper way to detect failure is something like:
+ * The negative failure value is most commonly -1, but don't bet on it.
+ *
+ * The proper way to detect failure is something like:
* \code
* if((dset = H5Dopen2(file, name)) < 0)
* fprintf(stderr, "unable to open the requested dataset\n");
@@ -215,10 +223,30 @@ typedef int herr_t;
* }
* \endcode
*/
+#ifdef H5_HAVE_STDBOOL_H
+#include
+#else /* H5_HAVE_STDBOOL_H */
+#ifndef __cplusplus
+#if defined(H5_SIZEOF_BOOL) && (H5_SIZEOF_BOOL != 0)
+#define bool _Bool
+#else
+#define bool unsigned int
+#endif
+#define true 1
+#define false 0
+#endif /* __cplusplus */
+#endif /* H5_HAVE_STDBOOL_H */
typedef bool hbool_t;
typedef int htri_t;
-/* Define the ssize_t type if it not is defined */
+/* The signed version of size_t
+ *
+ * ssize_t is POSIX and not defined in any C standard. It's used in some
+ * public HDF5 API calls so this work-around will define it if it's not
+ * present.
+ *
+ * Use of ssize_t should be discouraged in new code.
+ */
#if H5_SIZEOF_SSIZE_T == 0
/* Undefine this size, we will re-define it in one of the sections below */
#undef H5_SIZEOF_SSIZE_T
@@ -236,8 +264,10 @@ typedef long long ssize_t;
#endif
#endif
-/* int64_t type is used for creation order field for links. It may be
- * defined in Posix.1g, otherwise it is defined here.
+/**
+ * The size of file objects.
+ *
+ * \internal Defined as a (minimum) 64-bit integer type.
*/
#if H5_SIZEOF_INT64_T >= 8
#elif H5_SIZEOF_INT >= 8
@@ -282,9 +312,11 @@ typedef unsigned long long uint64_t;
#error "nothing appropriate for uint64_t"
#endif
-/*
- * The sizes of file objects have their own types defined here, use a minimum
- * 64-bit type.
+/**
+ * The size of file objects. Used when negative values are needed to indicate errors.
+ *
+ * \internal Defined as a (minimum) 64-bit integer type. Use of hssize_t
+ * should be discouraged in new code.
*/
#if H5_SIZEOF_LONG_LONG >= 8
H5_GCC_DIAG_OFF("long-long")
@@ -304,8 +336,10 @@ H5_GCC_DIAG_ON("long-long")
#error "nothing appropriate for hsize_t"
#endif
-/*
- * File addresses have their own types.
+/**
+ * The address of an object in the file.
+ *
+ * \internal Defined as a (minimum) 64-bit unsigned integer type.
*/
#if H5_SIZEOF_INT >= 8
typedef unsigned haddr_t;
@@ -386,9 +420,9 @@ typedef enum {
/* (Actually, any positive value will cause the iterator to stop and pass back
* that positive value to the function that called the iterator)
*/
-#define H5_ITER_ERROR (-1)
-#define H5_ITER_CONT (0)
-#define H5_ITER_STOP (1)
+#define H5_ITER_ERROR (-1) /**< Error, stop iteration */
+#define H5_ITER_CONT (0) /**< Continue iteration */
+#define H5_ITER_STOP (1) /**< Stop iteration, short-circuit success */
//!
/**
--
cgit v0.12