Add doxygen for high level modules to hdf51.10 (#1899)

7 files changed, 1131 insertions, 8 deletions

diff --git a/doxygen/dox/ReferenceManual.dox b/doxygen/dox/ReferenceManual.dox
index 155352a..cd438c2 100644
--- a/doxygen/dox/ReferenceManual.dox
+++ b/doxygen/dox/ReferenceManual.dox
@@ -29,19 +29,26 @@ The functions provided by the HDF5 C-API are grouped into the following
 </td><td style="border: none;vertical-align: top;">
 \li \ref api-compat-macros
 \li <a href="./deprecated.html">Deprecated functions</a>
-\li High-level Extensions
+\li \ref high_level
     <ul>
-    <li><a href="https://portal.hdfgroup.org/display/HDF5/Lite">\Bold{HDF5 Lite} (H5LT)</a></li>
-    <li><a href="https://portal.hdfgroup.org/display/HDF5/Images">\Bold{HDF5 Image} (H5IM)</a></li>
-    <li><a href="https://portal.hdfgroup.org/display/HDF5/Tables">\Bold{HDF5 Table} (H5TB)</a></li>
-    <li><a href="https://portal.hdfgroup.org/display/HDF5/Packet+Tables">\Bold{HDF5 Packet Table} (H5TB)</a></li>
-    <li><a href="https://portal.hdfgroup.org/display/HDF5/Dimension+Scales">\Bold{HDF5 Dimension Scale} (H5DS)</a></li>
+    <li>\ref H5LT "Lite (H5LT, H5LD)"
+    <li>\ref H5IM "Images (H5IM)"
+    <li>\ref H5TB "Table (H5TB)"
+    <li>\ref H5PT "Packet Table (H5PT)"
+    <li>\ref H5DS "Dimension Scale (H5DS)"
+    <li>\ref H5DO "Optimizations (H5DO)"
+    <li>\ref H5LR "Extensions (H5LR, H5LT)"
     </ul>
 </td></tr>
 <tr><td colspan="3" style="border: none;">
-\ref H5 \ref H5A \ref H5D \ref H5E \ref H5F \ref H5G \ref H5I \ref H5L
+\a Core \a library: \ref H5 \ref H5A \ref H5D \ref H5E \ref H5F \ref H5G \ref H5I \ref H5L
 \ref H5O \ref H5P \ref H5PL \ref H5R \ref H5S \ref H5T \ref H5Z
 </td></tr>
+
+<tr><td colspan="3" style="border: none;">
+\a High-level \a library: \ref H5LT \ref H5IM \ref H5TB \ref H5PT \ref H5DS \ref H5DO \ref H5LR
+</td></tr>
+
 </table>
 
 </td></tr>
@@ -82,4 +89,4 @@ Break a leg!
      <a href="https://github.com/HDFGroup/hdf5/pulls">pull request</a> !\n
      See the \ref RMT for general guidance.
 
-*/
\ No newline at end of file
+*/
diff --git a/doxygen/dox/high_level/extension.dox b/doxygen/dox/high_level/extension.dox
new file mode 100644
index 0000000..c81ac6e
--- /dev/null
+++ b/doxygen/dox/high_level/extension.dox
@@ -0,0 +1,654 @@
+/** \defgroup H5LR Extensions
+ *
+ * <em>Working with region references, hyperslab selections, 
+ * and bit-fields (H5LR, H5LT)</em>
+ *
+ * The following reference manual entries describe high-level HDF5 C and Fortran APIs 
+ * for working with region references, hyperslab selections, and bit-fields. 
+ * 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>, 
+ * <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 
+ * <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"> 
+ * <em>User Guide to the HDF5 High-level Library for Handling Region References and Hyperslab Selections</em></a>
+ * is available at 
+ * https://support.hdfgroup.org/projects/jpss/documentation/HL/UG/NPOESS_HL-UG.pdf.
+ *
+ * - \ref H5LRcopy_reference
+ *        \n Copies data from the specified dataset to a new location and 
+ *        creates a reference to it.
+ * - \ref H5LRcopy_region
+ *        \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) 
+ *        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 
+ *        datasets and an array of corresponding hyperslab descriptions.
+ * - \ref H5LRget_region_info
+ *        \n Retrieves information about the data a region reference points to.
+ * - \ref H5LRmake_dataset
+ *        \n Creates and writes a dataset containing a list of 
+ *        region references.
+ * - \ref H5LRread_region
+ *        \n  Retrieves raw data pointed to by a region reference to 
+ *        an application buffer.
+ * - \ref H5LTcopy_region
+ *        \n Copies data from a specified region in a source dataset 
+ *        to a specified region in a destination dataset.
+ * - \ref H5LTread_bitfield_value
+ *        \n Retrieves the values of quality flags for each element 
+ *        to the application provided buffer.
+ * - \ref H5LTread_region
+ *        \n Reads selected data to an application buffer.
+ *
+ */
+
+/*-------------------------------------------------------------------------
+ *
+ * Make dataset functions
+ *
+ *-------------------------------------------------------------------------
+ */
+
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5LR
+ *
+ * \brief Creates and writes a dataset containing a list of region references.
+ *
+ * \fgdta_loc_id
+ * \param[in] path          Path to the dataset being created
+ * \param[in] type_id       Datatype of the dataset
+ * \param[in] buf_size      Size of the \p loc_id_ref and \p buf arrays
+ * \param[in] loc_id_ref    Array of object identifiers; each identifier 
+ *                          describes to which HDF5 file the corresponding 
+ *                          region reference belongs to
+ * \param[in] buf           Array of region references
+ *
+ * \return \herr_t
+ *
+ * \details Given an array of size \p buf_size of region references \p buf, 
+ *          the function will create a dataset with path \p path, at location 
+ *          specified by \p loc_id and of a datatype specified by \p type_id, 
+ *          and will write data associated with each region reference in the order 
+ *          corresponding to the order of the region references in the buffer. 
+ *          It is assumed that all referenced hyperslabs have the same dimensionality, 
+ *          and only the size of the slowest changing dimension may differ. 
+ *          Each reference in the \p buf array belongs to the file identified 
+ *          by the corresponding object identifiers in the array \p loc_id_ref.
+ *
+ *          If \p path does not exist in \p loc_id then the function will 
+ *          create the path specified by \p path automatically.
+ *
+ * \version 1.1 Fortran wrapper introduced in this release.
+ *
+ * \since 1.0
+ *
+ */
+H5_HLRDLL herr_t H5LRmake_dataset(hid_t loc_id,
+				 const char *path, 
+				 hid_t type_id, const size_t buf_size,
+				 const hid_t *loc_id_ref,
+				 const hdset_reg_ref_t *buf);
+
+/*-------------------------------------------------------------------------
+ *
+ * Make and manipulate dataset region references functions
+ *
+ *-------------------------------------------------------------------------
+ */
+
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5LR
+ *
+ * \brief Creates an array of region references using an array of paths to 
+ *        datasets and an array of corresponding hyperslab descriptions.
+ *
+ * \param[in] obj_id        File identifier for the HDF5 file containing
+ *                          the referenced regions or an object identifier
+ *                          for any object in that file
+ * \param[in] num_elem      Number of elements in the \p path and 
+ *                          \p buf arrays
+ * \param[in] path          Array of pointers to strings, which contain 
+ *                          the paths to the target datasets for the 
+ *                          region references
+ * \param[in] block_coord   Array of hyperslab coordinate
+ * \param[out] buf          Buffer for returning an array of region 
+ *                          references
+ *
+ * \return \herr_t
+ *
+ * \note    **Motivation:**
+ * \note    H5LRcreate_region_references() is useful when creating 
+ *          large numbers of similar region references.
+ *
+ * \details H5LRcreate_region_references() creates a list of region references 
+ *          given an array of paths to datasets and another array listing the 
+ *          corner coordinates of the corresponding hyperslabs.
+ *
+ *          \p path parameter is an array of pointers to strings.
+ *
+ *          \p num_elem specifies the number of region references to be created, 
+ *          thus specifying the size of the \p path and \p _buf arrays.
+ *
+ *          Buffer \p block_coord has size 2*rank and is the coordinates of the 
+ *          starting point following by the coordinates of the ending point of 
+ *          the hyperslab, repeated \p num_elem times for each hyperslab. 
+ *          For example, creating two region references to two hyperslabs, 
+ *          one with a rectangular hyperslab region starting at element (2,2) 
+ *          to element (5,4) and the second rectangular region starting at 
+ *          element (7,7) to element (9,10), results in \p block_coord 
+ *          being {2,2,5,4, 7,7,9,10}.
+ *
+ *          The rank of the hyperslab will be the same as the rank of the 
+ *          target dataset. H5LRcreate_region_references() will retrieve 
+ *          the rank for each dataset and will use those values to interpret 
+ *          the values in the buffer. Please note that rank may vary from one 
+ *          dataset to another.
+ *
+ * \version 1.1 Fortran wrapper introduced in this release.
+ *
+ * \since 1.0
+ *
+ */
+H5_HLRDLL herr_t H5LRcreate_region_references(hid_t obj_id,
+					     size_t num_elem,
+					     const char **path,
+					     const hsize_t *block_coord,
+					     hdset_reg_ref_t *buf);
+
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5LR
+ *
+ * \brief Copies data from the specified dataset to a new location and 
+ *        creates a reference to it.
+ *
+ * \param[in] obj_id        Identifier of any object in a file an 
+ *                          HDF5 reference belongs to
+ * \param[in] ref           Reference to the datasets region
+ * \param[in] file          Name of the destination file 
+ * \param[in] path          Full path to the destination dataset
+ * \param[in] block_coord   Hyperslab coordinates in the destination 
+ *                          dataset
+ * \param[out] ref_new      Region reference to the new location of 
+ *                          data
+ *
+ * \return \herr_t
+ *
+ * \details Given a data set pointed to by a region reference, the function 
+ *          H5LRcopy_reference() will copy the hyperslab data referenced by 
+ *          a datasets region reference into existing dataset specified by 
+ *          its path \p path in the file with the name \p file, and to location 
+ *          specified by the hyperslab coordinates \p block_coord. It will 
+ *          create the region reference \p ref_new to point to the new location. 
+ *          The number of elements in the old and newly specified regions has 
+ *          to be the same.
+ *
+ *          Buffer \p block_coord has size 2*rank and is the coordinates of 
+ *          the starting point following by the coordinates of the ending 
+ *          point of the hyperslab. For example, to extract a rectangular 
+ *          hyperslab region starting at element (2,2) to element (5,4) 
+ *          then \p block_coord would be {2, 2, 5, 4}.
+ *
+ * \version 1.1 Fortran wrapper introduced in this release.
+ *
+ * \since 1.0
+ *
+ */
+H5_HLRDLL herr_t H5LRcopy_reference(hid_t obj_id, hdset_reg_ref_t *ref, const char *file,
+				    const char *path, const hsize_t *block_coord, 
+				    hdset_reg_ref_t *ref_new);
+
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5LR
+ *
+ * \brief Copies data from a referenced region to a region in a 
+ *        destination dataset.
+ *
+ * \param[in] obj_id        Identifier of any object in a file 
+ *                          dataset region reference belongs to
+ * \param[in] ref           Dataset region reference
+ * \param[in] file          Name of the destination file 
+ * \param[in] path          Full path to the destination dataset
+ * \param[in] block_coord   Hyperslab coordinates in the destination 
+ *                          dataset
+ *
+ * \return \herr_t
+ *
+ * \details Given a dataset region reference \p ref in a source file 
+ *          specified by an identifier of any object in that file 
+ *          \p obj_id, the function will write data to the existing 
+ *          dataset \p path in file \p file to the simple hyperslab 
+ *          specified by \p block_coord.
+ *
+ *          Buffer \p block_coord has size 2*rank and is the coordinates 
+ *          of the starting point following by the coordinates of the 
+ *          ending point of the hyperslab. For example, to specify a 
+ *          rectangular hyperslab destination region starting at element 
+ *          (2,2) to element (5,4) then \p block_coord would be {2, 2, 5, 4}.
+ *
+ *          If \p path does not exist in the destination file (as may be 
+ *          the case when writing to a new file) then the dataset will be 
+ *          copied directly to the \p path and \p block_coord will be 
+ *          disregarded.
+ *
+ * \version 1.1 Fortran wrapper introduced in this release.
+ *
+ * \since 1.0
+ *
+ */
+H5_HLRDLL herr_t H5LRcopy_region(hid_t obj_id,
+				hdset_reg_ref_t *ref,
+				const char *file,
+				const char *path,
+				const hsize_t *block_coord);
+
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5LR
+ *
+ * \brief 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) located under a specified group in a file.
+ *
+ * \fg_loc_id
+ * \param[in] group_path    Absolute or relative path to the group 
+ *                          at which traversal starts
+ * \param[in] ds_path       Absolute or relative path to the dataset 
+ *                          with region references to be created
+ * \param[in] index_type    Index_type; 
+ *                          see valid values below in description
+ * \param[in] order         Order in which index is traversed; 
+ *                          see valid values below in description
+ * \param[in] ref_type      Reference type;
+ *                          see valid values below in description
+ *
+ * \return \herr_t
+ *
+ * \details H5LRcreate_ref_to_all() 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) located 
+ *          under a specified group in a file.
+ *
+ *          Given a dataset path \p ds_path in a file specified by the 
+ *          \p loc_id identifier, the function H5LRcreate_ref_to_all() 
+ *          will create a contiguous one-dimensional dataset with the 
+ *          region references or object references depending on the value 
+ *          of the \p ref_type parameter. When \p ref_type is 
+ *          #H5R_DATASET_REGION, each region reference points to all data 
+ *          in a dataset encountered by an internally called H5Lvisit() 
+ *          routine, which starts at the group specified by the \p loc_id 
+ *          and \p group_path parameters. In a like manner, when
+ *          \p ref_type is #H5R_OBJECT, each object reference points to 
+ *          an object (a group or a dataset) encountered by H5Lvisit().
+ *
+ *          If \p ds_path does not exist in \p loc_id then the function 
+ *          will create the path specified by \p ds_path automatically.
+ *
+ *          \p index_type specifies the index to be used. 
+ *          Valid values include the following:
+ *          - #H5_INDEX_NAME        Alphanumeric index on name
+ *          - #H5_INDEX_CRT_ORDER   Index on creation order
+ *
+ *          \p order specifies the order in which objects are to be 
+ *          inspected along the index specified in \p index_type. 
+ *          Valid values include the following:
+ *          - #H5_ITER_INC      Increasing order
+ *          - #H5_ITER_DEC      Decreasing order
+ *          - #H5_ITER_NATIVE   Fastest available order
+ *
+ *          For more detailed information on these two parameters, 
+ *          see H5Lvisit().
+ *
+ *          \p ref_type specifies the type of the reference to be used. 
+ *          Valid values include the following:
+ *          - #H5R_DATASET_REGION   Dataset region reference
+ *          - #H5R_OBJECT           Object reference
+ *
+ * \version 1.1 Fortran wrapper introduced in this release.
+ *
+ * \since 1.0
+ *
+ */
+H5_HLRDLL herr_t H5LRcreate_ref_to_all(hid_t loc_id, const char *group_path,
+					 const char *ds_path, H5_index_t index_type, H5_iter_order_t order, H5R_type_t ref_type);
+
+/*-------------------------------------------------------------------------
+ *
+ * Read dataset functions
+ *
+ *-------------------------------------------------------------------------
+ */
+
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5LR
+ *
+ * \brief Retrieves raw data pointed to by a region reference 
+ *        to an application buffer.
+ *
+ * \param[in] obj_id        File identifier for the HDF5 file containing
+ *                          the dataset with the referenced region or an
+ *                          object identifier for any object in that file
+ * \param[in] ref           Region reference specifying data to be read
+ *                          in
+ * \param[in] mem_type      Memory datatype of data read from referenced 
+ *                          region into the application buffer
+ * \param[in,out] numelem   Number of elements to be read into buffer 
+ *                          \p buf
+ * \param[out] buf          Buffer in which data is returned to the 
+ *                          application
+ *
+ * \return \herr_t
+ *
+ * \details H5LRread_region() reads data pointed to by the region 
+ *          reference \p ref into the buffer \p buf.
+ *
+ *          \p numelem specifies the number of elements to be read 
+ *          into \p buf. When the size of the reference region is unknown, 
+ *          H5LRread_region() can be called with \p buf set to NULL; 
+ *          the number of elements in the referenced region will be returned 
+ *          in \p numelem.
+ *
+ *          The buffer buf must be big enough to hold \p numelem elements 
+ *          of type \p mem_type. For example, if data is read from the referenced 
+ *          region into an integer buffer, \p mem_type should be #H5T_NATIVE_INT 
+ *          and the buffer must be at least \c sizeof(int) * \p numelem  bytes 
+ *          in size. This buffer must be allocated by the application.
+ *
+ * \version 1.1 Fortran wrapper introduced in this release.
+ *
+ * \since 1.0
+ *
+ */
+H5_HLRDLL herr_t H5LRread_region(hid_t obj_id,
+				const hdset_reg_ref_t *ref, 
+				hid_t mem_type,
+				size_t *numelem,
+				void *buf );
+
+/*-------------------------------------------------------------------------
+ *
+ * Query dataset functions
+ *
+ *-------------------------------------------------------------------------
+ */
+
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5LR
+ *
+ * \brief Retrieves information about the data a region reference 
+ *        points to.
+ *
+ * \param[in] obj_id        Identifier of any object in an HDF5 file 
+ *                          the region reference belongs to.
+ * \param[in] ref           Region reference to query
+ * \param[in,out] len       Size of the buffer to store \p path in. 
+ *                          NOTE: if \p *path is not NULL then \p *len 
+ *                          must be the appropriate length
+ * \param[out] path         Full path that a region reference points to
+ * \param[out] rank         The number of dimensions of the dataset
+ *                          dimensions of the dataset pointed by 
+ *                          region reference.
+ * \param[out] dtype        Datatype of the dataset pointed by the 
+ *                          region reference.
+ * \param[out] sel_type     Type of the selection (point or hyperslab)
+ * \param[in,out] numelem   Number of coordinate blocks or 
+ *                          selected elements.
+ * \param[out] buf          Buffer containing description of the region 
+ *                          pointed by region reference
+ *
+ * \return \herr_t
+ *
+ * \details H5LRget_region_info() queries information about the data 
+ *          pointed by a region reference \p ref. It returns one of the 
+ *          absolute paths to a dataset, length of the path, dataset’s rank 
+ *          and datatype, description of the referenced region and type of 
+ *          the referenced region. Any output argument can be NULL if that 
+ *          argument does not need to be returned.
+ *
+ *          The parameter \p obj_id is an identifier for any object in the 
+ *          HDF5 file containing the referenced object. For example, it can 
+ *          be an identifier of a dataset the region reference belongs to 
+ *          or an identifier of an HDF5 file the dataset with region references 
+ *          is stored in.
+ *
+ *          The parameter \p ref is a region reference to query.
+ *
+ *          The parameter \p path is a pointer to application allocated
+ *          buffer of size \p len+1 to return an absolute path to a dataset
+ *          the region reference points to.
+ *
+ *          The parameter \p len is a length of absolute path string plus 
+ *          the \0 string terminator. If path parameter is NULL, actual 
+ *          length of the path (+1 for \0 string terminator) is returned to 
+ *          application and can be used to allocate buffer path of an 
+ *          appropriate length \p len.
+ *
+ *          The parameter \p sel_type describes the type of the selected
+ *          region. Possible values can be #H5S_SEL_POINTS for point 
+ *          selection and #H5S_SEL_HYPERSLABS for hyperslab selection.
+ *
+ *          The parameter \p numelem describes how many elements will be 
+ *          placed in the buffer \p buf. The number should be interpreted 
+ *          using the value of \p sel_type.
+ *
+ *          If value of \p sel_type is #H5S_SEL_HYPERSLABS, the parameter 
+ *          \p buf contains \p numelem blocks of the coordinates for each 
+ *          simple hyperslab of the referenced region. Each block has 
+ *          length \c 2*\p rank and is organized as follows: <"start" coordinate>, 
+ *          immediately followed by <"opposite" corner coordinate>. 
+ *          The total size of the buffer to hold the description of the 
+ *          region will be \c 2*\p rank*\p numelem. If region reference 
+ *          points to a contiguous sub-array, then the value of \p numelem 
+ *          is 1 and the block contains coordinates of the upper left and 
+ *          lower right corners of the sub-array (or simple hyperslab).
+ *
+ *          If value of \p sel_type is #H5S_SEL_POINTS, the parameter \p buf 
+ *          contains \p numelem blocks of the coordinates for each selected 
+ *          point of the referenced region. Each block has length \p rank 
+ *          and contains coordinates of the element. The total size of the 
+ *          buffer to hold the description of the region will be 
+ *          \p rank* \p numelem.
+ *
+ *
+ * \version 1.1 Fortran wrapper introduced in this release.
+ *
+ * \since 1.0
+ *
+ */
+H5_HLRDLL herr_t H5LRget_region_info(hid_t obj_id,
+				    const hdset_reg_ref_t *ref,  
+				    size_t *len, 
+				    char *path,
+				    int *rank,
+				    hid_t *dtype,
+				    H5S_sel_type *sel_type,
+				    size_t *numelem,
+				    hsize_t *buf );
+
+
+
+/*-------------------------------------------------------------------------
+ *
+ * Make dataset functions
+ *
+ *-------------------------------------------------------------------------
+ */
+
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5LR
+ *
+ * \brief Copies data from a specified region in a source dataset 
+ *        to a specified region in a destination dataset
+ *
+ * \param[in] file_src          Name of the source file
+ * \param[in] path_src          Full path to the source dataset
+ * \param[in] block_coord_src   Hyperslab coordinates in the 
+ *                              source dataset
+ * \param[in] file_dest         Name of the destination file
+ * \param[in] path_dest         Full path to the destination dataset
+ * \param[in] block_coord_dset  Hyperslab coordinates in the 
+ *                              destination dataset
+ *
+ * \return \herr_t
+ *
+ * \details Given a path to a dataset \p path_src in a file with the 
+ *          name \p file_src, and description of a simple hyperslab of 
+ *          the source \p block_coord_src, the function will write data 
+ *          to the dataset \p path_dest in file \p file_dest to the 
+ *          simple hyperslab specified by \p block_coord_dset. 
+ *          The arrays \p block_coord_src and \p block_coord_dset have 
+ *          a length of 2*rank and are the coordinates of the starting 
+ *          point following by the coordinates of the ending point of the 
+ *          hyperslab. For example, to specify a rectangular hyperslab 
+ *          destination region starting at element (2,2) to element (5,4) 
+ *          then \p block_coord_dset would be {2, 2, 5, 4}.
+ *
+ *          If \p path_dest does not exist in the destination file 
+ *          (as may be the case when writing to a new file) then the 
+ *          dataset will be copied directly to the \p path_dest and 
+ *          \p block_coord_dset will be disregarded.
+ *
+ * \version 1.1 Fortran wrapper introduced in this release.
+ *
+ * \since 1.0
+ *
+ */
+H5_HLRDLL herr_t H5LTcopy_region(const char *file_src,
+				const char *path_src,
+				const hsize_t *block_coord_src,
+				const char *file_dest,
+				const char *path_dest,
+				const hsize_t *block_coord_dset);
+
+/*-------------------------------------------------------------------------
+ *
+ * Read dataset functions
+ *
+ *-------------------------------------------------------------------------
+ */
+
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5LR
+ *
+ * \brief Reads selected data to an application buffer.
+ *
+ * \param[in] file          Name of file
+ * \param[in] path          Full path to a dataset
+ * \param[in] block_coord   Hyperslab coordinates
+ * \param[in] mem_type      Memory datatype, describing the buffer 
+ *                          the referenced data will be read into
+ * \param[out] buf          Buffer containing data from the 
+ *                          referenced region
+ *
+ * \return \herr_t
+ *
+ * \details H5LTread_region() reads data from a region described by 
+ *          the hyperslab coordinates in \p block_coord, located in 
+ *          the dataset specified by its absolute path \p path in a 
+ *          file specified by its name \p file. Data is read into a 
+ *          buffer \p buf of the datatype that corresponds to the 
+ *          HDF5 datatype specified by \p mem_type.
+ *
+ *          Buffer \p block_coord has size 2*rank and is the coordinates 
+ *          of the starting point following by the coordinates of the 
+ *          ending point of the hyperslab. For example, to extract a 
+ *          rectangular hyperslab region starting at element (2,2) to 
+ *          element (5,4) then \p block_coord would be {2, 2, 5, 4}.
+ *
+ *          Buffer \p buf should be big enough to hold selected elements 
+ *          of the type that corresponds to the \p mem_type
+ *
+ * \version 1.1 Fortran wrapper introduced in this release.
+ *
+ * \since 1.0
+ *
+ */
+H5_HLRDLL herr_t  H5LTread_region(const char *file,
+				 const char *path,
+				 const hsize_t *block_coord,
+				 hid_t mem_type,
+				 void *buf );
+
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5LR
+ *
+ * \brief Retrieves the values of quality flags for each element 
+ *        to the application provided buffer.
+ *
+ * \param[in] dset_id   Identifier of the dataset with bit-field values
+ * \param[in] num_values    Number of the values to be extracted
+ * \param[in] offset        Array of staring bits to be extracted from 
+ *                          the element; valid values: 0 (zero) through 7
+ * \param[in] lengths       Array of the number of bits to be extracted 
+ *                          for each value
+ * \param[in] space         Dataspace identifier, describing the elements 
+ *                          to be read from the dataset with bit-field 
+ *                          values
+ * \param[out] buf          Buffer to read the values in
+ *
+ * \return \herr_t
+ *
+ * \details H5LTread_bitfield_value() reads selected elements from a 
+ *          dataset specified by its identifier \p dset_id, and unpacks 
+ *          the bit-field values to a buffer \p buf.
+ *
+ *          The parameter \p space is a space identifier that indicates 
+ *          which elements of the dataset should be read.
+ *
+ *          The parameter \p offset is an array of length \p num_values; 
+ *          the i<sup>th</sup> element of the array holds the value of the
+ *          starting bit of the i<sup>th</sup> bit-field value. 
+ *          Valid values are: 0 (zero) through 7.
+ *
+ *          The parameter \p lengths is an array of length \p num_values; 
+ *          the i<sup>th</sup> element of the array holds the number of 
+ *          bits to be extracted for the i<sup>th</sup> bit-field value. 
+ *          Extracted bits will be interpreted as a base-2 integer value. 
+ *          Each value will be converted to the base-10 integer value and 
+ *          stored in the application buffer. 
+ *
+ *          Buffer \p buf is allocated by the application and should be big 
+ *          enough to hold \c num_sel_elem * \p num_values elements of the 
+ *          specified type, where \c num_sel_elem is a number of the elements 
+ *          to be read from the dataset. Data in the buffer is organized 
+ *          as \p num_values values for the first element, followed by the 
+ *          \p num_values values for the second element, ... , followed by 
+ *          the \p num_values values for the 
+ *          \c num_selected_elem<sup>th</sup> element.
+ *
+ * \version 1.1 Fortran wrapper introduced in this release.
+ *
+ * \since 1.0
+ *
+ */
+H5_HLRDLL herr_t H5LTread_bitfield_value(hid_t dset_id, int num_values, const unsigned *offset,
+					const unsigned *lengths, hid_t space, int *buf);
+
diff --git a/doxygen/dox/high_level/high_level.dox b/doxygen/dox/high_level/high_level.dox
new file mode 100644
index 0000000..c53d298
--- /dev/null
+++ b/doxygen/dox/high_level/high_level.dox
@@ -0,0 +1,29 @@
+/** \page high_level High-level library
+ * The high-level HDF5 library includes several sets of convenience and standard-use APIs to 
+ * facilitate common HDF5 operations.
+ *
+ * <ul>
+ * <li>\ref H5LT "Lite (H5LT, H5LD)"
+ * \n
+ * Functions to simplify creating and manipulating datasets, attributes and other features
+ * <li>\ref H5IM "Image (H5IM)"
+ * \n
+ * Creating and manipulating HDF5 datasets intended to be interpreted as images
+ * <li>\ref H5TB "Table (H5TB)"
+ * \n
+ * Creating and manipulating HDF5 datasets intended to be interpreted as tables
+ * <li>\ref H5PT "Packet Table (H5PT)"
+ * \n
+ * Creating and manipulating HDF5 datasets to support append- and read-only operations on table data
+ * <li>\ref H5DS "Dimension Scale (H5DS)"
+ * \n
+ * Creating and manipulating HDF5 datasets that are associated with the dimension of another HDF5 dataset
+ * <li>\ref H5DO "Optimizations (H5DO)"
+ * \n
+ * Bypassing default HDF5 behavior in order to optimize for specific use cases
+ * <li>\ref H5LR "Extensions (H5LR, H5LT)"
+ * \n
+ * Working with region references, hyperslab selections, and bit-fields
+ * </ul>
+ * 
+ */
diff --git a/doxygen/examples/H5DO_examples.c b/doxygen/examples/H5DO_examples.c
new file mode 100644
index 0000000..7a33c6b
--- /dev/null
+++ b/doxygen/examples/H5DO_examples.c
@@ -0,0 +1,220 @@
+/* -*- c-file-style: "stroustrup" -*- */
+
+//! <!-- [H5DOwrite] -->
+
+#include <zlib.h>
+#include <math.h>
+#define DEFLATE_SIZE_ADJUST(s) (ceil(((double)(s)) * 1.001) + 12)
+                :
+                :
+size_t       buf_size = CHUNK_NX*CHUNK_NY*sizeof(int);
+                const Bytef *z_src = (const Bytef *)(direct_buf);
+                Bytef *      z_dst; /* Destination buffer            */
+                uLongf       z_dst_nbytes = (uLongf)DEFLATE_SIZE_ADJUST(buf_size);
+                uLong        z_src_nbytes = (uLong)buf_size;
+                int          aggression   = 9; /* Compression aggression setting */
+                uint32_t     filter_mask  = 0;
+                size_t       buf_size     = CHUNK_NX * CHUNK_NY * sizeof(int);
+
+                /* Create the data space */
+                if ((dataspace = H5Screate_simple(RANK, dims, maxdims)) < 0)
+                    goto error;
+
+                /* Create a new file */
+                if ((file = H5Fcreate(FILE_NAME5, H5F_ACC_TRUNC, H5P_DEFAULT, H5P_DEFAULT)) < 0)
+                    goto error;
+
+                /* Modify dataset creation properties, i.e. enable chunking and compression */
+                if ((cparms = H5Pcreate(H5P_DATASET_CREATE)) < 0)
+                    goto error;
+
+                if ((status = H5Pset_chunk(cparms, RANK, chunk_dims)) < 0)
+                    goto error;
+
+                if ((status = H5Pset_deflate(cparms, aggression)) < 0)
+                    goto error;
+
+                /* Create a new dataset within the file using cparms creation properties */
+                if ((dset_id = H5Dcreate2(file, DATASETNAME, H5T_NATIVE_INT, dataspace, H5P_DEFAULT, cparms,
+                                          H5P_DEFAULT)) < 0)
+                    goto error;
+
+                /* Initialize data for one chunk */
+                for (i = n = 0; i < CHUNK_NX; i++)
+                    for (j = 0; j < CHUNK_NY; j++)
+                        direct_buf[i][j] = n++;
+
+                /* Allocate output (compressed) buffer */
+                outbuf = malloc(z_dst_nbytes);
+                z_dst  = (Bytef *)outbuf;
+
+                /* Perform compression from the source to the destination buffer */
+                ret = compress2(z_dst, &z_dst_nbytes, z_src, z_src_nbytes, aggression);
+
+                /* Check for various zlib errors */
+                if (Z_BUF_ERROR == ret) {
+                    fprintf(stderr, "overflow");
+                    goto error;
+                }
+                else if (Z_MEM_ERROR == ret) {
+                    fprintf(stderr, "deflate memory error");
+                    goto error;
+                }
+                else if (Z_OK != ret) {
+                    fprintf(stderr, "other deflate error");
+                    goto error;
+                }
+
+                /* Write the compressed chunk data repeatedly to cover all the
+                 *  * chunks in the dataset, using the direct write function.     */
+                for (i = 0; i < NX / CHUNK_NX; i++) {
+                    for (j = 0; j < NY / CHUNK_NY; j++) {
+                        status =
+                            H5DOwrite_chunk(dset_id, H5P_DEFAULT, filter_mask, offset, z_dst_nbytes, outbuf);
+                        offset[1] += CHUNK_NY;
+                    }
+                    offset[0] += CHUNK_NX;
+                    offset[1] = 0;
+                }
+
+                /* Overwrite the first chunk with uncompressed data.  Set the filter mask to
+                 *  * indicate the compression filter is skipped */
+                filter_mask = 0x00000001;
+                offset[0] = offset[1] = 0;
+                if (H5DOwrite_chunk(dset_id, H5P_DEFAULT, filter_mask, offset, buf_size, direct_buf) < 0)
+                    goto error;
+
+                /* Read the entire dataset back for data verification converting ints to longs */
+                if (H5Dread(dataset, H5T_NATIVE_LONG, H5S_ALL, H5S_ALL, H5P_DEFAULT, outbuf_long) < 0)
+                    goto error;
+
+                /* Data verification here */
+            :
+            :
+
+            //! <!-- [H5DOwrite] -->
+
+            //! <!-- [H5DOread] -->
+
+#include <zlib.h>
+#include <math.h>
+#define DEFLATE_SIZE_ADJUST(s) (ceil(((double)(s)) * 1.001) + 12)
+                :
+                :
+size_t       buf_size = CHUNK_NX*CHUNK_NY*sizeof(int);
+            const Bytef *z_src = (const Bytef *)(direct_buf);
+            Bytef *      z_dst; /* Destination buffer            */
+            uLongf       z_dst_nbytes = (uLongf)DEFLATE_SIZE_ADJUST(buf_size);
+            uLong        z_src_nbytes = (uLong)buf_size;
+            int          aggression   = 9; /* Compression aggression setting */
+            uint32_t     filter_mask  = 0;
+            size_t       buf_size     = CHUNK_NX * CHUNK_NY * sizeof(int);
+            /* For H5DOread_chunk() */
+            void *       readbuf = NULL;                   /* Buffer for reading data */
+            const Bytef *pt_readbuf;                       /* Point to the buffer for data read */
+            hsize_t      read_chunk_nbytes;                /* Size of chunk on disk */
+            int          read_dst_buf[CHUNK_NX][CHUNK_NY]; /* Buffer to hold un-compressed data */
+
+            /* Create the data space */
+            if ((dataspace = H5Screate_simple(RANK, dims, maxdims)) < 0)
+                goto error;
+
+            /* Create a new file */
+            if ((file = H5Fcreate(FILE_NAME5, H5F_ACC_TRUNC, H5P_DEFAULT, H5P_DEFAULT)) < 0)
+                goto error;
+
+            /* Modify dataset creation properties, i.e. enable chunking and compression */
+            if ((cparms = H5Pcreate(H5P_DATASET_CREATE)) < 0)
+                goto error;
+
+            if ((status = H5Pset_chunk(cparms, RANK, chunk_dims)) < 0)
+                goto error;
+
+            if ((status = H5Pset_deflate(cparms, aggression)) < 0)
+                goto error;
+
+            /* Create a new dataset within the file using cparms creation properties */
+            if ((dset_id = H5Dcreate2(file, DATASETNAME, H5T_NATIVE_INT, dataspace, H5P_DEFAULT, cparms,
+                                      H5P_DEFAULT)) < 0)
+                goto error;
+
+            /* Initialize data for one chunk */
+            for (i = n = 0; i < CHUNK_NX; i++)
+                for (j = 0; j < CHUNK_NY; j++)
+                    direct_buf[i][j] = n++;
+
+            /* Allocate output (compressed) buffer */
+            outbuf = malloc(z_dst_nbytes);
+            z_dst  = (Bytef *)outbuf;
+
+            /* Perform compression from the source to the destination buffer */
+            ret = compress2(z_dst, &z_dst_nbytes, z_src, z_src_nbytes, aggression);
+
+            /* Check for various zlib errors */
+            if (Z_BUF_ERROR == ret) {
+                fprintf(stderr, "overflow");
+                goto error;
+            }
+            else if (Z_MEM_ERROR == ret) {
+                fprintf(stderr, "deflate memory error");
+                goto error;
+            }
+            else if (Z_OK != ret) {
+                fprintf(stderr, "other deflate error");
+                goto error;
+            }
+
+            /* Write the compressed chunk data repeatedly to cover all the
+             *  * chunks in the dataset, using the direct write function.     */
+            for (i = 0; i < NX / CHUNK_NX; i++) {
+                for (j = 0; j < NY / CHUNK_NY; j++) {
+                    status = H5DOwrite_chunk(dset_id, H5P_DEFAULT, filter_mask, offset, z_dst_nbytes, outbuf);
+                    offset[1] += CHUNK_NY;
+                }
+                offset[0] += CHUNK_NX;
+                offset[1] = 0;
+            }
+
+            if (H5Fflush(dataset, H5F_SCOPE_LOCAL) < 0)
+                goto error;
+
+            if (H5Dclose(dataset) < 0)
+                goto error;
+
+            if ((dataset = H5Dopen2(file, DATASETNAME1, H5P_DEFAULT)) < 0)
+                goto error;
+
+            offset[0] = CHUNK_NX;
+            offset[1] = CHUNK_NY;
+
+            /* Get the size of the compressed chunk */
+            ret = H5Dget_chunk_storage_size(dataset, offset, &read_chunk_nbytes);
+
+            readbuf    = HDmalloc(read_chunk_nbytes);
+            pt_readbuf = (const Bytef *)readbuf;
+
+            /* Use H5DOread_chunk() to read the chunk back */
+            if ((status = H5DOread_chunk(dataset, H5P_DEFAULT, offset, &read_filter_mask, readbuf)) < 0)
+                goto error;
+
+            ret =
+                uncompress((Bytef *)read_dst_buf, (uLongf *)&buf_size, pt_readbuf, (uLong)read_chunk_nbytes);
+
+            /* Check for various zlib errors */
+            if (Z_BUF_ERROR == ret) {
+                fprintf(stderr, "error: not enough room in output buffer");
+                goto error;
+            }
+            else if (Z_MEM_ERROR == ret) {
+                fprintf(stderr, "error: not enough memory");
+                goto error;
+            }
+            else if (Z_OK != ret) {
+                fprintf(stderr, "error: corrupted input data");
+                goto error;
+            }
+
+            /* Data verification here */
+            :
+            :
+//! <!-- [H5DOread] -->
diff --git a/doxygen/examples/H5LDget_dset_elmts.c b/doxygen/examples/H5LDget_dset_elmts.c
new file mode 100644
index 0000000..e23299a
--- /dev/null
+++ b/doxygen/examples/H5LDget_dset_elmts.c
@@ -0,0 +1,143 @@
+/* -*- c-file-style: "stroustrup" -*- */
+
+//! <!-- [first_declare] -->
+
+DATASET "DSET1" {DATATYPE H5T_STD_I32LE DATASPACE SIMPLE{(4, 13) / (60, 100)} : : }
+
+//! <!-- [first_declare] -->
+
+//! <!-- [first_reading] -->
+
+/* open the HDF5 file */
+fid = H5Fopen(FILE, H5F_ACC_RDWR, H5P_DEFAULT);
+
+/* open the dataset */
+did = H5Dopen2(fid, "DSET1", H5P_DEFAULT);
+        :
+        :
+    /* define hsize_t dims[2]; */
+    /* define hsize_t new_dims[2]; */
+    /* get the dataset's current dimension sizes */
+    H5LDget_dset_dims(did, dims);
+
+        /* extend the dataset by 2 */
+        new_dims[0] = dims[0] + 2;
+        new_dims[1] = dims[1] + 2;
+        H5Dset_extent(did, new_dims)
+
+            /* write data to the extended dataset */
+            : :
+            /* get the size of the dataset's data type */
+            type_size = H5LDget_dset_type_size(did, NULL);
+        :
+        :
+    /* allocate buffer for storing selected data elements from the dataset */
+    /* calculate # of selected elements from dims & new_dims */
+    /* buffer size = type_size * number of selected elements */
+        :
+        :
+    /* read the selected elements from the dataset into buf */
+    H5LDget_dset_elmts(did, dims, new_dims, NULL, buf);
+        :
+        :
+    H5Dclose(did);
+        H5Fclose(fid);
+
+        //! <!-- [first_reading] -->
+
+        //! <!-- [first_output] -->
+
+    data for elements (0, 13), (0, 14) 
+    data for elements (1, 13), (1, 14) 
+    data for elements (2, 13), (2, 14) 
+    data for elements (3, 13), (3, 14)
+    data for elements (4, 0), (4, 1), (4, 2)......................(4, 13), (4, 14)
+    data for elements (5, 0), (5, 1), (5, 2)......................(5, 13), (5, 14)
+
+//! <!-- [first_output] -->
+
+
+//! <!-- [second_declare] -->
+
+    DATASET "DSET2" {
+    DATATYPE  H5T_COMPOUND {
+        H5T_STD_I32LE "a";
+    H5T_STD_I32LE "b";
+    H5T_ARRAY
+    {
+        [4] H5T_STD_I32LE
+    }
+    "c";
+    H5T_STD_I32LE "d";
+    H5T_STD_I32LE "e";
+    H5T_COMPOUND
+    {
+        H5T_STD_I32LE "a";
+        H5T_STD_I32LE "b";
+        H5T_ARRAY
+        {
+            [4] H5T_STD_I32LE
+        }
+        "c";
+        H5T_STD_I32LE "d";
+        H5T_STD_I32LE "e";
+    }
+    "s2";
+    }
+    DATASPACE SIMPLE
+    {
+        (5) / (5)
+    }
+    ::
+    }
+
+    //! <!-- [second_declare] -->
+
+    //! <!-- [second_reading] -->
+
+    /* open the HDF5 file */
+    fid = H5Fopen(FILE, H5F_ACC_RDWR, H5P_DEFAULT);
+
+    /* open the dataset */
+    did = H5Dopen2(fid, "DSET2", H5P_DEFAULT);
+
+    /* define hsize_t dims[1]; */
+    /* define hsize_t new_dims[1]; */
+        :
+        :
+    /* get the dataset's current dimension size */
+    H5LDget_dset_dims(did, dims);
+
+        /* extend the dataset by 2 */
+        new_dims[0] = dims[0] + 2;
+        H5Dset_extent(did, new_dims);
+        :
+        :
+    /* write data to the extended part of the dataset */
+        :
+        :
+    /* #define fields "d,s2.c" */
+    /* get the size of the dataset's data type for the selected fields */
+    type_size = H5LDget_dset_type_size(did, fields);
+        :
+        :
+    /* allocate buffer for storing selected data elements from the dataset */
+    /* calculate # of selected elements from dims & new_dims */
+    /* buffer size = type_size * number of selected elements */
+        :        
+        :
+    /* read the selected elements from the dataset into buf */
+    H5LD_get_dset_elmts(did, dims, new_dims, fields, buf);
+        :
+        :
+    H5Dclose(did);
+        H5Fclose(fid);
+
+        //! <!-- [second_reading] -->
+
+        //! <!-- [second_output] -->
+
+    Data for element (5): integer value for "d", 4 integer values for array "s2.c"
+    Data for element (6): integer value for "d", 4 integer values for array "s2.c"
+
+//! <!-- [second_output] -->
diff --git a/doxygen/examples/H5LT_examples.c b/doxygen/examples/H5LT_examples.c
new file mode 100644
index 0000000..5ed4c29
--- /dev/null
+++ b/doxygen/examples/H5LT_examples.c
@@ -0,0 +1,27 @@
+/* -*- c-file-style: "stroustrup" -*- */
+
+//! <!-- [get_attribute_info] -->
+
+H5T_class_t type_class;
+size_t      type_size;
+hsize_t     dims[0];
+... status = H5LTget_attribute_info(file_id, "/", STRNAME, dims, &type_class, &type_size);
+if (type_class == H5T_STRING) {
+    printf("Attribute is a string.\n");
+    printf("String size: %i\n", type_size);
+
+    //! <!-- [get_attribute_info] -->
+
+    //! <!-- [enum] -->
+
+    “H5T_ENUM
+    {
+        H5T_NATIVE_INT;
+        “Bob” 0;
+        “Elena” 1;
+        “Quincey” 2;
+        “Frank” 3;
+    }
+    ”
+
+//! <!-- [enum] -->
diff --git a/doxygen/examples/H5TBAget_fill.c b/doxygen/examples/H5TBAget_fill.c
new file mode 100644
index 0000000..15eae8b
--- /dev/null
+++ b/doxygen/examples/H5TBAget_fill.c
@@ -0,0 +1,43 @@
+unsigned char tmp_fill_buf[40];
+...
+
+    file_id = H5Fopen(FILENAME, H5F_ACC_RDWR, H5P_DEFAULT);
+dataset_id  = H5Dopen(file_id, TABLE_NAME, H5P_DEFAULT);
+datatype_id = H5Dget_type(dataset_id);
+
+status = H5TBget_table_info(file_id, TABLE_NAME, &nfields, &nrecords);
+
+hasfill = H5TBAget_fill(file_id, TABLE_NAME, dataset_id, tmp_fill_buf);
+
+for (i = 0; i < nfields; i++) {
+    member_type_id     = H5Tget_member_type(datatype_id, (unsigned)i);
+    native_mem_type_id = H5Tget_native_type(member_type_id, H5T_DIR_ASCEND);
+    member_offset      = H5Tget_member_offset(datatype_id, (unsigned)i);
+    printf("member_offset: %i\n", member_offset);
+    memb_class = H5Tget_class(member_type_id);
+    switch (memb_class) {
+        case H5T_INTEGER:
+            /* convert unsigned char array to integer */
+            break;
+        case H5T_FLOAT:
+            /* convert unsigned char array to double or float */
+
+            if (H5Tequal(native_mem_type_id, H5T_NATIVE_DOUBLE)) {
+            }
+            else if (H5Tequal(native_mem_type_id, H5T_NATIVE_FLOAT)) {
+                f.i = tmp_fill_buf[member_offset] | (tmp_fill_buf[member_offset + 1] << 8) |
+                      (tmp_fill_buf[member_offset + 2] << 16) | (tmp_fill_buf[member_offset + 3] << 24);
+                printf("Field %i  Fill Value:  %lf\n", i, f.f);
+            }
+            break;
+
+        case H5T_STRING:
+            /* convert unsigned char array to string */
+            strsize = H5Tget_size(member_type_id);
+
+            printf("Field %i  Fill Value: ", i);
+            for (j = 0; j < strsize; j++)
+                printf("%c", tmp_fill_buf[member_offset + j]);
+            printf("\n");
+            break;
+    }