1.12 Merge doxygen plist tables changes HDFGroup#2470 from develop (H…

…DFGroup#2505)

* Merge doxygen plist tables changes HDFGroup#2470 from develop

* Add new/moved files

* More add new/moved files

* Doxy corrections

doc/branches-explained.md

@@ -8,34 +8,33 @@ We encourage code contributors to check the status of their commits. If you have
 
 ## `develop`
 Develop is the main branch whose source code always reflects a state with the latest delivered development changes for the next major release of HDF5. 
-This is also considered the integration branch, as **all** new features are integrated into this branch from respective feature branches. 
+This is also considered the integration branch, as **all** new features are integrated into this branch from respective feature branches. Although
+develop is considered an integration branch, it is not an unstable branch. All code merged to develop is expected to pass all GitHub actions and daily tests.
 
 ## `Maintenance branches`
-
-Each currently supported release-line of HDF5 (e.g. 1.8.x, 1.10.x, 1.12.x) has a support branch with the name 1_8, 1_10, 1_12. 
+Each currently supported release line of HDF5 (e.g. 1.8.x, 1.10.x, 1.12.x) has an associated branch with the name hdf5\_1\_10, etc.. 
 Maintenance branches are similar to the develop branch, except the source code in a maintenance branch always reflects a state 
 with the latest delivered development changes for the next **maintenance** release of that particular supported release-line of HDF5. 
 **Some** new features will be integrated into a release maintenance branch, depending on whether or not those features can be 
 introduced in minor releases.  Maintenance branches are removed when a release-line is retired from support.
 
+## `Release branches`
+Release branches are used to prepare a new production release. They are primarily used to allow for last minute dotting of i's and crossing of t's 
+(things like setting the release version, finalizing release notes, and generating Autotools files) and do not include new development. 
+They are created from the maintenance branch at the time of the maintenance release and have 
+names like hdf5\_1\_10\_N, where N is the minor release number. Once the release is  done it is tagged, with a slightly different format: hdf5-1\_\10\_N. 
+Release branches are deleted after the tag has been created. If we have to create a patch version of a release (which is rare), we create a branch off of the tag.
+
 ## `feature/*`
 Feature branches are temporary branches used to develop new features in HDF5.
 Feature branches branch off of develop and exist as long as the feature is under development. 
 When the feature is complete, the branch is merged back into develop, as well as into any support branches in which the change will be included, and then the feature branch is removed.
 
-## `release/*`
-Release branches are used to prepare a new production release. They are primarily used to allow for last minute dotting of i's and crossing of t's 
-(things like setting the release version, finalizing release notes, et cetera) and do not include new development. 
-They are created from the maintenance branch at the time of the maintenance release and have 
-names 1_8_N, 1_10_N, 1_12_N, where N is the minor release number. Once the release is  done it is tagged. 
-Patches can be applied to the release branch for patch releases that are treated as "scaled down" maintenance releases as defined by Release coordinator.
-
-## `1.X/master/*` where X is 8, 10 or 12
-These branches are used to tag 1.X.* maintenance releases.
+Ideally, all feature branches should contain a BRANCH.md file in the root directory that explains the purpose of the branch, contact information for the person responsible, and, if possible, some clues about the branch's life cycle (so we have an idea about when it can be deleted, merged, or declared inactive).
 
-## `inactive/<name>/*`
-These branches are for experimental features that were developed in the past  and have not been merged to develop, and are not under active development. The features 
-can be out of sync with the develop branch.
+Minor bug fixes and refactoring work usually takes place on personal forks, not feature branches.
 
-This document was last updated on March 16, 2021
+## `inactive/*`
+These branches are for experimental features that were developed in the past, have not been merged to develop, and are not under active development. The exception to this is that some feature branches are labeled inactive and preserved for a short time after merging to develop. Integration branches are usually not kept in sync with the develop branch.
 
+As for feature branches, inactive branches should have a BRANCH.md file as described above.

doxygen/Doxyfile.in

@@ -1,4 +1,4 @@
-# Doxyfile 1.8.18
+# Doxyfile
 
 # This file describes the settings to be used by the documentation system
 # doxygen (www.doxygen.org) for a project.
