Merge pull request #542 from gheber/doxygen2

Added documentation for the deprecated H5G calls.

doxygen/aliases

@@ -202,13 +202,14 @@ ALIASES += es_id="\param[in] es_id The event set ID to add this asynchronous ope
 
 ALIASES += estack_id="\param[in] estack_id Error stack identifier"
 ALIASES += estack_id{1}="\param[in] \1 Error stack identifier"
-ALIASES += cpp_c_api_note="\note \Bold{C++ Developers using HDF5 C-API functions beware:}\n If a C routine that takes a function pointer as an argument is called from within C++ code, the C routine should be returned from normally. Examples of this kind of routine include callbacks such as H5Pset_elink_cb() and H5Pset_type_conv_cb() and functions such as H5Tconvert() and H5Ewalk2().\n Exiting the routine in its normal fashion allows the HDF5 C library to clean up its work properly. In other words, if the C++ application jumps out of the routine back to the C++ \c catch statement, the library is not given the opportunity to close any temporary data structures that were set up when the routine was called. The C++ application should save some state as the routine is started so that any problem that occurs might be diagnosed."
+ALIASES += cpp_c_api_note="\attention \Bold{C++ Developers using HDF5 C-API functions beware:}\n Several functions in this C-API take function pointers or callbacks as arguments. Examples include H5Pset_elink_cb(), H5Pset_type_conv_cb(), H5Tconvert(), and H5Ewalk2(). Application code must ensure that those callback functions return normally such to allow the HDF5 to manage its resources and maintain a consistent state. For instance, those functions must not use the C \c setjmp / \c longjmp mechanism to leave those callback functions. Within the context of C++, any exceptions thrown within the callback function must be caught, such as with a \Code{catch(…)} statement. Any exception state can be placed within the provided user data function call arguments, and may be thrown again once the calling function has returned. Exceptions raised and not handled inside the callback are not supported as it might leave the HDF5 library in an inconsistent state. Similarly, using C++20 coroutines cannot be used as callbacks, since they do not support plain return statements. If a callback function yields execution to another C++20 coroutine calling HDF5 functions as well, this may lead to undefined behavior."
 ALIASES += sa_metadata_ops="\sa \li H5Pget_all_coll_metadata_ops() \li H5Pget_coll_metadata_write() \li H5Pset_all_coll_metadata_ops() \li H5Pset_coll_metadata_write() \li \ref maybe_metadata_reads"
 
 ################################################################################
 # The Usual Suspects
 ################################################################################
 
+ALIASES += click4more="(Click on a enumerator, field, or type for more information.)"
 ALIASES += csets="<table><tr><td>#H5T_CSET_ASCII</td><td>US ASCII</td></tr><tr><td>#H5T_CSET_UTF8</td><td>UTF-8 Unicode encoding</td></tr></table>"
 ALIASES += datatype_class=" \li #H5T_INTEGER \li #H5T_FLOAT \li #H5T_STRING \li #H5T_BITFIELD \li #H5T_OPAQUE \li #H5T_COMPOUND \li #H5T_REFERENCE \li #H5T_ENUM \li #H5T_VLEN \li #H5T_ARRAY"
 ALIASES += file_access="<table><tr><td>#H5F_ACC_RDWR</td><td>File was opened with read/write access.</td></tr><tr><td>#H5F_ACC_RDONLY</td><td>File was opened with read-only access.</td></tr><tr><td>#H5F_ACC_SWMR_WRITE</td><td>File was opened with read/write access for a single-writer/multiple-reader (SWMR) scenario. Note that the writer process must also open the file with the #H5F_ACC_RDWR flag.</td></tr><tr><td>#H5F_ACC_SWMR_READ</td><td>File was opened with read-only access for a single-writer/multiple-reader (SWMR) scenario. Note that the reader process must also open the file with the #H5F_ACC_RDONLY flag.</td></tr></table>"
