diff options
author | Allen Byrne <50328838+byrnHDF@users.noreply.github.com> | 2023-03-01 01:08:47 (GMT) |
---|---|---|
committer | GitHub <noreply@github.com> | 2023-03-01 01:08:47 (GMT) |
commit | 91cf10156a65a96860cea965df74a5adecf3e4e8 (patch) | |
tree | 5466ea669b3c26ad27ad1b82d3bf4287df70a175 /doxygen/dox | |
parent | 4e645aeedf621b341c6b6d5665fecdd08314bda9 (diff) | |
download | hdf5-91cf10156a65a96860cea965df74a5adecf3e4e8.zip hdf5-91cf10156a65a96860cea965df74a5adecf3e4e8.tar.gz hdf5-91cf10156a65a96860cea965df74a5adecf3e4e8.tar.bz2 |
1.12 Merge doxygen plist tables changes #2470 from develop (#2505)
* Merge doxygen plist tables changes #2470 from develop
* Add new/moved files
* More add new/moved files
* Doxy corrections
Diffstat (limited to 'doxygen/dox')
-rw-r--r-- | doxygen/dox/MetadataCachingInHDF5.dox | 2 | ||||
-rw-r--r-- | doxygen/dox/Overview.dox | 2 | ||||
-rw-r--r-- | doxygen/dox/PredefinedDatatypeTables.dox | 22 | ||||
-rw-r--r-- | doxygen/dox/ReferenceManual.dox | 152 | ||||
-rw-r--r-- | doxygen/dox/ViewTools.dox | 8 | ||||
-rw-r--r-- | doxygen/dox/cookbook/Accessibility.dox | 2 | ||||
-rw-r--r-- | doxygen/dox/cookbook/Attributes.dox | 2 | ||||
-rw-r--r-- | doxygen/dox/cookbook/Files.dox | 2 | ||||
-rw-r--r-- | doxygen/dox/cookbook/Performance.dox | 2 | ||||
-rw-r--r-- | doxygen/dox/high_level/extension.dox | 11 |
10 files changed, 167 insertions, 38 deletions
diff --git a/doxygen/dox/MetadataCachingInHDF5.dox b/doxygen/dox/MetadataCachingInHDF5.dox index b84ddea..ce7f0df 100644 --- a/doxygen/dox/MetadataCachingInHDF5.dox +++ b/doxygen/dox/MetadataCachingInHDF5.dox @@ -724,7 +724,7 @@ is allowed to write to file, and then only after entering a sync point with the other caches. After it writes entries to file, it sends the base addresses of the now clean entries to the other caches, so they can mark these entries clean as well, and then leaves the sync point. The other caches mark the specified -entries as clean before they leave the synch point as well. (Observe, that since +entries as clean before they leave the sync point as well. (Observe, that since all caches see the same stream of dirty metadata, they will all have the same set of dirty entries upon sync point entry and exit.) diff --git a/doxygen/dox/Overview.dox b/doxygen/dox/Overview.dox index 64e80c7..eaa942e 100644 --- a/doxygen/dox/Overview.dox +++ b/doxygen/dox/Overview.dox @@ -24,7 +24,7 @@ documents cover a mix of tasks, concepts, and reference, to help a specific Version-specific documentation (see the version in the title area) can be found here: - HDF5 <code>1.12</code> branch (this site) - - <a href="https://docs.hdfgroup.org/hdf5/v1_12/index.html">HDF5 1.12.x</a> + - <a href="https://docs.hdfgroup.org/hdf5/v1_14/index.html">HDF5 1.14.x</a> - <a href="https://docs.hdfgroup.org/hdf5/v1_10/index.html">HDF5 1.10.x</a> - <a href="https://docs.hdfgroup.org/hdf5/v1_8/index.html">HDF5 1.8.x</a> diff --git a/doxygen/dox/PredefinedDatatypeTables.dox b/doxygen/dox/PredefinedDatatypeTables.dox new file mode 100644 index 0000000..fbafa94 --- /dev/null +++ b/doxygen/dox/PredefinedDatatypeTables.dox @@ -0,0 +1,22 @@ +/** \page predefined_datatypes_tables HDF5 Predefined Datatypes + * + * The following datatypes are predefined in HDF5. + * + * \snippet{doc} tables/predefinedDatatypes.dox predefined_ieee_datatypes_table + * + * \snippet{doc} tables/predefinedDatatypes.dox predefined_std_datatypes_table + * + * \snippet{doc} tables/predefinedDatatypes.dox predefined_unix_datatypes_table + * + * \snippet{doc} tables/predefinedDatatypes.dox predefined_string_datatypes_table + * + * \snippet{doc} tables/predefinedDatatypes.dox predefined_intel_datatypes_table + * + * \snippet{doc} tables/predefinedDatatypes.dox predefined_dec_datatypes_table + * + * \snippet{doc} tables/predefinedDatatypes.dox predefined_mips_datatypes_table + * + * \snippet{doc} tables/predefinedDatatypes.dox predefined_native_datatypes_table + * + * \snippet{doc} tables/predefinedDatatypes.dox predefined_c9x_datatypes_table + */ diff --git a/doxygen/dox/ReferenceManual.dox b/doxygen/dox/ReferenceManual.dox index 7900925..b9bcd49 100644 --- a/doxygen/dox/ReferenceManual.dox +++ b/doxygen/dox/ReferenceManual.dox @@ -8,49 +8,156 @@ The functions provided by the HDF5 API are grouped into the following <tr valign="top"> <td> <table> -<tr valign="top"><td style="border: none;"> -\include{doc} core_menu.md +<caption>Core Reference Manual Modules</caption> +<tr><th>Module</th><th colspan="4">Language</th><th>Description</th></tr> +<tr> +<th>Attributes (H5A)</th><td>@ref H5A "C"</td><td>@ref H5::Attribute "C++"</td><td>@ref FH5A "Fortran"</td><td>@ref JH5A "Java"</td><td>HDF5 attribute is a small metadata object describing the nature and/or intended usage of a primary data object. +</td> +</tr> +<tr> +<th>Datasets (H5D)</th><td>@ref H5D "C"</td><td>@ref H5::DataSet "C++"</td><td>@ref FH5D "Fortran"</td><td>@ref JH5D "Java"</td><td>Manage HDF5 datasets, including the transfer of data between memory and disk and the description of dataset properties. +</td> +</tr> +<tr> +<th>Dataspaces (H5S)</th><td>@ref H5S "C"</td><td>@ref H5::DataSpace "C++"</td><td>@ref FH5S "Fortran"</td><td>@ref JH5S "Java"</td><td>HDF5 dataspaces describe the shape of datasets in memory or in HDF5 files. </td> </tr> -<tr valign="top"><td style="border: none;"> -<!-- High-level library --> -\include{doc} high_level_menu.md +<tr> +<th>Datatypes (H5T)</th><td>@ref H5T "C"</td><td>@ref H5::DataType "C++"</td><td>@ref FH5T "Fortran"</td><td>@ref JH5T "Java"</td><td>HDF5 datatypes describe the element type of HDF5 datasets and attributes. </td> </tr> -<tr valign="top"><td style="border: none;"> -<!-- Fortran library --> -\include{doc} fortran_menu.md +<tr> +<th>Error Handling (H5E)</th><td>@ref H5E "C"</td><td>@ref H5::Exception "C++"</td><td>@ref FH5E "Fortran"</td><td>@ref JH5E "Java"</td><td>HDF5 library error reporting. </td> </tr> -<tr valign="top"><td style="border: none;"> -<!-- Java library --> -\include{doc} java_menu.md +<tr> +<th>Event Set (H5ES)</th><td>@ref H5ES "C"</td><td>"C++"</td><td>"Fortran"</td><td>"Java"</td><td>HDF5 event set life cycle used with HDF5 VOL connectors that enable the asynchronous feature in HDF5. </td> </tr> <tr> -<td><a href="./deprecated.html">Deprecated functions</a></td> -<td>Functions with \ref ASYNC</td> -<td>\ref api-compat-macros</td> +<th>Files (H5F)</th><td>@ref H5F "C"</td><td>@ref H5::H5File "C++"</td><td>@ref FH5F "Fortran"</td><td>@ref JH5F "Java"</td><td>Manage HDF5 files. +</td> +</tr> +<tr> +<th>Filters (H5Z)</th><td>@ref H5Z "C"</td><td>"C++"</td><td>@ref FH5Z "Fortran"</td><td>@ref JH5Z "Java"</td><td>Manage HDF5 user-defined filters +</td> +</tr> +<tr> +<th>Groups (H5G)</th><td>@ref H5G "C"</td><td>@ref H5::Group "C++"</td><td>@ref FH5G "Fortran"</td><td>@ref JH5G "Java"</td><td>Manage HDF5 groups. +</td> +</tr> +<tr> +<th>Identifiers (H5I)</th><td>@ref H5I "C"</td><td>@ref H5::IdComponent "C++"</td><td>@ref FH5I "Fortran"</td><td>@ref JH5I "Java"</td><td>Manage identifiers defined by the HDF5 library. +</td> +</tr> +<tr> +<th>Library General (%H5)</th><td>@ref H5 "C"</td><td>@ref H5::H5Library "C++"</td><td>@ref FH5 "Fortran"</td><td>@ref JH5 "Java"</td><td>Manage the life cycle of HDF5 library instances. +</td> +</tr> +<tr> +<th>Links (H5L)</th><td>@ref H5L "C"</td><td>"C++"</td><td>@ref FH5L "Fortran"</td><td>@ref JH5L "Java"</td><td>Manage HDF5 links and link types. +</td> +</tr> +<tr> +<th>Objects (H5O)</th><td>@ref H5O "C"</td><td>"C++"</td><td>@ref FH5O "Fortran"</td><td>@ref JH5O "Java"</td><td>Manage HDF5 objects (groups, datasets, datatype objects). +</td> +</tr> +<tr> +<th>Property Lists (H5P)</th><td>@ref H5P "C"</td><td>@ref H5::PropList "C++"</td><td>@ref FH5P "Fortran"</td><td>@ref JH5P "Java"</td><td>HDF5 property lists are the main vehicle to configure the behavior of HDF5 API functions. +</td> +</tr> +<tr> +<th>Dynamically-loaded Plugins (H5PL)</th><td>@ref H5PL "C"</td><td>"C++"</td><td>"Fortran"</td><td>@ref JH5PL "Java"</td><td>Manage the loading behavior of HDF5 plugins. +</td> +</tr> +<tr> +<th>References (H5R)</th><td>@ref H5R "C"</td><td>"C++"</td><td>@ref FH5R "Fortran"</td><td>@ref JH5R "Java"</td><td>Manage HDF5 references (HDF5 objects, attributes, and selections on datasets a.k.a. dataset regions). +</td> +</tr> +<tr> +<th>VOL Connector (H5VL)</th><td>@ref H5VL "C"</td><td>"C++"</td><td>@ref FH5VL "Fortran"</td><td>@ref JH5VL "Java"</td><td>Manage HDF5 VOL connector plugins. +</td> </tr> </table> - -</td></tr> -<tr><th>Mind the gap</th></tr> +<table> +<caption>High-level Reference Manual Modules</caption> +<tr><th>Module</th><th colspan="4"></th>Language<th>Description</th></tr> +<tr> +<th>HDF5 Lite APIs (H5LT,H5LD)</th><td>@ref H5LT "C"</td><td>"C++"</td><td>@ref FH5LT "Fortran"</td><td>"Java"</td><td>Functions to simplify creating and manipulating datasets, attributes and other features. +</td> +</tr> +<tr> +<th>HDF5 Images API (H5IM)</th><td>@ref H5IM "C"</td><td>"C++"</td><td>@ref FH5IM "Fortran"</td><td>"Java"</td><td>Creating and manipulating HDF5 datasets intended to be interpreted as images. +</td> +</tr> +<tr> +<th>HDF5 Table APIs (H5TB)</th><td>@ref H5TB "C"</td><td>"C++"</td><td>@ref FH5TB "Fortran"</td><td>"Java"</td><td>Creating and manipulating HDF5 datasets intended to be interpreted as tables. +</td> +</tr> +<tr> +<th>HDF5 Packet Table APIs (H5PT)</th><td>@ref H5PT "C"</td><td>"C++"</td><td>"Fortran"</td><td>"Java"</td><td>Creating and manipulating HDF5 datasets to support append- and read-only operations on table data. +</td> +</tr> +<tr> +<th>HDF5 Dimension Scales APIs (H5DS)</th><td>@ref H5DS "C"</td><td>"C++"</td><td>@ref FH5DS "Fortran"</td><td>"Java"</td><td>Creating and manipulating HDF5 datasets that are associated with the dimension of another HDF5 dataset. +</td> +</tr> +<tr> +<th>HDF5 Optimizations APIs (H5DO)</th><td>@ref H5DO "C"</td><td>"C++"</td><td>"Fortran"</td><td>"Java"</td><td>Bypassing default HDF5 behavior in order to optimize for specific use cases. +</td> +</tr> +<tr> +<th>Extensions (H5LR, H5LT)</th><td>@ref H5LR "C"</td><td>"C++"</td><td>"Fortran"</td><td>"Java"</td><td> +</td> +</tr> +</table> +</td> +</tr> <tr><td> +<table> +<caption>Additional Java Reference Manual Modules</caption> +<tr> +<td>@ref HDF5CONST</td><td>This class contains C constants and enumerated types of HDF5 library. +</td> +</tr> +<tr> +<td>@ref HDFNATIVE</td><td>This class encapsulates native methods to deal with arrays of numbers, converting from numbers to bytes and bytes to numbers. +</td> +</tr> +<tr> +<td>@ref HDFARRAY</td><td>This is a class for handling multidimensional arrays for HDF. +</td> +</tr> +<tr> +<td>@ref ERRORS</td><td>The class HDF5Exception returns errors from the Java HDF5 Interface. +</td> +</tr> +</table> +</td> +</tr> +<tr> +<td> +\ref predefined_datatypes_tables<br /> +<a href="./deprecated.html">Deprecated functions</a><br /> +Functions with \ref ASYNC<br /> +\ref api-compat-macros +</td> +</tr> +</table> + Follow these simple rules and stay out of trouble: -\li \Bold{Handle discipline:} The HDF5 C-API is rife with handles or +\li \Bold{Handle discipline:} The HDF5 API is rife with handles or identifiers, which you typically obtain by creating new HDF5 items, copying - items, or retrieving facets of items. \Emph{You acquire a handle, you own it!} - (Colin Powell) In other words, you are responsible for releasing the underlying + items, or retrieving facets of items. Consequently, \Bold{and most importantly}, you are + responsible for releasing the underlying resources via the matching \Code{H5*close()} call, or deal with the consequences of resource leakage. \li \Bold{Closed means closed:} Do not pass identifiers that were previously \Code{H5*close()}-d to other API functions! It will generate an error. \li \Bold{Dynamic memory allocation:} The API contains a few functions in which the HDF5 library dynamically allocates memory on the caller's behalf. The caller owns - this memory and eventually must free it by calling H5free_memory(). (\Bold{Not} - the `free` function \Emph{du jour}!) + this memory and eventually must free it by calling H5free_memory() and not language-explicit memory functions. \li \Bold{Be careful with that saw:} Do not modify the underlying collection when an iteration is in progress! \li \Bold{Use of locations:} Certain API functions, typically called \Code{H5***_by_name} @@ -58,7 +165,6 @@ Follow these simple rules and stay out of trouble: If the identifier fully specifies the object in question, pass \Code{'.'} (a dot) for the name! -Break a leg! </td> </tr> </table> diff --git a/doxygen/dox/ViewTools.dox b/doxygen/dox/ViewTools.dox index 0b685a0..2212d4b 100644 --- a/doxygen/dox/ViewTools.dox +++ b/doxygen/dox/ViewTools.dox @@ -829,6 +829,7 @@ by simply viewing the specified dataset with the <code style="background-color:w \code h5dump -d "HDFEOS/GRIDS/OMI Column Amount O3/Data Fields/SolarZenithAngle" OMI-Aura.he5 \endcode + Subsetting narrows down the output that is displayed. In the following example, the first 15x10 elements (-c "15,10") are specified, beginning with position (0,0) (-s "0,0"): \code @@ -840,11 +841,8 @@ If using the shorthand method, specify: h5dump -A 0 -d "HDFEOS/GRIDS/OMI Column Amount O3/Data Fields/SolarZenithAngle[0,0;;15,10;]" -w 0 OMI-Aura.he5 \endcode -Where, -\par The <code style="background-color:whitesmoke;">-d</code> option must be specified - -before -\par subsetting options (if not using the shorthand method). +Where, the <code style="background-color:whitesmoke;">-d</code> option must be specified +before subsetting options (if not using the shorthand method). The <code style="background-color:whitesmoke;">-A 0</code> option suppresses the printing of attributes. diff --git a/doxygen/dox/cookbook/Accessibility.dox b/doxygen/dox/cookbook/Accessibility.dox index f100283..28009be 100644 --- a/doxygen/dox/cookbook/Accessibility.dox +++ b/doxygen/dox/cookbook/Accessibility.dox @@ -1,6 +1,6 @@ /** \page Accessibility -\section Accessibility +\section secAccessibility Accessibility \subsection CB_MaintainCompat Maintaining Compatibility with other HDF5 Library Versions diff --git a/doxygen/dox/cookbook/Attributes.dox b/doxygen/dox/cookbook/Attributes.dox index 68fd159..5914909 100644 --- a/doxygen/dox/cookbook/Attributes.dox +++ b/doxygen/dox/cookbook/Attributes.dox @@ -1,6 +1,6 @@ /** \page Attributes -\section Attributes +\section secAttributes Attributes \subsection CB_LargeAttributes Creating "Large" HDF5 Attributes diff --git a/doxygen/dox/cookbook/Files.dox b/doxygen/dox/cookbook/Files.dox index 169d638..4893771 100644 --- a/doxygen/dox/cookbook/Files.dox +++ b/doxygen/dox/cookbook/Files.dox @@ -1,6 +1,6 @@ /** \page Files -\section Files +\section secFiles Files \subsection CB_FreeSpace Tracking Free Space in HDF5 Files diff --git a/doxygen/dox/cookbook/Performance.dox b/doxygen/dox/cookbook/Performance.dox index 7ac3a18..5e945b2 100644 --- a/doxygen/dox/cookbook/Performance.dox +++ b/doxygen/dox/cookbook/Performance.dox @@ -1,6 +1,6 @@ /** \page Performance -\section Performance +\section secPerformance Performance \subsection CB_MDCPerf Assessing HDF5 Metadata Cache Performance diff --git a/doxygen/dox/high_level/extension.dox b/doxygen/dox/high_level/extension.dox index e8471b9..d754b96 100644 --- a/doxygen/dox/high_level/extension.dox +++ b/doxygen/dox/high_level/extension.dox @@ -8,13 +8,16 @@ * These functions were created as part of a project supporting * NPP/NPOESS Data Production and Exploitation ( * <a href="https://support.hdfgroup.org/projects/jpss/documentation"> - * project</a>, software). + * project</a>, <a href="https://gamma.hdfgroup.org/ftp/pub/outgoing/NPOESS/source"> + * software </a>). * While they were written to facilitate access to NPP, NPOESS, and JPSS * data in the HDF5 format, these functions may be useful to anyone working * with region references, hyperslab selections, or bit-fields. * - * Note that these functions are not part of the standard HDF5 distribution; - * the software must be separately downloaded and installed. + * Note that these functions are not part of the standard HDF5 distribution; + * the <a href="https://gamma.hdfgroup.org/ftp/pub/outgoing/NPOESS/source"> + * software </a> + * must be separately downloaded and installed. * * A comprehensive guide to this library, * <a href="https://support.hdfgroup.org/projects/jpss/documentation/HL/UG/NPOESS_HL-UG.pdf"> @@ -28,7 +31,7 @@ * \n Copies data from a referenced region to a region in a destination dataset. * - \ref H5LRcreate_ref_to_all * \n Creates a dataset with the region references to the data in all datasets located under a - * specified group in a file or creates a dataset with object references to all objects (groups or datasets) + * specified group in a file or creates a dataset with object references to all objects (groups or datasets) * located under a specified group in a file. * - \ref H5LRcreate_region_references * \n Creates an array of region references using an array of paths to |