From e56b0a3d508b73746c9676b56b275d0e7a486b7b Mon Sep 17 00:00:00 2001 From: Gerd Heber Date: Thu, 13 Jan 2022 22:11:39 -0600 Subject: Documentation fixes right in time for the holidays (#1321) * Sketch of the H5S life cycle. * Committing clang-format changes * Fix H5S_UNLIMITED snafu. * Updated RM template and RM page. * Added H5S life cycle. * Committing clang-format changes * Added H5T life cycle. * Committing clang-format changes * Cleaner layout (?) * Cleaned the H5F life cycle. Called out unfinished biz. * Committing clang-format changes * Remaining life cycle skeletons. * Committing clang-format changes * Committing clang-format changes * Added H5Z life cycle. * Committing clang-format changes * Added H5G life cycle. * Committing clang-format changes * H5 and H5I life cycle updates. * Committing clang-format changes * Added H5PL life cycle. * Committing clang-format changes * Added H5L life cycle. * Committing clang-format changes * Fix for Chris' comment. * Add a variable for Doxygen pre-processor definitions. * Forgot to add the H5M API. * Clarify the H5Z life cycle. * Committing clang-format changes * Add H5Zdevelop.h to Doxygen.in. Added H5I life cycle. * Committing clang-format changes * Clarified introduction and fixed missing label declaration. * Added H5O life cycle. * Committing clang-format changes * H5O cleanup, part 1. * Committing clang-format changes * Cleaned up some of the endless repetition in H5O. * Committing clang-format changes * Cookbook & RFC draft layouts. * Updated manifest. * Updated the manifest, the example paths, and sketched the 1st recipe. * Committing clang-format changes * Outlined two more recipes. * Committing clang-format changes * More recipes and RFCs. * Committing clang-format changes * Draft of templatized RFC references. * Another batch of RFC changes. * Another batch of RFCs. * Fixed reference. * RFCs in reverse chronological order. * First cut of RFCs. * Fixed reference. * Updated recipes. * Updated recipes. * More RFCs. * Updated D*PL comments. * Added H5P descriptions. * Committing clang-format changes * H5R life-cycle snapshot. * Committing clang-format changes * H5R life-cycle. Added line numbers to life-cycle examples. * Committing clang-format changes * Fixed formatting for H5Dchunk_iter(). * Added comment on collective mode requirement w/ compression. * Simplified API compat. macro dox. * More API vers. updates. * Hide the async macro entrails. * Latest VFD SWMR RFC. * Create a tag file for permalinks. * Added TODOs for metadoc. * Removed duplication. * Revised RM landing page. * Trimmed more duplication. * Committing clang-format changes * Revised H5D. * Committing clang-format changes * Updated survey link. * Added Doxygen RM entry template link. * Added the "Multi-Thread HDF5" RFC. * Added DOXYGEN_TAG_FILE. * Added selection I/O RFC. * Added the VFD Sub-filing RFC. * Updated meta-documentation and added two old presentations. * Added a few more RFCs (4). * Fixed MANIFEST. * Updated meta-documentation. * Added Filters technical note. * Fixed MANIFEST. * Restore the path stripper. * Experimental full-text search via Google. * Better full-text search integration. * Whoops. Forgot this one. * Oh boy. * Make CMake happy. * Added "Debugging HDF5 Applications" technical note. * Another batch of RFCs. * Fixes for #1221. * Updated overview. * Fixed image dependencies. * CMake updates. * Fixed SET. * Better? * Update doxygen/dox/Overview.dox * Fixed documentation errors. Added missing version info. * Callback documentation updates. * Fixed indexing errors in the outline. * Doxygen-ized the HDF5 glossary. * Fix a few minor typos . Co-authored-by: github-actions <41898282+github-actions[bot]@users.noreply.github.com> Co-authored-by: Larry Knox --- MANIFEST | 1 + doxygen/dox/About.dox | 2 - doxygen/dox/Glossary.dox | 565 ++++++++++++++++++++++++++++++++++++ doxygen/dox/Overview.dox | 9 +- doxygen/examples/H5.format.1.0.html | 14 +- doxygen/examples/H5.format.1.1.html | 14 +- doxygen/hdf5doxy_layout.xml | 2 +- src/H5Dpublic.h | 9 +- src/H5ESpublic.h | 13 +- src/H5FDmpio.h | 6 +- src/H5Fpublic.h | 4 +- src/H5Pmodule.h | 3 +- src/H5Ppublic.h | 281 +++++++++--------- 13 files changed, 759 insertions(+), 164 deletions(-) create mode 100644 doxygen/dox/Glossary.dox diff --git a/MANIFEST b/MANIFEST index 1fff5cc..c272a13 100644 --- a/MANIFEST +++ b/MANIFEST @@ -223,6 +223,7 @@ ./doxygen/dox/DDLBNF112.dox ./doxygen/dox/FTS.dox ./doxygen/dox/GettingStarted.dox +./doxygen/dox/Glossary.dox ./doxygen/dox/H5AC_cache_config_t.dox ./doxygen/dox/MetadataCachingInHDF5.dox ./doxygen/dox/Overview.dox diff --git a/doxygen/dox/About.dox b/doxygen/dox/About.dox index 0b21fcc..a8b31d7 100644 --- a/doxygen/dox/About.dox +++ b/doxygen/dox/About.dox @@ -124,6 +124,4 @@ version. Talk to your friendly IT-team if you need write access, or you need someone to push an updated version for you! -\todo Make the publication a GitHub action! - */ \ No newline at end of file diff --git a/doxygen/dox/Glossary.dox b/doxygen/dox/Glossary.dox new file mode 100644 index 0000000..9ccd27d --- /dev/null +++ b/doxygen/dox/Glossary.dox @@ -0,0 +1,565 @@ +/** \page GLS Glossary + +\section GLS_A A + +
+
Array datatype
+
A family of HDF5 datatypes whose elements are arrays of a fixed rank (≤ + 32) and fixed finite extent. All array elements must be of the same HDF5 + datatype.
+
+ +
+
Array variable
+

A variable that can store (logically) dense, rectilinear, multidimensional + arrays of elements of a given HDF5 datatype.

+

The combination of array rank (dimensionality) and extent is called an + array variable's shape. This includes the degenerate array shapes of a + singleton (scalar) and the empty array (null).

+

The array element datatype is sometimes referred to as the array + variable's type, which is not entirely accurate because the array variable's + type is 'array of element type' rather than 'element type'.

+

In HDF5, there are two kinds of array variables, attributes and datasets, + and the distinction is functional (i.e., how they can be used) rather than + conceptual. Attributes are commonly used for descriptive "light-weight" + HDF5 object metadata while datasets are HDF5 objects used to store + "heavy-weight" problem-sized data.

+
+
+ +
+
Attribute
+

A named array variable that is associated with an HDF5 object, its + owner or attributee, and used to represent application domain-specific + metadata of the object. Intuitively, the set of an object's attributes can + be thought of as its key-value pair collection. Attribute names (keys) can + be arbitrary Unicode strings, but must be unique per object, i.e., an + object can have at most one attribute with a given name.

+

A scalar attribute is an attribute backed by a singleton array + variable. A null attribute is attribute backed by an empty array + variable.

+
+
+ +\section GLS_B B + +
+
Bitfield datatype
+
A family of HDF5 datatypes whose elements are fixed-width bit fields.
+
+ +\section GLS_C C + +
+
Chunked layout
+
+

A dataset storage layout where the dataset elements are partitioned into + fixed-size multidimensional chunks or tiles. Chunked layout is mandatory + for datasets with one or more dimensions of indefinite (infinite) extent + or where compression or other filters are applied to the dataset elements.

+

Chunked layout may improve I/O performance for certain access patterns.

+
+
+ +
+
Committed datatype
+
An immutable kind of HDF5 object that is used to store an HDF5 datatype + definition, which can be referenced by multiple array variables. When linked + to an HDF5 group, a committed datatype can be located by an HDF5 path name, + and is sometimes called a named datatype.
+
+ +
+
Compact layout
+
+
+ +
+
Compound datatype
+
+

A family of HDF5 datatypes whose elements are records with named fields + of other HDF5 datatypes. Currently, on ASCII field names are supported.

+

Similar to a struct in C or a COMMON block in + Fortran.

+
+
+ +
+
Contiguous layout
+
A dataset storage layout where the dataset elements are physically stored + in an HDF5 file as a contiguous block of bytes.
+
+ +\section GLS_D D + +
+
Dataset
+
+

A kind of HDF5 object, a linked array variable. which can be located in + an HDF5 file through a path name. Datasets are commonly used to store + "heavy-weight" problem-sized data.

+

The HDF5 library offers a lot of features aimed at optimized dataset + access and storage, including compression and partial I/O.

+
+
+ +
+
Dataspace
+
The shape of an array variable. With the exception of degenerate cases + (empty set, singleton), this is a rectilinear lattice or grid of a certain + rank (dimensionality) and extent.
+
+ +
+
Datatype
+
+

An HDF5 datatype consists of an abstract data type (a set of elements) + and a bit-level representation of these elements in storage such as an HDF5 + file or memory.

+

The HDF5 library comes with a large set of predefined datatypes and + offers mechanisms for creating user-defined datatypes.

+

The ten major families or classes of HDF5 datatypes are:

+
    +
  • Integer datatypes
    • +
  • Floating-point number datatypes
    • +
  • String datatypes
    • +
  • Bitfield datatypes
    • +
  • Opaque datatypes
    • +
  • Compound datatypes
    • +
  • Reference datatypes
    • +
  • Enumerated datatypes
    • +
  • Variable-length sequence datatypes
    • +
  • Array datatypes
    • +
+
+
+ +\section GLS_E E + +
+
Enumeration datatype
+
A family of HDF5 datatypes whose elements represent named integer values + called members or enumerators. Currently, only ASCII names are supported.
+
+ +
+
External layout
+
A form of contiguous layout where a dataset's elements are physically + stored in unformatted binary files outside the HDF5 file.
+
+ +
+
External link
+
An HDF5 link whose destination is specified as a pair of an HDF5 file name +and an HDF5 path name in that file.
+
+ +\section GLS_F F + +
+
Field
+
See compound datatype.
+
+ +
+
File
+
+
    +
  1. A byte stream (in a storage context such as a file system or in + memory) formatted according to the HDF5 File Format Specification.
    2. +
  2. A (logical) container for HDF5 objects.
    3. +
+
+
+ +
+
File format
+
+
+ +
+
Fill value
+
+
+ +
+
Filter
+
+
+ +\section GLS_G G + +
+
Group
+
+

A kind of HDF5 object that stores a collection of HDF5 links. Each HDF5 + file contains at least one group, it's root group.

+

Among the destinations of an HDF5 group's links may be other HDF5 groups + (including the group itself!). This ability is sometimes referred to as the + closure property of groups. It is the basis for creating hierarchical or + more general graph-like structures.

+
+
+ +\section GLS_H H + +
+
Hard link
+
An HDF5 link whose destination is specified (internally) as the address of + an HDF5 object in the same HDF5 file.
+
+ +
+
Hierarchy
+
See group.
+
+ +
+
Hyperslab
+
+

A regular multidimensional pattern described by four vectors whose length + equals the rank of the pattern.

+
    +
  1. start - the offset where the first block of the hyperslab begins
    2. +
  2. stride - the offset between pattern blocks
    3. +
  3. count - the number of blocks
    4. +
  4. block - the extent of an individual pattern block
    5. +
+

For example, the black squares on a (two-dimensional) chessboard with + origin at (0,0) can be represented as the union of two + hyperslabs representing the even (0,2,4,6) and + odd (1,3,5,7) rows, respectively.

+ +

The hyperslab parameters for the even rows are: start (0,0), + stride (2,2), count (4,4), block + (1,1). Likewise the parameters for the odd rows are: start + (1,1), stride (2,2), count + (4,4), block (1,1).

+
+
+ +\section GLS_I I + +
+
Identifier
+
An opaque, transient handle used by the HDF5 library to manipulate + in-memory representations of HDF5 items.
+
+ +\section GLS_L L + +
+
Library
+
+
+ +
+
Link
+
+

A named, uni-directional association between a source and a + destination. In HDF5, the source is always the HDF5 group that hosts the + link in its link collection.

+

There are several ways to specify a link's destination:

+
    +
  • The address of an HDF5 object in the same HDF5 file; so-called hard + link.
    • +
  • A path name in the same or a different file; so-called soft or + external link.
    • +
  • User-defined
    • +
+

A link name can be any Unicode string that does not contain slashes + ("/") or consists of a single dot character + ("."). A link name must be unique in a group's link + collection.

+
+
+ +\section GLS_M M + +
+
Metadata
+
Data that in a given context has a descriptive or documentation function + for other data. Typically, the metadata is small compared to the data it + describes.
+
+ +
+
Member
+
+

A link destination is sometimes referred to as a member of the link's + source (group). This way of speaking invites confusion: A destination (e.g., + object) can be the destination of multiple links in the same (!) or + different groups. It would then be a "member" of a given group with + multiplicity greater than one and be a member of multiple groups.

+

It is the link that is a member of the group's link collection and not + the link destination.

+
+
+ +\section GLS_N N + +
+
Name
+
+

A Unicode string that depending on the item it names might be subject to + certain character restrictions, such as ASCII-encoded only. In HDF5, the + user might encounter the following names:

+
    +
  • A link name
    • +
  • A path name
    • +
  • An attribute name
    • +
  • A field name (compound datatypes)
    • +
  • A constant name (enumeration datatypes)
    • +
  • A tag name (opaque datatypes)
    • +
  • A file name
    • +
+
+
+ + +
+
Named datatype
+
See committed datatype.
+
+ +
+
Null dataspace
+
A shape which represents the empty set. Array variables with this shape + cannot store any values.
+
+ +\section GLS_O O + +
+
Object
+
An HDF5 group, dataset or named datatype; an HDF5 item that can be linked + to zero or more groups and decorated with zero or more HDF5 attributes.
+
+ +
+
Object reference
+
+
    +
  1. A datatype for representing references to objects in a file.
    2. +
  2. A value of the object reference datatype.
    3. +
+
+
+ +
+
Opaque datatype
+
A family of HDF5 datatypes whose elements are byte sequences of a given + fixed length. An opaque datatype can be tagged with a sequence of up to 256 + ASCII characters, e.g., MIME code.
+
+ +\section GLS_P P + +
+
Path name
+
A Unicode string that is the concatenation of link names separated by + slashes ('/'). In HDF5, path names are used to locate and refer + to HDF5 objects.
+
+ +
+
Plugin
+
An HDF5 library feature or capability that can be added dynamically at + application run time rather than library compilation time. Plugins are + usually implemented as shared libraries, and their discovery and loading + behavior can be controlled programmatically or through environment + variables. +
+
+ +
+
Point selection
+
A dataspace selection that consists of a set of points (coordinates) in + the same dataspace.
+
+ +
+
Property list
+
+

An HDF5 API construct, a means of customizing the behavior of the HDF5 + library when creating, accessing or modifying HDF5 items.

+

While the default property settings are sufficient in many cases, certain + HDF5 features, such as compression, can be reasonably controlled only by the + user who has to provide the desired settings via property lists.

+
+
+ +\section GLS_R R + +
+
Rank
+
The number of dimensions of a non-null dataspace.
+
+ +
+
Reference
+
+
    +
  1. An HDF5 object reference
    2. +
  2. An HDF5 dataset region reference
    3. +
+
+
+ +
+
Reference datatype
+
+
    +
  1. An HDF5 datatype whose elements represent references to HDF5 + objects.
    2. +
  2. An HDF5 datatype whose elements represent references to regions of an + HDF5 dataset.
    3. +
+
+
+ +
+
Region reference
+
See dataset region reference.
+
+ +
+
Root group
+
+

An HDF5 group that is present in all HDF5 files and that acts as the + entry or base point for all other data stored in an HDF5 file.

+

The root group is "the mother of all objects" in an HDF5 file in the + sense that all objects (and their attributes) can be discovered, + beginning at the root group, by combinations of the following + operations:

+
    +
  • Link traversal
    • +
  • De-referencing of object references
    • +
+

This discovery is portable and robust with respect to file-internal + storage reorganization.

+
+
+ +\section GLS_S S + +
+
Scalar dataspace
+
A kind of HDF5 dataspace that has the shape of a singleton, i.e., a set + containing a single element. Array variables with this shape store exactly one + element.
+
+ +
+
Selection
+
+
    +
  1. A subset of points of an HDF5 dataspace. The subset might be a point + selection or a combination (union, intersection, etc.) of hyperslabs.
    2. +
  2. A subset of dataset elements associated with a dataspace selection as + described under 1.
    3. +
+
+
+ +
+
Serialization
+
+
    +
  1. The flattening of an N-dimensional array into a 1-dimensional + array.
    2. +
  2. The encoding of a complex data item as a linear byte stream.
    3. +
+
+
+ +
+
Soft link
+
A kind of HDF5 link in which the link destination is specified as an HDF5 + path name. The path name may or may not refer to an actual object.
+
+ +
+
Storage layout
+
The storage arrangement for dataset elements, links in a group's link + collection, or attributes in an object's attribute collection.
+
+ +
+
String datatype
+
+
+ +
+
Super block
+
An HDF5 file format primitive; a block of data which contains information + required to access HDF5 files in a portable manner on multiple platforms. The + super block contains information such as version numbers, the size of offsets + and lengths, and the location of the root group.
+
+ +
+
SWMR
+
Single Writer Multiple Reader, a file access mode in which a single + process is permitted to write data to an HDF5 file while other processes are + permitted to read data from the same file without the need of inter-process + communication or synchronization.
+
+ +
+
Symbolic link
+
An external link or a soft link.
+
+ +\section GLS_U U + +
+
User block
+
An HDF5 file format primitive that allows one to set aside a fixed-size + (at least 512 bytes or any power of 2 thereafter) contiguous range of bytes at + the beginning of an HDF5 file for application purposes which will be + skipped/ignored by the HDF5 library.
+
+ +
+
UTF-8
+
+

A variable-length (1-4 bytes per code point) encoding of the Unicode set + of code points. This is the encoding supported by HDF5 to represent Unicode + strings.

+

The ASCII encoding is a proper subset of UTF-8.

+
+
+ +\section GLS_V V + +
+
Variable-length (sequence) datatype
+
A family of HDF5 datatypes whose elements are variable-length sequences of + a given datatype.
+
+ +
+
Virtual Dataset (VDS)
+
An HDF5 dataset with virtual storage layout. A dataset whose elements are + partially or entirely stored physically in other datasets.
+
+ +
+
Virtual File Driver (VFD)
+
+
+ + +
+
Virtual layout
+
+
+ + +
+
Virtual Object Layer (VOL)
+
+
+ +*/ diff --git a/doxygen/dox/Overview.dox b/doxygen/dox/Overview.dox index e9c52c2..040769c 100644 --- a/doxygen/dox/Overview.dox +++ b/doxygen/dox/Overview.dox @@ -1,9 +1,8 @@ /** \mainpage notitle -This is the documentation set for HDF5. You can -download it as a tgz archive for offline reading. -This documentation includes specifications and documentation +This is the documentation set for HDF5. +It includes specifications and documentation of software and tools developed and maintained by The HDF Group. It is impractical to document the entire HDF5 ecosystem in one place, and you should also consult the documentation @@ -38,8 +37,8 @@ documents cover a mix of tasks, concepts, and reference, to help a specific You can download it as a tgz archive for offline reading. \par History - A snapshot (April 2017) of the pre-Doxygen HDF5 documentation can be found - here. + A snapshot (~April 2017) of the pre-Doxygen HDF5 documentation can be found + here. \par ToDo List There is plenty of unfinished business. diff --git a/doxygen/examples/H5.format.1.0.html b/doxygen/examples/H5.format.1.0.html index cdc19ec7..d2b6610 100644 --- a/doxygen/examples/H5.format.1.0.html +++ b/doxygen/examples/H5.format.1.0.html @@ -10,12 +10,12 @@
-
    +
    1. Introduction
    2. Disk Format Level 0 - File Signature and Super Block
    3. Disk Format Level 1 - File Infrastructure -
        +
        1. Disk Format Level 1A - B-link Trees and B-tree Nodes
        2. Disk Format Level 1B - Group
        3. Disk Format Level 1C - Group Entry @@ -26,9 +26,9 @@
        4. Disk Format Level 2 - Data Objects -
            +
            1. Disk Format Level 2a - Data Object Headers -
                +
                1. Name: NIL
                2. Name: Simple Dataspace
                3. Name: Data Storage - External Data Files
                4. Name: Data Storage - Layout diff --git a/doxygen/examples/H5.format.1.1.html b/doxygen/examples/H5.format.1.1.html index 9894fad..b91ac90 100644 --- a/doxygen/examples/H5.format.1.1.html +++ b/doxygen/examples/H5.format.1.1.html @@ -36,18 +36,18 @@ TABLE.list TD { border:none; }
                  -
                    +
                    1. Introduction
                    2. Disk Format Level 0 - File Metadata -
                        +
                        1. Disk Format Level 0A - File Signature and Super Block
                        2. Disk Format Level 0B - File Driver Info
                      1. Disk Format Level 1 - File Infrastructure -
                          +
                          1. Disk Format Level 1A - B-link Trees and B-tree Nodes
                          2. Disk Format Level 1B - Group
                          3. Disk Format Level 1C - Group Entry @@ -58,9 +58,9 @@ TABLE.list TD { border:none; }
                          4. Disk Format Level 2 - Data Objects -
                              +
                              1. Disk Format Level 2a - Data Object Headers -
                                  +
                                  1. Name: NIL
                                  2. Name: Simple Dataspace @@ -73,13 +73,13 @@ TABLE.list TD { border:none; }
                  		   -
                    +
                    1. Disk Format Level 2 - Data Objects (Continued)
                      1. Disk Format Level 2a - Data Object Headers(Continued) -
                          +
                          1. Name: Reserved - not assigned yet
                          2. Name: Data Storage - External Data Files diff --git a/doxygen/hdf5doxy_layout.xml b/doxygen/hdf5doxy_layout.xml index 6efa690..24642b5 100644 --- a/doxygen/hdf5doxy_layout.xml +++ b/doxygen/hdf5doxy_layout.xml @@ -7,7 +7,7 @@ - + diff --git a/src/H5Dpublic.h b/src/H5Dpublic.h index 75f4b95..10e297f 100644 --- a/src/H5Dpublic.h +++ b/src/H5Dpublic.h @@ -77,7 +77,7 @@ typedef enum H5D_chunk_index_t { */ typedef enum H5D_alloc_time_t { H5D_ALLOC_TIME_ERROR = -1, /**< Error */ - H5D_ALLOC_TIME_DEFAULT = 0, /**< \todo Define this! */ + H5D_ALLOC_TIME_DEFAULT = 0, /**< Default (layout dependent) */ 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) */ @@ -127,8 +127,8 @@ typedef enum H5D_fill_value_t { */ typedef enum H5D_vds_view_t { H5D_VDS_ERROR = -1, /**< Error */ - H5D_VDS_FIRST_MISSING = 0, /**< \todo Define this! */ - H5D_VDS_LAST_AVAILABLE = 1 /**< \todo Define this! */ + H5D_VDS_FIRST_MISSING = 0, /**< Include all data before the first missing mapped data */ + H5D_VDS_LAST_AVAILABLE = 1 /**< Include all available mapped data */ } H5D_vds_view_t; //! @@ -682,8 +682,7 @@ H5_DLL herr_t H5Dget_chunk_info_by_coord(hid_t dset_id, const hsize_t *offset, u * Iterate over all chunked datasets and chunks in a file. * \snippet H5D_examples.c H5Ovisit_cb * - * \version 1.?.? - * \todo When was this function introduced? + * \since 1.13.0 * */ H5_DLL herr_t H5Dchunk_iter(hid_t dset_id, hid_t dxpl_id, H5D_chunk_iter_op_t cb, void *op_data); diff --git a/src/H5ESpublic.h b/src/H5ESpublic.h index c8696b3..c8d1c7b 100644 --- a/src/H5ESpublic.h +++ b/src/H5ESpublic.h @@ -200,7 +200,18 @@ H5_DLL herr_t H5ESget_count(hid_t es_id, size_t *count); /** * \ingroup H5ES * - * \todo Fill in the blanks! + * \brief Retrieves the next operation counter to be assigned in an event set + * + * \es_id + * \param[out] counter The next counter value to be assigned to an event + * \returns \herr_t + * + * \details H5ESget_op_counter() retrieves the \p counter that will be assigned + * to the next operation inserted into the event set \p es_id. + * + * \note This is designed for wrapper libraries mainly, to use as a mechanism + * for matching operations inserted into the event set with possible + * errors that occur. * * \since 1.13.0 * diff --git a/src/H5FDmpio.h b/src/H5FDmpio.h index 00dea1b..5ce98ca 100644 --- a/src/H5FDmpio.h +++ b/src/H5FDmpio.h @@ -223,7 +223,7 @@ H5_DLL herr_t H5Pset_dxpl_mpio_collective_opt(hid_t dxpl_id, H5FD_mpio_collectiv * * Use of this function is optional. * - * \todo Add missing version information + * \since 1.8.0 * */ H5_DLL herr_t H5Pset_dxpl_mpio_chunk_opt(hid_t dxpl_id, H5FD_mpio_chunk_opt_t opt_mode); @@ -247,7 +247,7 @@ H5_DLL herr_t H5Pset_dxpl_mpio_chunk_opt(hid_t dxpl_id, H5FD_mpio_chunk_opt_t op * otherwise, a separate I/O process will be invoked for each chunk * (multi-chunk I/O). * - * \todo Add missing version information + * \since 1.8.0 * */ H5_DLL herr_t H5Pset_dxpl_mpio_chunk_opt_num(hid_t dxpl_id, unsigned num_chunk_per_proc); @@ -272,7 +272,7 @@ H5_DLL herr_t H5Pset_dxpl_mpio_chunk_opt_num(hid_t dxpl_id, unsigned num_chunk_p * percent_proc_per_chunk, the library will do collective I/O for this * chunk; otherwise, independent I/O will be done for the chunk. * - * \todo Add missing version information + * \since 1.8.0 * */ H5_DLL herr_t H5Pset_dxpl_mpio_chunk_opt_ratio(hid_t dxpl_id, unsigned percent_num_proc_per_chunk); diff --git a/src/H5Fpublic.h b/src/H5Fpublic.h index c3230e1..671eec3 100644 --- a/src/H5Fpublic.h +++ b/src/H5Fpublic.h @@ -1606,7 +1606,7 @@ H5_DLL herr_t H5Fget_page_buffering_stats(hid_t file_id, unsigned accesses[2], u * \brief Obtains information about a cache image if it exists * * \file_id - * \param[out] image_addr Offset of the cache image if it exists, or \c HADDR_UNDEF if it does not + * \param[out] image_addr Offset of the cache image if it exists, or #HADDR_UNDEF if it does not * \param[out] image_size Length of the cache image if it exists, or 0 if it does not * \returns \herr_t * @@ -1878,6 +1878,7 @@ H5_DLL herr_t H5Fget_info1(hid_t obj_id, H5F_info1_t *file_info); * * \deprecated When? * + * \todo In which version was this function introduced? * \todo In which version was this function deprecated? * */ @@ -1896,6 +1897,7 @@ H5_DLL herr_t H5Fset_latest_format(hid_t file_id, hbool_t latest_format); * \details H5Fis_hdf5() determines whether a file is in the HDF5 format. * * \todo In which version was this function deprecated? + * \todo In which version was this function introduced? * */ H5_DLL htri_t H5Fis_hdf5(const char *file_name); diff --git a/src/H5Pmodule.h b/src/H5Pmodule.h index 6e92e66..66a9574 100644 --- a/src/H5Pmodule.h +++ b/src/H5Pmodule.h @@ -111,7 +111,8 @@ * * \defgroup GAPL General Access Properties * \ingroup H5P - * \todo Should this be as standalone page? + * The functions in this section can be applied to different kinds of property + * lists. * * \defgroup GCPL Group Creation Properties * \ingroup H5P diff --git a/src/H5Ppublic.h b/src/H5Ppublic.h index 536407c..d0bc2b8 100644 --- a/src/H5Ppublic.h +++ b/src/H5Ppublic.h @@ -116,21 +116,70 @@ extern "C" { /* Define property list class callback function pointer types */ //! /** - * \todo Document me! + * \brief Callback function for H5Pcreate_class() + * + * \param[in] prop_id The identifier of the property list class being created + * \param[in] create_data User pointer to any class creation data required + * \return \herr_t + * + * \details This function is called when a new property list of the class + * with which this function was registered is being created. The + * function is called after any registered parent create function is + * called for each property value. + * + * If the create function returns a negative value, the new list is not + * returned to the user and the property list creation routine returns + * an error value. + * + * \since 1.4.0 + * */ typedef herr_t (*H5P_cls_create_func_t)(hid_t prop_id, void *create_data); //! //! /** - * \todo Document me! + * \brief Callback function for H5Pcreate_class() + * + * \param[in] new_prop_id The identifier of the property list copy + * \param[in] old_prop_id The identifier of the property list being copied + * \param[in] copy_data User pointer to any copy data required + * \return \herr_t + * + * \details This function is called when an existing property list of this + * class is copied. The copy callback function is called after any + * registered parent copy callback function is called for each property + * value. + * + * If the copy routine returns a negative value, the new list is not + * returned to the user and the property list copy function returns an + * error value. + * + * \since 1.4.0 + * */ typedef herr_t (*H5P_cls_copy_func_t)(hid_t new_prop_id, hid_t old_prop_id, void *copy_data); //! //! /** - * \todo Document me! + * \brief Callback function for H5Pcreate_class() + * + * \param[in] prop_id The identifier of the property list class being created + * \param[in] close_data User pointer to any close data required + * \return \herr_t + * + * \details This function is called when a property list of the class + * with which this function was registered is being closed. The + * function is called after any registered parent close function is + * called for each property value. + * + * If the close function returns a negative value, the new list is not + * returned to the user and the property list close routine returns + * an error value. + * + * \since 1.4.0 + * */ typedef herr_t (*H5P_cls_close_func_t)(hid_t prop_id, void *close_data); //! @@ -145,8 +194,8 @@ typedef herr_t (*H5P_cls_close_func_t)(hid_t prop_id, void *close_data); * \param[in,out] value The value for the property * \return \herr_t * - * \details The H5P_prp_cb1_t() describes the parameters used by the - * property create,copy and close callback functions. + * \details The H5P_prp_cb1_t() function describes the parameters used by the + * property create, copy and close callback functions. */ typedef herr_t (*H5P_prp_cb1_t)(const char *name, size_t size, void *value); //! @@ -161,8 +210,8 @@ typedef herr_t (*H5P_prp_cb1_t)(const char *name, size_t size, void *value); * \param[in] value The value for the property * \return \herr_t * - * \details The H5P_prp_cb2_t() describes the parameters used by the - * property set ,copy and delete callback functions. + * \details The H5P_prp_cb2_t() function describes the parameters used by the + * property set, copy and delete callback functions. */ typedef herr_t (*H5P_prp_cb2_t)(hid_t prop_id, const char *name, size_t size, void *value); //! @@ -172,13 +221,28 @@ typedef H5P_prp_cb2_t H5P_prp_set_func_t; typedef H5P_prp_cb2_t H5P_prp_get_func_t; //! /** - * \todo Document me! + * \brief Callback function for encoding property values + * + * \param[in] value The property value to be encoded + * \param[out] buf The encoded property value + * \param[out] size The size of \p buf + * \return \herr_t + * + * \note There is currently no public API which exposes a callback of this type. + * */ typedef herr_t (*H5P_prp_encode_func_t)(const void *value, void **buf, size_t *size); //! //! /** - * \todo Document me! + * \brief Callback function for decoding property values + * + * \param[in] buf A buffer containing an encoded property value + * \param[out] value The decoded property value + * \return \herr_t + * + * \note There is currently no public API which exposes a callback of this type. + * */ typedef herr_t (*H5P_prp_decode_func_t)(const void **buf, void *value); //! @@ -187,7 +251,16 @@ typedef H5P_prp_cb1_t H5P_prp_copy_func_t; //! /** - * \todo Document me! + * \brief Callback function for comparing property values + * + * \param[in] value1 A property value + * \param[in] value2 A property value + * \param[in] size The size of the \p value1 and \p value2 buffers + * \return Returns a positive value if \c value1 is greater than \c value2, a + * negative value if \c value2 is greater than \c value1 and zero if + * \c value1 and \c value2 are equal. + * + * \see H5Pregister(), H5Pinsert() */ typedef int (*H5P_prp_compare_func_t)(const void *value1, const void *value2, size_t size); //! @@ -197,7 +270,19 @@ typedef H5P_prp_cb1_t H5P_prp_close_func_t; /* Define property list iteration function type */ //! /** - * \todo Document me! + * \brief Callback function for H5Piterate() + * + * \param[in] id The identifier of a property list or property list class + * \param[in] name The name of the current property + * \param[in,out] iter_data The user context passed to H5Piterate() + * \return \herr_t_iter + * + * \details This function is called for each property encountered when + * iterating over a property list or property list class + * via H5Piterate(). + * + * \since 1.4.0 + * */ typedef herr_t (*H5P_iterate_t)(hid_t id, const char *name, void *iter_data); //! @@ -264,15 +349,15 @@ typedef enum H5D_mpio_no_collective_cause_t { H5D_MPIO_DATA_TRANSFORMS = 0x04, /**< Collective I/O was not performed because data transforms needed to be applied */ H5D_MPIO_MPI_OPT_TYPES_ENV_VAR_DISABLED = 0x08, - /**< \todo FIXME! */ + /**< Collective I/O was disabled by environment variable (\Code{HDF5_MPI_OPT_TYPES}) */ H5D_MPIO_NOT_SIMPLE_OR_SCALAR_DATASPACES = 0x10, /**< Collective I/O was not performed because one of the dataspaces was neither simple nor scalar */ H5D_MPIO_NOT_CONTIGUOUS_OR_CHUNKED_DATASET = 0x20, /**< Collective I/O was not performed because the dataset was neither contiguous nor chunked */ H5D_MPIO_PARALLEL_FILTERED_WRITES_DISABLED = 0x40, - /**< \todo FIXME! */ + /**< Collective I/O was not performed because parallel filtered writes are disabled */ H5D_MPIO_ERROR_WHILE_CHECKING_COLLECTIVE_POSSIBLE = 0x80, - /**< \todo FIXME! */ + /**< Error */ H5D_MPIO_NO_COLLECTIVE_MAX_CAUSE = 0x100 /**< Sentinel */ } H5D_mpio_no_collective_cause_t; @@ -577,77 +662,12 @@ H5_DLL hid_t H5Pcreate(hid_t cls_id); * those existing properties, only add or remove their own class * properties. Property list classes defined and supported in the * HDF5 library distribution are listed and briefly described in - * H5Pcreate(). The \p create routine is called when a new property - * list of this class is being created. The #H5P_cls_create_func_t - * callback function is defined as follows: - * - * \snippet this H5P_cls_create_func_t_snip + * H5Pcreate(). The \p create, \p copy, \p close functions are called + * when a property list of the new class is created, copied, or closed, + * respectively. * - * The parameters to this callback function are defined as follows: - * - * - * - * - * - * - * - * - * - *
                            \ref hid_t \c prop_idIN: The identifier of the property list being created
                            \Code{void * create_data}IN: User pointer to any class creation data required
                            - * - * The \p create routine is called after any registered - * \p create function is called for each property value. If the - * \p create routine returns a negative value, the new list is not - * returned to the user and the property list creation routine returns - * an error value. - * - * The \p copy routine is called when an existing property - * list of this class is copied. The #H5P_cls_copy_func_t callback - * function is defined as follows: - * \snippet this H5P_cls_copy_func_t_snip - * - * The parameters to this callback function are defined as follows: - * - * - * - * - * - * - * - * - * - *
                            \ref hid_t \c prop_idIN: The identifier of the property list created by copying
                            \Code{void * copy_data}IN: User pointer to any class copy data required
                            - * - * The \p copy routine is called after any registered \p copy function - * is called for each property value. If the \p copy routine returns a - * negative value, the new list is not returned to the user and the - * property list \p copy routine returns an error value. - * - * The \p close routine is called when a property list of this class - * is being closed. The #H5P_cls_close_func_t callback function is - * defined as follows: - * \snippet this H5P_cls_close_func_t_snip - * - * The parameters to this callback function are defined as follows: - * - * - * - * - * - * - * - * - * - *
                            \ref hid_t \c prop_idIN: The identifier of the property list being closed
                            \Code{void * close_data}IN: User pointer to any class close data required
                            - * - * The \p close routine is called before any registered \p close - * function is called for each property value. If the \p close routine - * returns a negative value, the property list close routine returns - * an error value but the property list is still closed. - * - * H5Pclose_class() can be used to release the property list class - * identifier returned by this function so that resources leaks will - * not develop. + * H5Pclose_class() must be used to release the property list class + * identifier returned by this function. * * \since 1.4.0 * @@ -1376,35 +1396,12 @@ H5_DLL htri_t H5Pisa_class(hid_t plist_id, hid_t pclass_id); * returned in this case, the iterator cannot be restarted if * one of the calls to its operator returns non-zero. * - * The prototype for the #H5P_iterate_t operator is as follows: - * \snippet this H5P_iterate_t_snip - * - * The operation receives the property list or class + * The operation \p iter_func receives the property list or class * identifier for the object being iterated over, \p id, the * name of the current property within the object, \p name, * and the pointer to the operator data passed in to H5Piterate(), - * \p iter_data. The valid return values from an operator are - * as follows: + * \p iter_data. * - * - * - * - * - * - * - * - * - * - * - * - * - * - *
                            ZeroCauses the iterator to continue, returning zero when all - * properties have been processed
                            PositiveCauses the iterator to immediately return that positive - * value, indicating short-circuit success. The iterator - * can be restarted at the index of the next property
                            NegativeCauses the iterator to immediately return that value, - * indicating failure. The iterator can be restarted at the - * index of the next property
                            * H5Piterate() assumes that the properties in the object * identified by \p id remain unchanged through the iteration. * If the membership changes during the iteration, the function's @@ -1877,9 +1874,6 @@ H5_DLL herr_t H5Pget_attr_phase_change(hid_t plist_id, unsigned *max_compact, un * * \brief Returns information about a filter in a pipeline * - * \todo Signature for H5Pget_filter2 is different in H5Pocpl.c than in - * H5Ppublic.h - * * \ocpl_id{plist_id} * \param[in] idx Sequence number within the filter pipeline of the filter * for which information is sought @@ -4205,17 +4199,14 @@ H5_DLL herr_t H5Pset_alignment(hid_t fapl_id, hsize_t threshold, hsize_t alignme * * \note Note: Raw dataset chunk caching is not currently * supported when using the MPI I/O and MPI POSIX file drivers - * in read/write mode; see H5Pset_fapl_mpio() and - * H5Pset_fapl_mpiposix(), respectively. When using one of these - * file drivers, all calls to H5Dread() and H5Dwrite() will access + * in read/write mode; see H5Pset_fapl_mpio(). When using this + * file driver, all calls to H5Dread() and H5Dwrite() will access * the disk directly, and H5Pset_cache() will have no effect on * performance. * * \note Raw dataset chunk caching is supported when these drivers are * used in read-only mode. * - * \todo Check on H5Pset_fapl_mpio() and H5Pset_fapl_mpiposix(). - * * \version 1.8.0 The use of the \p mdc_nelmts parameter was discontinued. * Metadata cache configuration is managed with * H5Pset_mdc_config() and H5Pget_mdc_config(). @@ -5483,12 +5474,38 @@ H5_DLL herr_t H5Pset_coll_metadata_write(hid_t plist_id, hbool_t is_collective); H5_DLL herr_t H5Pget_coll_metadata_write(hid_t plist_id, hbool_t *is_collective); /** - * \todo Add missing documentation + * \ingroup FAPL + * + * \brief Get the MPI communicator and info + * + * \fapl_id + * \param[out] comm MPI communicator + * \param[out] info MPI info object + * \return \herr_t + * + * \details H5Pget_mpi_params() gets the MPI communicator and info stored in + * the file access property list \p fapl_id. + * + * \todo When was this introduced? + * */ H5_DLL herr_t H5Pget_mpi_params(hid_t fapl_id, MPI_Comm *comm, MPI_Info *info); /** - * \todo Add missing documentation + * \ingroup FAPL + * + * \brief Set the MPI communicator and info + * + * \fapl_id + * \param[in] comm MPI communicator + * \param[in] info MPI info object + * \return \herr_t + * + * \details H5Pset_mpi_params() sets the MPI communicator and info stored in + * the file access property list \p fapl_id. + * + * \todo When was this introduced? + * */ H5_DLL herr_t H5Pset_mpi_params(hid_t fapl_id, MPI_Comm comm, MPI_Info info); #endif /* H5_HAVE_PARALLEL */ @@ -7100,9 +7117,6 @@ H5_DLL herr_t H5Pget_virtual_printf_gap(hid_t dapl_id, hsize_t *gap_size); * * \dapl_id * \param[out] view The flag specifying the view of the virtual dataset. - * Valid values are: - * \li #H5D_VDS_FIRST_MISSING - * \li #H5D_VDS_LAST_AVAILABLE * * \return \herr_t * @@ -7456,11 +7470,7 @@ H5_DLL herr_t H5Pset_virtual_printf_gap(hid_t dapl_id, hsize_t gap_size); * * \dapl_id * \param[in] view Flag specifying the extent of the data to be included - * in the view. Valid values are: - * \li #H5D_VDS_FIRST_MISSING: View includes all data - * before the first missing mapped data - * \li #H5D_VDS_LAST_AVAILABLE View includes all - * available mapped data + * in the view. * * \return \herr_t * @@ -7628,8 +7638,11 @@ H5_DLL herr_t H5Pget_hyper_vector_size(hid_t fapl_id, size_t *size /*out*/); * \details H5Pget_preserve() checks the status of the dataset transfer * property list. * + * \since 1.0.0 + * * \version 1.6.0 The flag parameter was changed from INTEGER to LOGICAL to * better match the C API. (Fortran 90) + * \version 1.8.2 Deprecated. * */ H5_DLL int H5Pget_preserve(hid_t plist_id); @@ -7657,6 +7670,8 @@ H5_DLL int H5Pget_preserve(hid_t plist_id); * * Please refer to the function H5Pset_type_conv_cb() for more details. * + * \since 1.8.0 + * */ H5_DLL herr_t H5Pget_type_conv_cb(hid_t dxpl_id, H5T_conv_except_func_t *op, void **operate_data); /** @@ -7680,6 +7695,8 @@ H5_DLL herr_t H5Pget_type_conv_cb(hid_t dxpl_id, H5T_conv_except_func_t *op, voi * H5Pset_vlen_mem_manager(), returning the parameters set by * that function. * + * \since 1.0.0 + * */ H5_DLL herr_t H5Pget_vlen_mem_manager(hid_t plist_id, H5MM_allocate_t *alloc_func, void **alloc_info, H5MM_free_t *free_func, void **free_info); @@ -7923,8 +7940,9 @@ H5_DLL herr_t H5Pset_hyper_vector_size(hid_t plist_id, size_t size); * I/O pipeline treats the destination datapoints as completely * uninitialized. * - * \todo Add missing version information: introduction, deprecation, etc. - * Why is the declaration not in the deprecated section? + * \since 1.0.0 + * + * \version 1.8.2 Deprecated. * */ H5_DLL herr_t H5Pset_preserve(hid_t plist_id, hbool_t status); @@ -7952,7 +7970,7 @@ H5_DLL herr_t H5Pset_preserve(hid_t plist_id, hbool_t status); * function prototype is as follows: * \snippet H5Tpublic.h H5T_conv_except_func_t_snip * - * \todo Add version information. + * \since 1.8.0 * */ H5_DLL herr_t H5Pset_type_conv_cb(hid_t dxpl_id, H5T_conv_except_func_t op, void *operate_data); @@ -8002,7 +8020,8 @@ H5_DLL herr_t H5Pset_type_conv_cb(hid_t dxpl_id, H5T_conv_except_func_t op, void * set to \c NULL and the \p alloc_info and \p free_info parameters are * ignored. * - * \todo Add version information. + * \since 1.0.0 + * */ H5_DLL herr_t H5Pset_vlen_mem_manager(hid_t plist_id, H5MM_allocate_t alloc_func, void *alloc_info, H5MM_free_t free_func, void *free_info); -- cgit v0.12