@@ -224,5 +225,5 @@ ALIASES += scopes="<table><tr><td>#H5F_SCOPE_GLOBAL</td><td>Flushes the entire v
 ALIASES += sign_prop="<table><tr><td>#H5T_SGN_NONE</td><td>0</td><td>Unsigned integer type</td></tr><tr><td>#H5T_SGN_2</td><td>1</td><td>Two's complement signed integer type</td></tr></table>"
 ALIASES += storage_type="<table><tr><td>#H5G_STORAGE_TYPE_COMPACT</td><td>Compact storage</td></tr><tr><td>#H5G_STORAGE_TYPE_DENSE</td><td>Indexed storage</td></tr><tr><td>#H5G_STORAGE_TYPE_SYMBOL_TABLE</td><td>Symbol tables, the original HDF5 structure</td></tr></table>"
 ALIASES += str_pad_type="<table><tr><td>#H5T_STR_NULLTERM</td><td>0</td><td>Null terminate (as C does)</td></tr><tr><td>#H5T_STR_NULLPAD</td><td>1</td><td>Pad with zeros</td></tr><tr><td>#H5T_STR_SPACEPAD</td><td>2</td><td>Pad with spaces (as FORTRAN does)</td></tr></table>"
-ALIASES += virtual=" \see Supporting Functions: \li H5Pget_layout() \li H5Pset_layout() \li H5Sget_regular_hyperslab() \li H5Sis_regular_hyperslab() \li H5Sselect_hyperslab() \see VDS Functions: \li H5Pget_virtual_count() \li H5Pget_virtual_dsetname() \li H5Pget_virtual_filename() \li H5Pget_virtual_prefix() \li H5Pget_virtual_printf_gap() \li H5Pget_virtual_srcspace() \li H5Pget_virtual_view() \li H5Pget_virtual_vspace() \li H5Pset_virtual \li H5Pset_virtual_prefix() \li H5Pset_virtual_printf_gap() \li H5Pset_virtual_view()"
+ALIASES += see_virtual=" \see Supporting Functions: H5Pget_layout(), H5Pset_layout(), H5Sget_regular_hyperslab(), H5Sis_regular_hyperslab(), H5Sselect_hyperslab() \see VDS Functions: H5Pget_virtual_count(), H5Pget_virtual_dsetname(), H5Pget_virtual_filename(), H5Pget_virtual_prefix(), H5Pget_virtual_printf_gap(), H5Pget_virtual_srcspace(), H5Pget_virtual_view(), H5Pget_virtual_vspace(), H5Pset_virtual(), H5Pset_virtual_prefix(), H5Pset_virtual_printf_gap(), H5Pset_virtual_view()"
 ALIASES += obj_info_fields="<table><tr><th>Flag</th><th>Purpose</th></tr><tr><td>#H5O_INFO_BASIC</td><td>Fill in the fileno, addr, type, and rc fields</td></tr><tr> <td>#H5O_INFO_TIME</td><td>Fill in the atime, mtime, ctime, and btime fields</td></tr><tr> <td>#H5O_INFO_NUM_ATTRS</td> <td>Fill in the num_attrs field</td></tr><tr><td>#H5O_INFO_HDR</td><td>Fill in the num_attrs field</td></tr><tr><td>#H5O_INFO_META_SIZE</td><td>Fill in the meta_size field</td></tr><tr><td>#H5O_INFO_ALL</td><td>#H5O_INFO_BASIC | #H5O_INFO_TIME | #H5O_INFO_NUM_ATTRS | #H5O_INFO_HDR | #H5O_INFO_META_SIZE</td></tr></table>"

doxygen/dox/DDLBNF110.dox

@@ -2,12 +2,12 @@
 
 \todo Revise this & break it up!
 
-\section intro Introduction
+\section intro110 Introduction
 
 This document contains the data description language (DDL) for an HDF5 file. The
 description is in Backus-Naur Form (BNF).
 
-\section expo Explanation of Symbols
+\section expo110 Explanation of Symbols
 
 This section contains a brief explanation of the symbols used in the DDL.
 
