From 4d2b244e73f108676d4514c9332180e63cf52e52 Mon Sep 17 00:00:00 2001
From: Allen Byrne <50328838+byrnHDF@users.noreply.github.com>
Date: Fri, 13 May 2022 23:25:07 -0500
Subject: Add H5P doxygen chapter (#1762)
---
c++/src/H5Location.cpp | 6 +-
doxygen/dox/ReferenceManual.dox | 2 +-
doxygen/dox/UsersGuide.dox | 386 +++++++++++--
doxygen/examples/H5.format.1.0.html | 2 +-
doxygen/examples/H5.format.1.1.html | 2 +-
doxygen/examples/H5.format.2.0.html | 6 +-
doxygen/examples/H5.format.html | 6 +-
doxygen/img/PropListClassInheritance.gif | Bin 0 -> 17349 bytes
doxygen/img/PropListEcosystem.gif | Bin 0 -> 3720 bytes
java/examples/groups/H5Ex_G_Traverse.java | 2 +-
java/examples/groups/H5Ex_G_Visit.java | 2 +-
src/H5ACpublic.h | 2 +-
src/H5Amodule.h | 4 +-
src/H5Dmodule.h | 30 +-
src/H5Emodule.h | 4 +-
src/H5FDfamily.h | 4 +-
src/H5FDmulti.h | 4 +-
src/H5FDsec2.h | 16 +-
src/H5FDstdio.h | 4 +-
src/H5Fmodule.h | 41 +-
src/H5Gmodule.h | 26 +-
src/H5Gpublic.h | 8 +-
src/H5Imodule.h | 2 +-
src/H5Lmodule.h | 2 +-
src/H5Omodule.h | 2 +-
src/H5Opublic.h | 6 +-
src/H5PLmodule.h | 2 +-
src/H5Pmodule.h | 896 +++++++++++++++++++++++++++++-
src/H5Ppublic.h | 78 +--
src/H5Rmodule.h | 2 +-
src/H5Smodule.h | 23 +-
src/H5Tmodule.h | 35 +-
src/H5Zmodule.h | 2 +-
src/H5module.h | 42 ++
34 files changed, 1506 insertions(+), 143 deletions(-)
create mode 100644 doxygen/img/PropListClassInheritance.gif
create mode 100644 doxygen/img/PropListEcosystem.gif
diff --git a/c++/src/H5Location.cpp b/c++/src/H5Location.cpp
index 98da713..89e4fe1 100644
--- a/c++/src/H5Location.cpp
+++ b/c++/src/H5Location.cpp
@@ -1323,7 +1323,7 @@ H5Location::copyLink(const H5std_string &src_name, const H5std_string &dst_name,
///\note
/// Exercise care in moving groups as it is possible to render
/// data in a file inaccessible with H5Location::moveLink. Please refer
-/// to the Group Interface in the HDF5 User's Guide for details.
+/// to the Group Interface in the HDF5 User Guide for details.
// March, 2018
//--------------------------------------------------------------------------
void
@@ -1366,7 +1366,7 @@ H5Location::moveLink(const H5std_string &src_name, const Group &dst, const H5std
///\note
/// Exercise care in moving groups as it is possible to render
/// data in a file inaccessible with H5Location::moveLink. Please refer
-/// to the Group Interface in the HDF5 User's Guide for details.
+/// to the Group Interface in the HDF5 User Guide for details.
// March, 2018
//--------------------------------------------------------------------------
void
@@ -1406,7 +1406,7 @@ H5Location::moveLink(const H5std_string &src_name, const H5std_string &dst_name,
///\note
/// Exercise care in moving groups as it is possible to render
/// data in a file inaccessible with H5Location::move. Please refer
-/// to the Group Interface in the HDF5 User's Guide for details.
+/// to the Group Interface in the HDF5 User Guide for details.
// Modification
// 2007: QAK modified to use H5L APIs - BMR
// 2018: Will be replaced by H5Location::moveLink() -BMR
diff --git a/doxygen/dox/ReferenceManual.dox b/doxygen/dox/ReferenceManual.dox
index 53f64a7..155352a 100644
--- a/doxygen/dox/ReferenceManual.dox
+++ b/doxygen/dox/ReferenceManual.dox
@@ -1,4 +1,4 @@
-/** \page RM Reference Manual
+/** \page RM HDF5 Reference Manual
The functions provided by the HDF5 C-API are grouped into the following
\Emph{modules}:
diff --git a/doxygen/dox/UsersGuide.dox b/doxygen/dox/UsersGuide.dox
index 22fe5c6..0e2b4fd 100644
--- a/doxygen/dox/UsersGuide.dox
+++ b/doxygen/dox/UsersGuide.dox
@@ -1,4 +1,4 @@
-/** \page UG HDF5 User’s Guide
+/** \page UG HDF5 User Guide
HDF5 Release 1.10
@@ -7,57 +7,214 @@ HDF5 Release 1.10
-\section sec_data_model The HDF5 Data Model and File Structure
- - Introduction
- - The Abstract Data Model
- - The HDF5 Storage Model
- - The Structure of an HDF5 File
-
-\section sec_program The HDF5 Library and Programming Model
- - Introduction
- - The HDF5 Programming Model
- - The Data Transfer Pipeline
-
-\section sec_file The HDF5 File
- - Introduction
- - File Access Modes
- - File Creation and File Access Properties
- - Low-level File Drivers
- - "Programming Model for Files
- - Using h5dump to View a File
- - File Function Summaries
- - Creating or Opening an HDF5 File
- - Closing an HDF5 File
- - File Property Lists
- - Alternate File Storage Layouts and Low-level File Drivers
- - Code Examples for Opening and Closing Files
- - Working with Multiple HDF5 Files
-
-\section sec_group HDF5 Groups
- - Introduction
- - Description of the Group Object
- - Using h5dump
- - Group Function Summaries
- - Programming Model for Groups
- - Examples of File Structures
-
-\section sec_dataset HDF5 Datasets
- - Introduction
- - Dataset Function Summaries
- - Programming Model for Datasets
- - Data Transfer
- - Allocation of Space in the File
- - Using HDF5 Filters
-
-\section sec_datatype HDF5 Datatypes
-
-\section sec_dataspace HDF5 Dataspaces and Partial I/O
+\ref sec_data_model
+\li \ref subsec_data_model_intro
+\li \ref subsec_data_model_abstract
+
+ - \ref subsubsec_data_model_abstract_file
+
- \ref subsubsec_data_model_abstract_group
+
- \ref subsubsec_data_model_abstract_dataset
+
- \ref subsubsec_data_model_abstract_space
+
- \ref subsubsec_data_model_abstract_type
+
- \ref subsubsec_data_model_abstract_attr
+
- \ref subsubsec_data_model_abstract_plist
+
- \ref subsubsec_data_model_abstract_link
+
+\li \ref subsec_data_model_storage
+
+ - \ref subsubsec_data_model_storage_spec
+
- \ref subsubsec_data_model_storage_imple
+
+\li \ref subsec_data_model_structure
+
+ - \ref subsubsec_data_model_structure_file
+
- \ref subsubsec_data_model_structure_path
+
- \ref subsubsec_data_model_structure_example
+
+
+\ref sec_program
+\li \ref subsec_program_intro
+\li \ref subsec_program_model
+
+ - \ref subsubsec_program_model_create
+
- \ref subsubsec_program_model_dset
+
- \ref subsubsec_program_model_close
+
- \ref subsubsec_program_model_data
+
- \ref subsubsec_program_model_partial
+
- \ref subsubsec_program_model_info
+
- \ref subsubsec_program_model_compound
+
- \ref subsubsec_program_model_extend
+
- \ref subsubsec_program_model_group
+
- \ref subsubsec_program_model_attr
+
+\li \ref subsec_program_transfer_pipeline
+
+\ref sec_file
+\li \ref subsec_file_intro
+\li \ref subsec_file_access_modes
+\li \ref subsec_file_creation_access
+\li \ref subsec_file_drivers
+\li \ref subsec_file_program_model
+
+ - \ref subsubsec_file_program_model_create
+
- \ref subsubsec_file_program_model_open
+
- \ref subsubsec_file_program_model_close
+
+\li \ref subsec_file_h5dump
+\li \ref subsec_file_summary
+\li \ref subsec_file_create
+\li \ref subsec_file_closes
+\li \ref subsec_file_property_lists
+
+ - \ref subsubsec_file_property_lists_create
+
- \ref subsubsec_file_property_lists_props
+
- \ref subsubsec_file_property_lists_access
+
+\li \ref subsec_file_alternate_drivers
+
+ - \ref subsubsec_file_alternate_drivers_id
+
- \ref subsubsec_file_alternate_drivers_sec2
+
- \ref subsubsec_file_alternate_drivers_direct
+
- \ref subsubsec_file_alternate_drivers_log
+
- \ref subsubsec_file_alternate_drivers_win
+
- \ref subsubsec_file_alternate_drivers_stdio
+
- \ref subsubsec_file_alternate_drivers_mem
+
- \ref subsubsec_file_alternate_drivers_family
+
- \ref subsubsec_file_alternate_drivers_multi
+
- \ref subsubsec_file_alternate_drivers_split
+
- \ref subsubsec_file_alternate_drivers_par
+
+\li \ref subsec_file_examples
+
+ - \ref subsubsec_file_examples_trunc
+
- \ref subsubsec_file_examples_props
+
- \ref subsubsec_file_examples_access
+
+\li \ref subsec_file_multiple
+
+\ref sec_group
+\li \ref subsec_group_intro
+\li \ref subsec_group_descr
+
+ - \ref subsubsec_group_descr_object
+
- \ref subsubsec_group_descr_model
+
- \ref subsubsec_group_descr_path
+
- \ref subsubsec_group_descr_impl
+
+\li \ref subsec_group_h5dump
+\li \ref subsec_group_function
+\li \ref subsec_group_program
+
+ - \ref subsubsec_group_program_create
+
- \ref subsubsec_group_program_open
+
- \ref subsubsec_group_program_dataset
+
- \ref subsubsec_group_program_close
+
- \ref subsubsec_group_program_links
+
- \ref subsubsec_group_program_info
+
- \ref subsubsec_group_program_objs
+
- \ref subsubsec_group_program_all
+
+\li \ref subsec_group_examples
+
+\ref sec_dataset
+\li \ref subsec_dataset_intro
+\li \ref subsec_dataset_function
+\li \ref subsec_dataset_program
+
+ - \ref subsubsec_dataset_program_general
+
- \ref subsubsec_dataset_program_create
+
- \ref subsubsec_dataset_program_transfer
+
- \ref subsubsec_dataset_program_read
+
+\li \ref subsec_dataset_transfer Data Transfer
+
+ - \ref subsubsec_dataset_transfer_pipe
+
- \ref subsubsec_dataset_transfer_filter
+
- \ref subsubsec_dataset_transfer_drive
+
- \ref subsubsec_dataset_transfer_props
+
- \ref subsubsec_dataset_transfer_store
+
- \ref subsubsec_dataset_transfer_partial
+
+\li \ref subsec_dataset_allocation
+
+ - \ref subsubsec_dataset_allocation_store
+
- \ref subsubsec_dataset_allocation_delete
+
- \ref subsubsec_dataset_allocation_release
+
- \ref subsubsec_dataset_allocation_ext
+
+\li \ref subsec_dataset_filters
+
+ - \ref subsubsec_dataset_filters_nbit
+
- \ref subsubsec_dataset_filters_scale
+
- \ref subsubsec_dataset_filters_szip
+
+
+\ref sec_datatype
+\li \ref subsec_datatype_intro
+\li \ref subsec_datatype_model
+
+ - \ref subsubsec_datatype_model_class
+
- \ref subsubsec_datatype_model_predefine
+
+\li \ref subsec_datatype_usage
+
+ - \ref subsubsec_datatype_usage_object
+
- \ref subsubsec_datatype_usage_create
+
- \ref subsubsec_datatype_usage_transfer
+
- \ref subsubsec_datatype_usage_discover
+
- \ref subsubsec_datatype_usage_user
+
+\li \ref subsec_datatype_function
+\li \ref subsec_datatype_program
+
+ - \ref subsubsec_datatype_program_discover
+
- \ref subsubsec_datatype_program_define
+
+\li \ref subsec_datatype_other
+
+ - \ref subsubsec_datatype_other_strings
+
- \ref subsubsec_datatype_other_refs
+
- \ref subsubsec_datatype_other_enum
+
- \ref subsubsec_datatype_other_opaque
+
- \ref subsubsec_datatype_other_bitfield
+
+\li \ref subsec_datatype_fill
+\li \ref subsec_datatype_complex
+
+ - \ref subsubsec_datatype_complex_create
+
- \ref subsubsec_datatype_complex_analyze
+
+\li \ref subsec_datatype_life
+\li \ref subsec_datatype_transfer
+\li \ref subsec_datatype_text
+
+\ref sec_dataspace
+\li \ref subsec_dataspace_intro
+\li \ref subsec_dataspace_function
+\li \ref subsec_dataspace_program
+
+ - \ref subsubsec_dataspace_program_object
+
- \ref subsubsec_dataspace_program_model
+
+\li \ref subsec_dataspace_transfer
+
+ - \ref subsubsec_dataspace_transfer_select
+
- \ref subsubsec_dataspace_transfer_model
+
+\li \ref subsec_dataspace_select
+\li \ref subsec_dataspace_refer
+
+ - \ref subsubsec_dataspace_refer_use
+
- \ref subsubsec_dataspace_refer_create
+
- \ref subsubsec_dataspace_refer_read
+
+\li \ref subsec_dataspace_sample
\ref sec_attribute
\li \ref subsec_attribute_intro
\li \ref subsec_attribute_program
- - To Open and Read or Write an Existing Attribute
+
- To Open and Read or Write an Existing Attribute
\li \ref subsec_error_H5A
\li \ref subsec_attribute_work
@@ -91,9 +248,140 @@ HDF5 Release 1.10
\ref subsubsec_error_adv_app
-\section sec_plist Properties and Property Lists in HDF5
+\ref sec_plist
+\li \ref subsec_plist_intro
+\li \ref subsec_plist_class
+
+ - \ref subsubsec_plist_class
+
- \ref subsubsec_plist_lists
+
- \ref subsubsec_plist_props
+
+\li \ref subsec_plist_program
+
+ - \ref subsubsec_plist_default
+
- \ref subsubsec_plist_basic
+
- \ref subsubsec_plist_additional
+
+\li \ref subsec_plist_generic
+\li \ref subsec_plist_H5P
+\li \ref subsec_plist_resources
+\li \ref subsec_plist_notes
+
+\ref sec_addition
+
+\page AR_UG Additional Resources
\section sec_addition Additional Resources
+These documents provide additional information for the use and tuning of specific HDF5 features.
+
+ Table of Additional resources
+
+
+ Document
+ |
+
+ Comments
+ |
+
+
+
+ HDF5 Examples
+ |
+
+ Code examples by API.
+ |
+
+
+
+ Chunking in HDF5
+ |
+
+ Structuring the use of chunking and tuning it for performance.
+ |
+
+
+
+ Using the Direct Chunk Write Function
+ |
+
+ Describes another way that chunks can be written to datasets.
+ |
+
+
+
+ Copying Committed Datatypes with H5Ocopy
+ |
+
+ Describes how to copy to another file a dataset that uses a committed datatype or an object with an attribute that uses a committed datatype so that the committed datatype in the destination file can be used by multiple objects.
+ |
+
+
+
+ Metadata Caching in HDF5
+ |
+
+ Managing the HDF5 metadata cache and tuning it for performance.
+ |
+
+
+
+ HDF5 Dynamically Loaded Filters
+ |
+
+ Describes how an HDF5 application can apply a filter that is not registered with the HDF5 Library.
+ |
+
+
+
+ HDF5 File Image Operations
+ |
+
+ Describes how to work with HDF5 files in memory. Disk I/O is not required when file images are opened, created, read from, or written to.
+ |
+
+
+
+ Modified Region Writes
+ |
+
+ Describes how to set write operations for in-memory files so that only modified regions are written to storage. Available when the Core (Memory) VFD is used.
+ |
+
+
+
+ Using Identifiers
+ |
+
+ Describes how identifiers behave and how they should be treated.
+ |
+
+
+
+ Using UTF-8 Encoding in HDF5 Applications
+ |
+
+ Describes the use of UTF-8 Unicode character encodings in HDF5 applications.
+ |
+
+
+
+ Freeing Memory Allocated by the HDF5 Library
+ |
+
+ Describes how inconsistent memory management can cause heap corruption or resource leaks and possible solutions.
+ |
+
+
+
+ HDF5 Glossary
+ |
+
+ A glossary of terms.
+ |
+
+
+
+Previous Chapter \ref sec_plist
-\par Don't like what you see? - You can help to improve this User’s Guide
+\par Don't like what you see? - You can help to improve this User Guide
Complete the survey linked near the top of this page!\n
We treat documentation like code: Fork the
HDF5 repo, make changes, and create a
diff --git a/doxygen/examples/H5.format.1.0.html b/doxygen/examples/H5.format.1.0.html
index d2b6610..041cdb6 100644
--- a/doxygen/examples/H5.format.1.0.html
+++ b/doxygen/examples/H5.format.1.0.html
@@ -139,7 +139,7 @@
This document describes the lower-level data objects;
the higher-level objects and their properties are described
- in the HDF5 User's Guide.
+ in the HDF5 User Guide.