Merge doxygen2 into develop (#553)

* Fixed warnings and started H5Epublic.h.

* Include H5FD* headers to correctly resolve references.

* Doxygen2 (#330)

* H5Eauto_is_v2.

* Added a few more calls.

* Added a few more H5E calls.

* First cut of H5E v2.

* Added the deprecated v1 calls.

* Updated spacing.

* Once more.

* Taking some inspiration from Eigen3.

* Add doxygen for the assigned functions: H5Pregister1,H5Pinsert1,H5Pen… (#352)

* Add doxygen for the assigned functions: H5Pregister1,H5Pinsert1,H5Pencode1, H5Pget_filter_by_id1,H5Pget_version, H5Pset_file_space,H5Pget_file_space. Someone already adds H5Pget_filter1. Also fixs an extra parameter 'close' call back function for HPregister2.

* doxygen work. fixs format by using clang-format.

* doxgen work for H5Pregister1 etc. Addressed Barbara and Gerd's comments.
For Quincey's comments, since we are not supposed to change the source code.
I leave this to future improvements.

* added documentation for H5P APIs (#350)

* add documenation for H5Pget_buffer,H5Pget_data_transform,H5Pget_edc_check,H5Pget_hyper_vector_size,H5Pget_preserve,H5Pget_type_conv_cb,H5Pget_vlen_mem_manager,H5Pset_btree_ratios

* format corrections

* fixed grammer

* fixed herr_t

* Better name.

* A fresh look.

* add doxygen to H5Ppublic.h

* use attention instead of warning

* Add doxygen comments in H5Ppublic.h (#375)

* Add doxygen comments in H5Ppublic.h

* H5Pset_meta_block_size
* H5Pset_metadata_read_attempts
* H5Pset_multi_type
* H5Pset_object_flush_cb
* H5Pset_sieve_buf_size
* H5Pset_small_data_block_size
* H5Pset_all_coll_metadata_ops
* H5Pget_all_coll_metadata_ops

* Add DOXYGEN_EXAMPLES_DIR to src/CMakeLists.txt

* Fix clang-format errors

* Fix filenames in doxygen/examples

* add doxygen to H5Ppublic.h (#378)

* add doxygen to H5Ppublic.h

* use attention instead of warning

Co-authored-by: Kimmy Mu <kmu@hdfgroup.org>

* Revert "add doxygen to H5Ppublic.h (#378)"

This reverts commit 2ee1821b138a5c00b15ea57ce9e950367480f5f2.

* Updated Doxygen variables.

* I forgot to copy two images.

* Enable desktop search by default.

* Add my assigned Doxygen documentation.

* Remove whitespace at EOL.  Appease clang-format.

* Addressed Chris' comments.

* Added an alias for asynchronous functions.

* One space is enough for all of us.

* Slightly restructured RM page.

* address some issues

* reformatting

* Style external links.

* reformatting

* reformatting

* Added "Metadata Caching in HDF5" as a technical note example.

* Revise this soon!

* Added specification examples.

* Fixed references.

* Added H5AC cache image stuff and file format study.

* Added older FMT versions. Where did 1.0 go?

* Updated C/C++ note and replaced ambiguous labels.

* Reformat source with clang v10.0.1.

* Added the VFL technical note.

* Added what I believe might be called version 1.0 of the format.

* Added the remaining specs.

* Added H5Z callback documentation and fixed a few mistakes.

* Added dox for deprecated H5G calls and fixed a few snippet blockIDs.

* clang-format happy?

* Ok?

* Bonus track: Deprecated H5D functions.

* Carry over the more detailed group description.

* Added documentation for the missing and deprecated H5R calls.

* Life is easier and less repetitive w/ snippets. Use them!

* Eliminate the snippet block ID artifacts in the HTML rendering.

* Fixed snippet HTML artifacts and added a few missing calls.

* Under 20 H5Ps to go!

* Almost complete!

* "This is a form of pedantry up with which I will not put." (Churchill)

* Let's not waste as much space on bulleted lists!

* First complete (?) draft of the Doxygen-based RM.

* Completeness check and minor fixes along the way.

* Pedantry.

* Adding missing H5FD calls checkpoint.

* Pedantry.

* More pedantry.

* Added H5Pset_fapl_log.

* First draft of H5ES.

* Fixed warnings.

* Prep. for map module.

* First cut of the map module.

* Pedantry.

* Possible H5F introduction.

* Fix the indentation.

* Pedantry.

* Ditto.

* Thanks to the reviewers for their comments.

* Added missing images.

* Line numbers are a distraction here.

* More examples, references, and clean-up. Don't repeat yourself!

* Clang pedantry.

* Ditto.

* More reviewer comments...

* Templatized references and cleaned up \todos.

* Committing clang-format changes

* Fixed MANIFEST.

* Addressed Quincey's comments. (OCPLs)

* Fixed a few more \todo items.

* Fixed more \todo items.

* Added attribute life cycle.

* Forgot the examples file.

* Committing clang-format changes

* Pedantry.

* Live and learn!

* Added a sample H5D life cycle.

* Committing clang-format changes

* Pedantry.

Co-authored-by: kyang2014 <kyang2014@users.noreply.github.com>
Co-authored-by: Scot Breitenfeld <brtnfld@hdfgroup.org>
Co-authored-by: Kimmy Mu <kmu@hdfgroup.org>
Co-authored-by: Christopher Hogan <ChristopherHogan@users.noreply.github.com>
Co-authored-by: jya-kmu <53388330+jya-kmu@users.noreply.github.com>
Co-authored-by: David Young <dyoung@hdfgroup.org>
Co-authored-by: Larry Knox <lrknox@hdfgroup.org>
Co-authored-by: github-actions <41898282+github-actions[bot]@users.noreply.github.com>

1 files changed, 263 insertions, 152 deletions

diff --git a/src/H5Dpublic.h b/src/H5Dpublic.h
index ce4ce84..608025a 100644
--- a/src/H5Dpublic.h
+++ b/src/H5Dpublic.h
@@ -39,30 +39,41 @@
 /* Public Typedefs */
 /*******************/
 
-/* Values for the H5D_LAYOUT property */
+//! <!-- [H5D_layout_t_snip] -->
+/**
+ * Values for the H5D_LAYOUT property
+ */
 typedef enum H5D_layout_t {
     H5D_LAYOUT_ERROR = -1,
 
-    H5D_COMPACT    = 0, /*raw data is very small		     */
-    H5D_CONTIGUOUS = 1, /*the default				     */
-    H5D_CHUNKED    = 2, /*slow and fancy			     */
-    H5D_VIRTUAL    = 3, /*actual data is stored in other datasets     */
-    H5D_NLAYOUTS   = 4  /*this one must be last!		     */
+    H5D_COMPACT    = 0, /**< raw data is very small		     */
+    H5D_CONTIGUOUS = 1, /**< the default				     */
+    H5D_CHUNKED    = 2, /**< slow and fancy			     */
+    H5D_VIRTUAL    = 3, /**< actual data is stored in other datasets     */
+    H5D_NLAYOUTS   = 4  /**< this one must be last!		     */
 } H5D_layout_t;
+//! <!-- [H5D_layout_t_snip] -->
 
-/* Types of chunk index data structures */
+//! <!-- [H5D_chunk_index_t_snip] -->
+/**
+ * Types of chunk index data structures
+ */
 typedef enum H5D_chunk_index_t {
-    H5D_CHUNK_IDX_BTREE = 0, /* v1 B-tree index (default)                */
+    H5D_CHUNK_IDX_BTREE = 0, /**< v1 B-tree index (default)                */
     H5D_CHUNK_IDX_SINGLE =
-        1, /* Single Chunk index (cur dims[]=max dims[]=chunk dims[]; filtered & non-filtered) */
-    H5D_CHUNK_IDX_NONE   = 2, /* Implicit: No Index (H5D_ALLOC_TIME_EARLY, non-filtered, fixed dims) */
-    H5D_CHUNK_IDX_FARRAY = 3, /* Fixed array (for 0 unlimited dims)       */
-    H5D_CHUNK_IDX_EARRAY = 4, /* Extensible array (for 1 unlimited dim)   */
-    H5D_CHUNK_IDX_BT2    = 5, /* v2 B-tree index (for >1 unlimited dims)  */
-    H5D_CHUNK_IDX_NTYPES      /* This one must be last!                   */
+        1, /**< Single Chunk index (cur dims[]=max dims[]=chunk dims[]; filtered & non-filtered) */
+    H5D_CHUNK_IDX_NONE   = 2, /**< Implicit: No Index (#H5D_ALLOC_TIME_EARLY, non-filtered, fixed dims) */
+    H5D_CHUNK_IDX_FARRAY = 3, /**< Fixed array (for 0 unlimited dims)       */
+    H5D_CHUNK_IDX_EARRAY = 4, /**< Extensible array (for 1 unlimited dim)   */
+    H5D_CHUNK_IDX_BT2    = 5, /**< v2 B-tree index (for >1 unlimited dims)  */
+    H5D_CHUNK_IDX_NTYPES      /**< This one must be last!                   */
 } H5D_chunk_index_t;
+//! <!-- [H5D_chunk_index_t_snip] -->
 
-/* Values for the space allocation time property */
+//! <!-- [H5D_alloc_time_t_snip] -->
+/**
+ * Values for the space allocation time property
+ */
 typedef enum H5D_alloc_time_t {
     H5D_ALLOC_TIME_ERROR   = -1,
     H5D_ALLOC_TIME_DEFAULT = 0,
@@ -70,57 +81,84 @@ typedef enum H5D_alloc_time_t {
     H5D_ALLOC_TIME_LATE    = 2,
     H5D_ALLOC_TIME_INCR    = 3
 } H5D_alloc_time_t;
+//! <!-- [H5D_alloc_time_t_snip] -->
 
-/* Values for the status of space allocation */
+//! <!-- [H5D_space_status_t_snip] -->
+/**
+ * Values for the status of space allocation
+ */
 typedef enum H5D_space_status_t {
     H5D_SPACE_STATUS_ERROR          = -1,
     H5D_SPACE_STATUS_NOT_ALLOCATED  = 0,
     H5D_SPACE_STATUS_PART_ALLOCATED = 1,
     H5D_SPACE_STATUS_ALLOCATED      = 2
 } H5D_space_status_t;
+//! <!-- [H5D_space_status_t_snip] -->
 
-/* Values for time of writing fill value property */
+//! <!-- [H5D_fill_time_t_snip] -->
+/**
+ * Values for time of writing fill value property
+ */
 typedef enum H5D_fill_time_t {
     H5D_FILL_TIME_ERROR = -1,
     H5D_FILL_TIME_ALLOC = 0,
     H5D_FILL_TIME_NEVER = 1,
     H5D_FILL_TIME_IFSET = 2
 } H5D_fill_time_t;
+//! <!-- [H5D_fill_time_t_snip] -->
 
-/* Values for fill value status */
+//! <!-- [H5D_fill_value_t_snip] -->
+/**
+ * Values for fill value status
+ */
 typedef enum H5D_fill_value_t {
     H5D_FILL_VALUE_ERROR        = -1,
     H5D_FILL_VALUE_UNDEFINED    = 0,
     H5D_FILL_VALUE_DEFAULT      = 1,
     H5D_FILL_VALUE_USER_DEFINED = 2
 } H5D_fill_value_t;
+//! <!-- [H5D_fill_value_t_snip] -->
 
-/* Values for VDS bounds option */
+//! <!-- [H5D_vds_view_t_snip] -->
+/**
+ * Values for VDS bounds option
+ */
 typedef enum H5D_vds_view_t {
     H5D_VDS_ERROR          = -1,
     H5D_VDS_FIRST_MISSING  = 0,
     H5D_VDS_LAST_AVAILABLE = 1
 } H5D_vds_view_t;
+//! <!-- [H5D_vds_view_t_snip] -->
 
-/* Callback for H5Pset_append_flush() in a dataset access property list */
+//! <!-- [H5D_append_cb_t_snip] -->
+/**
+ * Callback for H5Pset_append_flush() in a dataset access property list
+ */
 typedef herr_t (*H5D_append_cb_t)(hid_t dataset_id, hsize_t *cur_dims, void *op_data);
+//! <!-- [H5D_append_cb_t_snip] -->
 
-/** Define the operator function pointer for H5Diterate() */
-//! [H5D_operator_t_snip]
+//! <!-- [H5D_operator_t_snip] -->
+/**
+ * Define the operator function pointer for H5Diterate()
+ */
 typedef herr_t (*H5D_operator_t)(void *elem, hid_t type_id, unsigned ndim, const hsize_t *point,
                                  void *operator_data);
-//! [H5D_operator_t_snip]
+//! <!-- [H5D_operator_t_snip] -->
 
-/** Define the operator function pointer for H5Dscatter() */
-//! [H5D_scatter_func_t_snip]
+//! <!-- [H5D_scatter_func_t_snip] -->
+/**
+ * Define the operator function pointer for H5Dscatter()
+ */
 typedef herr_t (*H5D_scatter_func_t)(const void **src_buf /*out*/, size_t *src_buf_bytes_used /*out*/,
                                      void *op_data);
-//! [H5D_scatter_func_t_snip]
+//! <!-- [H5D_scatter_func_t_snip] -->
 
-/** Define the operator function pointer for H5Dgather() */
-//! [H5D_gather_func_t_snip]
+//! <!-- [H5D_gather_func_t_snip] -->
+/**
+ * Define the operator function pointer for H5Dgather()
+ */
 typedef herr_t (*H5D_gather_func_t)(const void *dst_buf, size_t dst_buf_bytes_used, void *op_data);
-//! [H5D_gather_func_t_snip]
+//! <!-- [H5D_gather_func_t_snip] -->
 
 /********************/
 /* Public Variables */
@@ -203,26 +241,8 @@ H5_DLL hid_t H5Dcreate2(hid_t loc_id, const char *name, hid_t type_id, hid_t spa
 
 /**
  * --------------------------------------------------------------------------
- * \ingroup H5D
- *
- * \brief Asynchronous version of H5Dcreate2()
- *
- * \app_file
- * \app_func
- * \app_line
- * \fgdta_loc_id
- * \param[in] name      Name of the dataset to create
- * \type_id
- * \space_id
- * \lcpl_id
- * \dcpl_id
- * \dapl_id
- * \es_id
- *
- * \return \hid_t{dataset}
- *
- * \see H5Dcreate2()
- *
+ * \ingroup ASYNC
+ * \async_variant_of{H5Dcreate}
  */
 H5_DLL hid_t H5Dcreate_async(const char *app_file, const char *app_func, unsigned app_line, hid_t loc_id,
                              const char *name, hid_t type_id, hid_t space_id, hid_t lcpl_id, hid_t dcpl_id,
@@ -325,22 +345,8 @@ H5_DLL hid_t H5Dopen2(hid_t loc_id, const char *name, hid_t dapl_id);
 
 /**
  * --------------------------------------------------------------------------
- * \ingroup H5D
- *
- * \brief Asynchronous version of H5Dopen2()
- *
- * \app_file
- * \app_func
- * \app_line
- * \fgdta_loc_id
- * \param[in] name      Name of the dataset to open
- * \dapl_id
- * \es_id
- *
- * \return \hid_t{dataset}
- *
- * \see H5Dopen2()
- *
+ * \ingroup ASYNC
+ * \async_variant_of{H5Dopen}
  */
 H5_DLL hid_t H5Dopen_async(const char *app_file, const char *app_func, unsigned app_line, hid_t loc_id,
                            const char *name, hid_t dapl_id, hid_t es_id);
@@ -370,24 +376,17 @@ H5_DLL hid_t H5Dget_space(hid_t dset_id);
 
 /**
  * --------------------------------------------------------------------------
- * \ingroup H5D
- *
- * \brief Asynchronous version of H5Dget_space()
- *
- * \app_file
- * \app_func
- * \app_line
- * \dset_id
- * \es_id
- *
- * \return \hid_t{dataspace}
- *
- * \see H5Dget_space()
- *
+ * \ingroup ASYNC
+ * \async_variant_of{H5Dget_space}
  */
 H5_DLL hid_t H5Dget_space_async(const char *app_file, const char *app_func, unsigned app_line, hid_t dset_id,
                                 hid_t es_id);
 
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5D
+ * \todo Document this function!
+ */
 H5_DLL herr_t H5Dget_space_status(hid_t dset_id, H5D_space_status_t *allocation);
 
 /**
@@ -614,7 +613,7 @@ H5_DLL herr_t H5Dget_num_chunks(hid_t dset_id, hid_t fspace_id, hsize_t *nchunks
  *          using the coordinates specified by \p offset.
  *
  *          If the queried chunk does not exist in the file, \p size will
- *          be set to 0, \p addr to #HADDR_UNDEF, and the buffer \p
+ *          be set to 0, \p addr to \c HADDR_UNDEF, and the buffer \p
  *          filter_mask will not be modified.
  *
  *          \p offset is a pointer to a one-dimensional array with a size
@@ -649,7 +648,7 @@ H5_DLL herr_t H5Dget_chunk_info_by_coord(hid_t dset_id, const hsize_t *offset, u
  *          specified by the index index. The chunk belongs to a set of
  *          chunks in the selection specified by fspace_id. If the queried
  *          chunk does not exist in the file, the size will be set to 0 and
- *          address to #HADDR_UNDEF. The value pointed to by filter_mask will
+ *          address to \c HADDR_UNDEF. The value pointed to by filter_mask will
  *          not be modified. NULL can be passed in for any \p out parameters.
  *
  *          \p chk_idx is the chunk index in the selection. Index value
@@ -684,7 +683,7 @@ H5_DLL herr_t H5Dget_chunk_info(hid_t dset_id, hid_t fspace_id, hsize_t chk_idx,
  *
  * \dset_id
  *
- * \return Returns the offset in bytes; otherwise, returns #HADDR_UNDEF,
+ * \return Returns the offset in bytes; otherwise, returns \c HADDR_UNDEF,
  *         a negative value.
  *
  * \details H5Dget_offset() returns the address in the file of
@@ -795,25 +794,8 @@ H5_DLL herr_t H5Dread(hid_t dset_id, hid_t mem_type_id, hid_t mem_space_id, hid_
 
 /**
  * --------------------------------------------------------------------------
- * \ingroup H5D
- *
- * \brief Asynchronous version of H5Dread()
- *
- * \app_file
- * \app_func
- * \app_line
- * \dset_id                 Identifier of the dataset to read from
- * \param[in] mem_type_id   Identifier of the memory datatype
- * \param[in] mem_space_id  Identifier of the memory dataspace
- * \param[in] file_space_id Identifier of the dataset's dataspace in the file
- * \param[in] dxpl_id       Identifier of a transfer property list
- * \param[out] buf          Buffer to receive data read from file
- * \es_id
- *
- * \return \herr_t
- *
- * \see H5Dread()
- *
+ * \ingroup ASYNC
+ * \async_variant_of{H5Dread}
  */
 H5_DLL herr_t H5Dread_async(const char *app_file, const char *app_func, unsigned app_line, hid_t dset_id,
                             hid_t mem_type_id, hid_t mem_space_id, hid_t file_space_id, hid_t dxpl_id,
@@ -932,25 +914,8 @@ H5_DLL herr_t H5Dwrite(hid_t dset_id, hid_t mem_type_id, hid_t mem_space_id, hid
 
 /**
  * --------------------------------------------------------------------------
- * \ingroup H5D
- *
- * \brief Asynchronous version of H5Dwrite()
- *
- * \app_file
- * \app_func
- * \app_line
- * \param[in] dset_id        Identifier of the dataset to read from
- * \param[in] mem_type_id    Identifier of the memory datatype
- * \param[in] mem_space_id   Identifier of the memory dataspace
- * \param[in] file_space_id  Identifier of the dataset's dataspace in the file
- * \dxpl_id
- * \param[out] buf           Buffer with data to be written to the file
- * \es_id
- *
- * \return \herr_t
- *
- * \see H5Dwrite()
- *
+ * \ingroup ASYNC
+ * \async_variant_of{H5Dwrite}
  */
 H5_DLL herr_t H5Dwrite_async(const char *app_file, const char *app_func, unsigned app_line, hid_t dset_id,
                              hid_t mem_type_id, hid_t mem_space_id, hid_t file_space_id, hid_t dxpl_id,
@@ -1292,22 +1257,8 @@ H5_DLL herr_t H5Dset_extent(hid_t dset_id, const hsize_t size[]);
 
 /**
  * --------------------------------------------------------------------------
- * \ingroup H5D
- *
- * \brief Asynchronous version of H5Dset_extent()
- *
- * \app_file
- * \app_func
- * \app_line
- * \dset_id
- * \param[in] size[]   Array containing the new magnitude of each dimension
- *                     of the dataset
- * \es_id
- *
- * \return \herr_t
- *
- * \see H5Dset_extent()
- *
+ * \ingroup ASYNC
+ * \async_variant_of{H5Dset_extent}
  */
 H5_DLL herr_t H5Dset_extent_async(const char *app_file, const char *app_func, unsigned app_line,
                                   hid_t dset_id, const hsize_t size[], hid_t es_id);
@@ -1536,20 +1487,8 @@ H5_DLL herr_t H5Dclose(hid_t dset_id);
 
 /**
  * --------------------------------------------------------------------------
- * \ingroup H5D
- *
- * \brief Asynchronous version of H5Dclose()
- *
- * \app_file
- * \app_func
- * \app_line
- * \dset_id
- * \es_id
- *
- * \return \herr_t
- *
- * \see H5Dclose()
- *
+ * \ingroup ASYNC
+ * \async_variant_of{H5Dclose}
  */
 H5_DLL herr_t H5Dclose_async(const char *app_file, const char *app_func, unsigned app_line, hid_t dset_id,
                              hid_t es_id);
@@ -1608,9 +1547,181 @@ H5_DLL herr_t H5Dget_chunk_index_type(hid_t did, H5D_chunk_index_t *idx_type);
 /* Typedefs */
 
 /* Function prototypes */
-H5_DLL hid_t  H5Dcreate1(hid_t loc_id, const char *name, hid_t type_id, hid_t space_id, hid_t dcpl_id);
-H5_DLL hid_t  H5Dopen1(hid_t loc_id, const char *name);
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5D
+ *
+ * \brief Creates a dataset at the specified location
+ *
+ * \fgdta_loc_id
+ * \param[in] name Name of the dataset to create
+ * \type_id
+ * \space_id
+ * \dcpl_id
+ *
+ * \return \hid_t{dataset}
+ *
+ * \deprecated This function is deprecated in favor of the function H5Dcreate2()
+ *             or the macro H5Dcreate().
+ *
+ * \details H5Dcreate1() creates a data set with a name, \p name, in the
+ *          location specified by the identifier \p loc_id. \p loc_id may be a
+ *          file, group, dataset, named datatype or attribute.  If an attribute,
+ *          dataset, or named datatype is specified for \p loc_id then the
+ *          dataset will be created at the location where the attribute,
+ *          dataset, or named datatype is attached.
+ *
+ *          \p name can be a relative path based at \p loc_id or an absolute
+ *          path from the root of the file. Use of this function requires that
+ *          any intermediate groups specified in the path already exist.
+ *
+ *          The dataset’s datatype and dataspace are specified by \p type_id and
+ *          \p space_id, respectively. These are the datatype and dataspace of
+ *          the dataset as it will exist in the file, which may differ from the
+ *          datatype and dataspace in application memory.
+ *
+ *          Names within a group are unique: H5Dcreate1() will return an error
+ *          if a link with the name specified in name already exists at the
+ *          location specified in \p loc_id.
+ *
+ *          As is the case for any object in a group, the length of a dataset
+ *          name is not limited.
+ *
+ *          \p dcpl_id is an #H5P_DATASET_CREATE property list created with \p
+ *          H5reate1() and initialized with various property list functions
+ *          described in Property List Interface.
+ *
+ *          H5Dcreate() and H5Dcreate_anon() return an error if the dataset’s
+ *          datatype includes a variable-length (VL) datatype and the fill value
+ *          is undefined, i.e., set to \c NULL in the dataset creation property
+ *          list. Such a VL datatype may be directly included, indirectly
+ *          included as part of a compound or array datatype, or indirectly
+ *          included as part of a nested compound or array datatype.
+ *
+ *          H5Dcreate() and H5Dcreate_anon() return a dataset identifier for
+ *          success or a negative value for failure. The dataset identifier
+ *          should eventually be closed by calling H5Dclose() to release
+ *          resources it uses.
+ *
+ *          See H5Dcreate_anon() for discussion of the differences between
+ *          H5Dcreate() and H5Dcreate_anon().
+ *
+ *          The HDF5 library provides flexible means of specifying a fill value,
+ *          of specifying when space will be allocated for a dataset, and of
+ *          specifying when fill values will be written to a dataset.
+ *
+ * \version 1.8.0 Function H5Dcreate() renamed to H5Dcreate1() and deprecated in this release.
+ * \since 1.0.0
+ *
+ * \see H5Dopen2(), H5Dclose(), H5Tset_size()
+ *
+ */
+H5_DLL hid_t H5Dcreate1(hid_t loc_id, const char *name, hid_t type_id, hid_t space_id, hid_t dcpl_id);
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5D
+ *
+ * \brief Opens an existing dataset
+ *
+ * \fgdta_loc_id
+ * \param[in] name Name of the dataset to access
+ *
+ * \return \hid_t{dataset}
+ *
+ * \deprecated This function is deprecated in favor of the function H5Dopen2()
+ *             or the macro H5Dopen().
+ *
+ * \details H5Dopen1() opens an existing dataset for access at the location
+ *          specified by \p loc_id.  \p loc_id may be a file, group, dataset,
+ *          named datatype or attribute.  If an attribute, dataset, or named
+ *          datatype is specified for loc_id then the dataset will be opened at
+ *          the location where the attribute, dataset, or named datatype is
+ *          attached. name is a dataset name and is used to identify the dataset
+ *          in the file.
+ *
+ *          A dataset opened with this function should be closed with H5Dclose()
+ *          when the dataset is no longer needed so that resource leaks will not
+ *          develop.
+ *
+ * \version 1.8.0 Function H5Dopen() renamed to H5Dopen1() and deprecated in this release.
+ * \since 1.0.0
+ *
+ */
+H5_DLL hid_t H5Dopen1(hid_t loc_id, const char *name);
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5D
+ *
+ * \brief Extends a dataset
+ *
+ * \dset_id
+ * \param[in] size Array containing the new size of each dimension
+ *
+ * \return \herr_t
+ *
+ * \deprecated This function is deprecated in favor of the function H5Dset_extent().
+ *
+ * \details H5Dextend() verifies that the dataset is at least of size \p size,
+ *          extending it if necessary. The dimensionality of size is the same as
+ *          that of the dataspace of the dataset being changed.
+ *
+ *          This function can be applied to the following datasets:
+ *          \li Any dataset with unlimited dimensions
+ *          \li A dataset with fixed dimensions if the current dimension sizes
+ *              are less than the maximum sizes set with \c maxdims
+ *              (see H5Screate_simple())
+ *
+ *          Space on disk is immediately allocated for the new dataset extent if
+ *          the dataset’s space allocation time is set to
+ *          #H5D_ALLOC_TIME_EARLY. Fill values will be written to the dataset if
+ *          the dataset’s fill time is set to #H5D_FILL_TIME_IFSET or
+ *          #H5D_FILL_TIME_ALLOC. (See H5Pset_fill_time() and
+ *          H5Pset_alloc_time().)
+ *
+ *          This function ensures that the dataset dimensions are of at least
+ *          the sizes specified in size. The function H5Dset_extent() must be
+ *          used if the dataset dimension sizes are are to be reduced.
+ *
+ * \version 1.8.0 Function Function deprecated in this release. Parameter size
+ *                syntax changed to \Code{const hsize_t size[]} in this release.
+ *
+ */
 H5_DLL herr_t H5Dextend(hid_t dset_id, const hsize_t size[]);
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5D
+ *
+ * \brief Reclaims variable-length (VL) datatype memory buffers
+ *
+ * \type_id
+ * \space_id
+ * \dxpl_id
+ * \param[in] buf Pointer to the buffer to be reclaimed
+ *
+ * \return \herr_t
+ *
+ * \deprecated This function has been deprecated in HDF5-1.12 in favor of the
+ *             function H5Treclaim().
+ *
+ * \details H5Dvlen_reclaim() reclaims memory buffers created to store VL
+ *          datatypes.
+ *
+ *          The \p type_id must be the datatype stored in the buffer. The \p
+ *          space_id describes the selection for the memory buffer to free the
+ *          VL datatypes within. The \p dxpl_id is the dataset transfer property
+ *          list which was used for the I/O transfer to create the buffer. And
+ *          \p buf is the pointer to the buffer to be reclaimed.
+ *
+ *          The VL structures (\ref hvl_t) in the user's buffer are modified to
+ *          zero out the VL information after the memory has been reclaimed.
+ *
+ *          If nested VL datatypes were used to create the buffer, this routine
+ *          frees them from the bottom up, releasing all the memory without
+ *          creating memory leaks.
+ *
+ * \version 1.12.0 Routine was deprecated
+ *
+ */
 H5_DLL herr_t H5Dvlen_reclaim(hid_t type_id, hid_t space_id, hid_t dxpl_id, void *buf);
 
 #endif /* H5_NO_DEPRECATED_SYMBOLS */