@@ -23,7 +23,7 @@ This section contains a brief explanation of the symbols used in the DDL.
  TBD                      To Be Decided
 \endcode
 
-\section ddl The DDL
+\section ddl110 The DDL
 
 \code{.unparsed}
 <file> ::= HDF5 <file_name> { <file_super_block>opt <root_group> }
@@ -509,7 +509,7 @@ This section contains a brief explanation of the symbols used in the DDL.
 <hex_value> ::= 0x[0-F][0-F]+ | [0-F][0-F]+
 \endcode
 
-\section example An Example of an HDF5 File in DDL
+\section example110 An Example of an HDF5 File in DDL
 
 \code{.unparsed}
 HDF5 "example.h5" {

doxygen/dox/DDLBNF112.dox

@@ -2,12 +2,12 @@
 
 \todo Revise this & break it up!
 
-\section intro Introduction
+\section intro112 Introduction
 
 This document contains the data description language (DDL) for an HDF5 file. The
 description is in Backus-Naur Form (BNF).
 
-\section expo Explanation of Symbols
+\section expo112 Explanation of Symbols
 
 This section contains a brief explanation of the symbols used in the DDL.
 
@@ -23,7 +23,7 @@ This section contains a brief explanation of the symbols used in the DDL.
  TBD                      To Be Decided
 \endcode
 
-\section ddl The DDL
+\section ddl112 The DDL
 
 \code{.unparsed}
 <file> ::= HDF5 <file_name> { <file_super_block>opt <root_group> }
@@ -512,7 +512,7 @@ This section contains a brief explanation of the symbols used in the DDL.
 <hex_value> ::= 0x[0-F][0-F]+ | [0-F][0-F]+
 \endcode
 
-\section example An Example of an HDF5 File in DDL
+\section example112 An Example of an HDF5 File in DDL
 
 \code{.unparsed}
 HDF5 "example.h5" {

doxygen/dox/FileFormatSpec.dox

@@ -0,0 +1,23 @@
+/** \page FMT3 HDF5 File Format Specification Version 3.0
+
+\htmlinclude H5.format.html
+
+*/
+
+/** \page FMT2 HDF5 File Format Specification Version 2.0
+
+\htmlinclude H5.format.2.0.html
+
+*/
+
+/** \page FMT11 HDF5 File Format Specification Version 1.1
+
+\htmlinclude H5.format.1.1.html
+
+*/
+
+/** \page FMT1 HDF5 File Format Specification Version 1.0
+
+\htmlinclude H5.format.1.0.html
+
+*/

doxygen/dox/MetadataCachingInHDF5.dox

@@ -388,7 +388,7 @@ From the user perspective, all the cache configuration data for a given file is
 contained in an instance of the \ref H5AC_cache_config_t structure -- the definition
 of which is given below:
 
-\snippet H5ACpublic.h H5AC_cache_config_t_general_snip
+\snippet H5ACpublic.h H5AC_cache_config_t_snip
 
 This structure is defined in \c H5ACpublic.h. Each field is discussed below and in
 the associated header comment.

doxygen/dox/OtherSpecs.dox

@@ -0,0 +1,11 @@
+/** \page IMG HDF5 Image and Palette Specification Version 1.2
+
+\htmlinclude ImageSpec.html
+
+*/
+
+/** \page TBL HDF5 Table Specification Version 1.0
+
+\htmlinclude TableSpec.html
+
+*/

doxygen/dox/Overview.dox

@@ -26,6 +26,7 @@ Finally, do not miss the search engine (top right-hand corner)! If you are
 looking for a specific function, it'll take you there directly. If unsure, it'll
 give you an idea of what's on offer and a few promising leads.
 
-See also: \link api-compat-macros API Compatibility Macros \endlink
+\par ToDo List
+     There is plenty of <a href="./todo.html">unfinished business</a>.
 
 */

doxygen/dox/ReferenceManual.dox

@@ -1,7 +1,6 @@
 /** \page RM Reference Manual
 
-The HDF5 C-API provides applications with fine-grained control over all aspects
-of HDF5 functionality. This functionality is grouped into the following
+The functions provides by the HDF5 C-API are grouped into the following
 \Emph{modules}:
 
 \li \ref H5A "Attributes" — Management of HDF5 attributes (\ref H5A)
@@ -27,29 +26,16 @@ of HDF5 functionality. This functionality is grouped into the following
 \par API Versioning
      See \ref api-compat-macros
 
-\par Deprecated Functions
-     A list of deprecated functions can be found <a href="./deprecated.html">here</a>.
+\par Deprecated Functions and Types
+     A list of deprecated functions and types can be found
+     <a href="./deprecated.html">here</a>.
 
 \par Etiquette
      Here are a few simple rules to follow:
      \li \Bold{Handle discipline:} If you acquire a handle (by creation or copy), \Emph{you own it!} (..., i.e., you have to close it.)
      \li \Bold{Dynamic memory allocation:} ...
      \li \Bold{Use of locations:} Identifier + name combo
 
-\attention \Bold{C++ Developers using HDF5 C-API functions beware:}\n
-      If a C routine that takes a function pointer as an argument is called from
-      within C++ code, the C routine should be returned from normally.
-      Examples of this kind of routine include callbacks such as H5Pset_elink_cb()
-      and H5Pset_type_conv_cb() and functions such as H5Tconvert() and H5Ewalk2().\n
-      Exiting the routine in its normal fashion allows the HDF5 C library to clean
-      up its work properly. In other words, if the C++ application jumps out of
-      the routine back to the C++ \c catch statement, the library is not given the
-      opportunity to close any temporary data structures that were set up when the
-      routine was called. The C++ application should save some state as the
-      routine is started so that any problem that occurs might be diagnosed.
-
-
-\par ToDo List
-     There is plenty of <a href="./todo.html">unfinished business</a>.
+\cpp_c_api_note
 
 */

doxygen/dox/Specifications.dox

@@ -1,7 +1,22 @@
 /** \page SPEC Specifications
 
-\li \ref DDLBNF112 "DDL in BNF for HDF5 1.12 and above"
+\section DDL
+
 \li \ref DDLBNF110 "DDL in BNF through HDF5 1.10"
-\li <a href="https://portal.hdfgroup.org/display/HDF5/Design+Specifications"> Other Specifications</a>
+\li \ref DDLBNF112 "DDL in BNF for HDF5 1.12 and above"
+
+\section File Format
+
+\li \ref FMT1 "HDF5 File Format Specification Version 1.0"
+\li \ref FMT11 "HDF5 File Format Specification Version 1.1"
+\li \ref FMT2 "HDF5 File Format Specification Version 2.0"
+\li \ref FMT3 "HDF5 File Format Specification Version 3.0"
+
+\section Other
+
+\li \ref IMG "HDF5 Image and Palette Specification Version 1.2"
+\li \ref TBL "HDF5 Table Specification Version 1.0"
+\li <a href="https://support.hdfgroup.org/HDF5/doc/HL/H5DS_Spec.pdf">
+      HDF5 Dimension Scale Specification</a>
 
 */

doxygen/dox/TechnicalNotes.dox

@@ -1,6 +1,20 @@
 /** \page TN Technical Notes
 
+\li \link api-compat-macros API Compatibility Macros \endlink
 \li \ref TNMDC "Metadata Caching in HDF5"
+\li \ref MT "Thread Safe library"
+\li \ref VFL "Virtual File Layer"
 
+ */
 
- */
+/** \page MT HDF5 Thread Safe library
+
+\htmlinclude ThreadSafeLibrary.html
+
+*/
+
+/** \page VFL HDF5 Virtual File Layer
+
+\htmlinclude VFL.html
+
+*/

doxygen/dox/api-compat-macros.dox

@@ -1,5 +1,4 @@
 /** \page api-compat-macros API Compatibility Macros
-  \tableofcontents
 
   \section audience Audience
   The target audience for this document has existing applications that use the