@@ -853,31 +853,20 @@ INPUT_ENCODING         = UTF-8
 # C comment), *.py, *.pyw, *.f90, *.f95, *.f03, *.f08, *.f18, *.f, *.for, *.vhd,
 # *.vhdl, *.ucf, *.qsf and *.ice.
 
-FILE_PATTERNS          = H5*public.h \
-                         H5*module.h \
-                         H5FDcore.h \
-                         H5FDdirect.h \
-                         H5FDfamily.h \
-                         H5FDhdfs.h \
-                         H5FDlog.h \
-                         H5FDmirror.h \
-                         H5FDmpi.h \
-                         H5FDmpio.h \
-                         H5FDmulti.h \
-                         H5FDros3.h \
-                         H5FDsec2.h \
-                         H5FDsplitter.h \
-                         H5FDstdio.h \
-                         H5FDwindows.h \
-                         H5VLconnector.h \
-                         H5VLconnector_passthru.h \
-                         H5VLnative.h \
-                         H5Zdevelop.h \
-                         H5version.h \
-                         H5*.java \
-                         HDF*.java \
-                         *.F90 \
-                         *.dox
+FILE_PATTERNS  = H5*public.h H5*module.h H5*develop.h H5FD*.h \
+                 H5VLconnector.h H5VLconnector_passthru.h H5VLnative.h H5PLextern.h \
+                 H5Zdevelop.h \
+                 H5version.h \
+                 H5*.java \
+                 HDF*.java \
+                 *.F90 \
+                 *.dox \
+                 H5Cpp.h H5AbstractDs.h H5AtomType.h H5Attribute.h H5CommonFG.h H5CompType.h \
+                 H5DataSet.h H5DataSpace.h H5DataType.h H5OcreatProp.h H5DaccProp.h H5DcreatProp.h \
+                 H5DxferProp.h H5EnumType.h H5Exception.h H5FaccProp.h H5FcreatProp.h H5File.h \
+                 H5FloatType.h H5Group.h H5IdComponent.h H5Include.h H5IntType.h H5LcreatProp.h \
+                 H5LaccProp.h H5Library.h H5Location.h H5Object.h H5PredType.h H5PropList.h H5StrType.h \
+                 H5ArrayType.h H5VarLenType.h
 
 # The RECURSIVE tag can be used to specify whether or not subdirectories should
 # be searched for input files as well.
@@ -908,7 +897,15 @@ EXCLUDE_SYMLINKS       = NO
 # Note that the wildcards are matched against the file with absolute path, so to
 # exclude all test directories for example use the pattern */test/*
 
-EXCLUDE_PATTERNS       =
+EXCLUDE_PATTERNS       = */fortran/test/*
+EXCLUDE_PATTERNS      += */fortran/testpar/*
+EXCLUDE_PATTERNS      += */fortran/examples/*
+EXCLUDE_PATTERNS      += */fortran/src/*.c
+EXCLUDE_PATTERNS      += */fortran/src/*.h
+EXCLUDE_PATTERNS      += */hl/fortran/examples/*
+EXCLUDE_PATTERNS      += */hl/fortran/test/*
+EXCLUDE_PATTERNS      += */hl/fortran/src/*.c
+EXCLUDE_PATTERNS      += */hl/fortran/src/*.h
 
 # The EXCLUDE_SYMBOLS tag can be used to specify one or more symbol names
 # (namespaces, classes, functions, etc.) that should be excluded from the

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.)
 

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>
 

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
+ */

doxygen/dox/ReferenceManual.dox

@@ -8,57 +8,163 @@ 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}
     use a combination of identifiers and path names to refer to HDF5 objects.
     If the identifier fully specifies the object in question, pass \Code{'.'} (a dot)
     for the name!
 
-Break a leg!
 </td>
 </tr>
 </table>

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.
 

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
 

doxygen/dox/cookbook/Attributes.dox

@@ -1,6 +1,6 @@
 /** \page Attributes
 
-\section Attributes
+\section secAttributes Attributes
 
 \subsection CB_LargeAttributes Creating "Large" HDF5 Attributes
 

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