summaryrefslogtreecommitdiffstats
path: root/src/H5Pmodule.h
diff options
context:
space:
mode:
authorGerd Heber <gheber@hdfgroup.org>2021-09-01 21:09:27 (GMT)
committerGitHub <noreply@github.com>2021-09-01 21:09:27 (GMT)
commitcf25524474a4012a70cc2bdb6eaddc402b5ea136 (patch)
treecf7e30d16a602e5146500158696d429a146cb2c2 /src/H5Pmodule.h
parent01fe2549a36d7635b2cbe6f6a57cbcce29c1335b (diff)
downloadhdf5-cf25524474a4012a70cc2bdb6eaddc402b5ea136.zip
hdf5-cf25524474a4012a70cc2bdb6eaddc402b5ea136.tar.gz
hdf5-cf25524474a4012a70cc2bdb6eaddc402b5ea136.tar.bz2
A batch of life-cycle examples for different modules (#654)
* Create a tag file for permalinks. * Added DOXYGEN_TAG_FILE. * Added Doxygen life-cycle examples for different modules. Co-authored-by: github-actions <41898282+github-actions[bot]@users.noreply.github.com>
Diffstat (limited to 'src/H5Pmodule.h')
-rw-r--r--src/H5Pmodule.h164
1 files changed, 140 insertions, 24 deletions
diff --git a/src/H5Pmodule.h b/src/H5Pmodule.h
index 18f30c6..6e92e66 100644
--- a/src/H5Pmodule.h
+++ b/src/H5Pmodule.h
@@ -30,49 +30,165 @@
#define H5_MY_PKG_INIT YES
/**\defgroup H5P H5P
- * \brief Property List Interface
*
- * \details The HDF5 Property List Interface provides a mechanism to take
- * advantage of more powerful or unusual features in HDF5.
+ * Use the functions in this module to manage HDF5 property lists and property
+ * list classes. HDF5 property lists are the main vehicle to configure the
+ * behavior of HDF5 API functions.
*
- * HDF5 objects have properties or characteristics associated with
- * them, and there are default properties that handle the most
- * common needs. These default properties can be modified using the
- * HDF5 Property List Interface. For example, the data storage
- * layout property of a dataset is contiguous by default. For better
- * performance, the layout can be modified to be chunked or chunked
- * and compressed.
+ * Typically, property lists are created by instantiating one of the built-in
+ * or user-defined property list classes. After adding suitable properties,
+ * property lists are used when opening or creating HDF5 items, or when reading
+ * or writing data. Property lists can be modified by adding or changing
+ * properties. Property lists are deleted by closing the associated handles.
*
- * \todo Describe concisely what the functions in this module are about.
+ * <table>
+ * <tr><th>Create</th><th>Read</th></tr>
+ * <tr valign="top">
+ * <td>
+ * \snippet{lineno} H5P_examples.c create
+ * </td>
+ * <td>
+ * \snippet{lineno} H5P_examples.c read
+ * </td>
+ * <tr><th>Update</th><th>Delete</th></tr>
+ * <tr valign="top">
+ * <td>
+ * \snippet{lineno} H5P_examples.c update
+ * </td>
+ * <td>
+ * \snippet{lineno} H5P_examples.c delete
+ * </td>
+ * </tr>
+ * </table>
*
- * \defgroup GPLO General Property List Operations
+ * \defgroup ALCAPL Attribute and Link Creation Properties
* \ingroup H5P
- * \defgroup GPLOA General Property List Operations (Advanced)
+ * Currently, there are only two creation properties that you can use to control
+ * the creation of HDF5 attributes and links. The first creation property, the
+ * choice of a character encoding, applies to both attributes and links.
+ * The second creation property applies to links only, and advises the library
+ * to automatically create missing intermediate groups when creating new objects.
+ *
+ * \defgroup DAPL Dataset Access Properties
* \ingroup H5P
- * \defgroup FCPL File Creation Properties
+ * Use dataset access properties to modify the default behavior of the HDF5
+ * library when accessing datasets. The properties include adjusting the size
+ * of the chunk cache, providing prefixes for external content and virtual
+ * dataset file paths, and controlling flush behavior, etc. These properties
+ * are \Emph{not} persisted with datasets, and can be adjusted at runtime before
+ * a dataset is created or opened.
+ *
+ * \defgroup DCPL Dataset Creation Properties
+ * \ingroup H5P
+ * Use dataset creation properties to control aspects of dataset creation such
+ * as fill time, storage layout, compression methods, etc.
+ * Unlike dataset access and transfer properties, creation properties \Emph{are}
+ * stored with the dataset, and cannot be changed once a dataset has been
+ * created.
+ *
+ * \defgroup DXPL Dataset Transfer Properties
* \ingroup H5P
+ * Use dataset transfer properties to customize certain aspects of reading
+ * and writing datasets such as transformations, MPI-IO I/O mode, error
+ * detection, etc. These properties are \Emph{not} persisted with datasets,
+ * and can be adjusted at runtime before a dataset is read or written.
+ *
* \defgroup FAPL File Access Properties
* \ingroup H5P
- * \defgroup GCPL Group Creation Properties
+ * Use file access properties to modify the default behavior of the HDF5
+ * library when accessing files. The properties include selecting a virtual
+ * file driver (VFD), configuring the metadata cache (MDC), control
+ * file locking, etc. These properties are \Emph{not} persisted with files, and
+ * can be adjusted at runtime before a file is created or opened.
+ *
+ * \defgroup FCPL File Creation Properties
* \ingroup H5P
- * \defgroup ALCAPL Attribute and Link Creation Properties
+ * Use file creation properties to control aspects of file creation such
+ * as setting a file space management strategy or creating a user block.
+ * Unlike file access properties, creation properties \Emph{are}
+ * stored with the file, and cannot be changed once a file has been
+ * created.
+ *
+ * \defgroup GAPL General Access Properties
* \ingroup H5P
- * \defgroup LAPL Link Access Properties
+ * \todo Should this be as standalone page?
+ *
+ * \defgroup GCPL Group Creation Properties
* \ingroup H5P
- * \defgroup DCPL Dataset Creation Properties
+ * Use group creation properties to control aspects of group creation such
+ * as storage layout, compression, and link creation order tracking.
+ * Unlike file access properties, creation properties \Emph{are}
+ * stored with the group, and cannot be changed once a group has been
+ * created.
+ *
+ * \defgroup GPLO General Property List Operations
* \ingroup H5P
- * \defgroup DAPL Dataset Access Properties
+ *
+ * Use the functions in this module to manage HDF5 property lists.
+ *
+ * <table>
+ * <tr><th>Create</th><th>Read</th></tr>
+ * <tr valign="top">
+ * <td>
+ * \snippet{lineno} H5P_examples.c create
+ * </td>
+ * <td>
+ * \snippet{lineno} H5P_examples.c read
+ * </td>
+ * <tr><th>Update</th><th>Delete</th></tr>
+ * <tr valign="top">
+ * <td>
+ * \snippet{lineno} H5P_examples.c update
+ * </td>
+ * <td>
+ * \snippet{lineno} H5P_examples.c delete
+ * </td>
+ * </tr>
+ * </table>
+ *
+ * \defgroup GPLOA General Property List Operations (Advanced)
* \ingroup H5P
- * \defgroup DXPL Dataset Transfer Properties
+ *
+ * You can create and customize user-defined property list classes using the
+ * functions described below. Arbitrary user-defined properties can also
+ * be inserted into existing property lists as so-called temporary properties.
+ *
+ * <table>
+ * <tr><th>Create</th><th>Read</th></tr>
+ *
+ * <tr valign="top">
+ * <td>
+ * \snippet{lineno} H5P_examples.c create_class
+ * </td>
+ * <td>
+ * \snippet{lineno} H5P_examples.c read_class
+ * </td>
+ * <tr><th>Update</th><th>Delete</th></tr>
+ * <tr valign="top">
+ * <td>
+ * \snippet{lineno} H5P_examples.c update_class
+ * </td>
+ * <td>
+ * \snippet{lineno} H5P_examples.c delete_class
+ * </td>
+ * </tr>
+ * </table>
+ *
+ * \defgroup LAPL Link Access Properties
* \ingroup H5P
+ *
+ *
+ * \defgroup MAPL Map Access Properties
+ * \ingroup H5P
+
* \defgroup OCPL Object Creation Properties
* \ingroup H5P
+ *
+ *
* \defgroup OCPPL Object Copy Properties
* \ingroup H5P
- * \defgroup GACPL General Access Properties
- * \ingroup H5P
- * \defgroup MAPL Map Access Properties
- * \ingroup H5P
+ *
+ *
*/
#endif /* H5Pmodule_H */