RM blocks for H5R (#219)

* Transferred RM blocks in H5D and H5G to develop

* Added RM blocks to H5R and added new aliases.

Co-authored-by: Larry Knox <lrknox@hdfgroup.org>

4 files changed, 749 insertions, 8 deletions

diff --git a/src/H5Dpublic.h b/src/H5Dpublic.h
index 00948f9..8d0ef30 100644
--- a/src/H5Dpublic.h
+++ b/src/H5Dpublic.h
@@ -140,7 +140,7 @@ extern "C" {
  * \brief Creates a new dataset and links it into the file
  *
  * \fgdta_loc_id
- * \param[in] name      Name of the dataset to open
+ * \param[in] name      Name of the dataset to create
  * \type_id
  * \space_id
  * \lcpl_id
@@ -149,7 +149,6 @@ extern "C" {
  *
  * \return \hid_t{dataset}
  *
- *
  * \details H5Dcreate2() creates a new dataset named \p name at
  *          the location specified by \p loc_id, and associates constant
  *          and initial persistent properties with that dataset, including
@@ -201,6 +200,30 @@ extern "C" {
  */
 H5_DLL hid_t  H5Dcreate2(hid_t loc_id, const char *name, hid_t type_id, hid_t space_id, hid_t lcpl_id,
                          hid_t dcpl_id, hid_t dapl_id);
+
+/**
+ * --------------------------------------------------------------------------
+ * \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()
+ *
+ */
 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,
                               hid_t dapl_id, hid_t es_id);
@@ -299,6 +322,26 @@ H5_DLL hid_t  H5Dcreate_anon(hid_t loc_id, hid_t type_id, hid_t space_id, hid_t
  *
  */
 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()
+ *
+ */
 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);
 
@@ -324,6 +367,24 @@ H5_DLL hid_t  H5Dopen_async(const char *app_file, const char *app_func, unsigned
  *
  */
 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()
+ *
+ */
 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);
 
@@ -732,6 +793,28 @@ H5_DLL haddr_t H5Dget_offset(hid_t dset_id);
 H5_DLL herr_t  H5Dread(hid_t dset_id, hid_t mem_type_id, hid_t mem_space_id, hid_t file_space_id,
                        hid_t dxpl_id, void *buf /*out*/);
 
+/**
+ * --------------------------------------------------------------------------
+ * \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()
+ *
+ */
 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,
                              void *buf /*out*/, hid_t es_id);
@@ -847,6 +930,28 @@ H5_DLL herr_t  H5Dread_async(const char *app_file, const char *app_func, unsigne
 H5_DLL herr_t  H5Dwrite(hid_t dset_id, hid_t mem_type_id, hid_t mem_space_id, hid_t file_space_id,
                         hid_t dxpl_id, const void *buf);
 
+/**
+ * --------------------------------------------------------------------------
+ * \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()
+ *
+ */
 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,
                               const void *buf, hid_t es_id);
@@ -1184,6 +1289,26 @@ H5_DLL herr_t  H5Dfill(const void *fill, hid_t fill_type_id, void *buf, hid_t bu
  *
  */
 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()
+ *
+ */
 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);
 
@@ -1408,6 +1533,24 @@ H5_DLL herr_t  H5Dgather(hid_t src_space_id, const void *src_buf, hid_t type_id,
  *
  */
 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()
+ *
+ */
 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);
 
diff --git a/src/H5Gpublic.h b/src/H5Gpublic.h
index e46bef6..26617d3 100644
--- a/src/H5Gpublic.h
+++ b/src/H5Gpublic.h
@@ -118,6 +118,28 @@ extern "C" {
  *
  */
 H5_DLL hid_t  H5Gcreate2(hid_t loc_id, const char *name, hid_t lcpl_id, hid_t gcpl_id, hid_t gapl_id);
+
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5G
+ *
+ * \brief Asynchronous version of H5Gcreate2()
+ *
+ * \app_file
+ * \app_func
+ * \app_line
+ * \fgdta_loc_id
+ * \param[in] name      Name of the group to create
+ * \lcpl_id
+ * \gcpl_id
+ * \gapl_id
+ * \es_id
+ *
+ * \return \hid_t{group}
+ *
+ * \see H5Gcreate2()
+ *
+ */
 H5_DLL hid_t  H5Gcreate_async(const char *app_file, const char *app_func, unsigned app_line, hid_t loc_id,
                               const char *name, hid_t lcpl_id, hid_t gcpl_id, hid_t gapl_id, hid_t es_id);
 
@@ -199,6 +221,26 @@ H5_DLL hid_t  H5Gcreate_anon(hid_t loc_id, hid_t gcpl_id, hid_t gapl_id);
  *
  */
 H5_DLL hid_t  H5Gopen2(hid_t loc_id, const char *name, hid_t gapl_id);
+
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5G
+ *
+ * \brief Asynchronous version of H5Gopen2()
+ *
+ * \app_file
+ * \app_func
+ * \app_line
+ * \fgdta_loc_id
+ * \param[in] name      Name of the group to open
+ * \gapl_id
+ * \es_id
+ *
+ * \return \hid_t{group}
+ *
+ * \see H5Gopen2()
+ *
+ */
 H5_DLL hid_t  H5Gopen_async(const char *app_file, const char *app_func, unsigned app_line, hid_t loc_id,
                             const char *name, hid_t gapl_id, hid_t es_id);
 
@@ -253,8 +295,26 @@ H5_DLL hid_t  H5Gget_create_plist(hid_t group_id);
  */
 H5_DLL herr_t H5Gget_info(hid_t loc_id, H5G_info_t *ginfo);
 
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5G
+ *
+ * \brief Asynchronous version of H5Gget_info()
+ *
+ * \app_file
+ * \app_func
+ * \app_line
+ * \fgdta_loc_id
+ * \param[out] ginfo Struct in which group information is returned
+ * \es_id
+ *
+ * \return \hid_t{group}
+ *
+ * \see H5Gget_info()
+ *
+ */
 H5_DLL herr_t H5Gget_info_async(const char *app_file, const char *app_func, unsigned app_line, hid_t loc_id,
-                                H5G_info_t *group_info /*out*/, hid_t es_id);
+                                H5G_info_t *ginfo /*out*/, hid_t es_id);
 
 /**
  *-------------------------------------------------------------------------
@@ -289,8 +349,29 @@ H5_DLL herr_t H5Gget_info_async(const char *app_file, const char *app_func, unsi
  *
  */
 H5_DLL herr_t H5Gget_info_by_name(hid_t loc_id, const char *name, H5G_info_t *ginfo, hid_t lapl_id);
+
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5G
+ *
+ * \brief Asynchronous version of H5Gget_info_by_name()
+ *
+ * \app_file
+ * \app_func
+ * \app_line
+ * \fgdta_loc_id
+ * \param[in] name      Name of the group to query
+ * \param[out] ginfo Struct in which group information is returned
+ * \lapl_id
+ * \es_id
+ *
+ * \return \herr_t
+ *
+ * \see H5Gget_info_by_name()
+ *
+ */
 H5_DLL herr_t H5Gget_info_by_name_async(const char *app_file, const char *app_func, unsigned app_line,
-                                        hid_t loc_id, const char *name, H5G_info_t *group_info /*out*/,
+                                        hid_t loc_id, const char *name, H5G_info_t *ginfo /*out*/,
                                         hid_t lapl_id, hid_t es_id);
 
 /**
@@ -340,9 +421,36 @@ H5_DLL herr_t H5Gget_info_by_name_async(const char *app_file, const char *app_fu
  */
 H5_DLL herr_t H5Gget_info_by_idx(hid_t loc_id, const char *group_name, H5_index_t idx_type,
                                  H5_iter_order_t order, hsize_t n, H5G_info_t *ginfo, hid_t lapl_id);
+
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5G
+ *
+ * \brief Asynchronous version of H5Gcreate2()
+ *
+ * \app_file
+ * \app_func
+ * \app_line
+ * \fgdta_loc_id
+ * \param[in] group_name Name of the group to query
+ * \param[in] idx_type   Transient index identifying object
+ * \param[in] order      Transient index identifying object
+ * \param[in] n          Position in the index of the group to query
+ * \param[out] ginfo     Struct in which group information is returned
+ * \lapl_id
+ * \es_id
+ *
+ * \return Returns
+ *      \li The size of the object name if successful, or
+ *      \li 0 if no name is associated with the group identifier, or
+ *      \li negative value, if failure occurred
+ *
+ * \see H5Gcreate2()
+ *
+ */
 H5_DLL herr_t H5Gget_info_by_idx_async(const char *app_file, const char *app_func, unsigned app_line,
                                        hid_t loc_id, const char *group_name, H5_index_t idx_type,
-                                       H5_iter_order_t order, hsize_t n, H5G_info_t *group_info /*out*/,
+                                       H5_iter_order_t order, hsize_t n, H5G_info_t *ginfo /*out*/,
                                        hid_t lapl_id, hid_t es_id);
 
 /**
@@ -422,6 +530,24 @@ H5_DLL herr_t H5Grefresh(hid_t group_id);
  *
  */
 H5_DLL herr_t H5Gclose(hid_t group_id);
+
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5G
+ *
+ * \brief Asynchronous version of H5Gcreate2()
+ *
+ * \app_file
+ * \app_func
+ * \app_line
+ * \group_id
+ * \es_id
+ *
+ * \return \herr_t
+ *
+ * \see H5Gcreate2()
+ *
+ */
 H5_DLL herr_t H5Gclose_async(const char *app_file, const char *app_func, unsigned app_line, hid_t group_id,
                              hid_t es_id);
 
diff --git a/src/H5Rmodule.h b/src/H5Rmodule.h
index e4f5313..0a910a1 100644
--- a/src/H5Rmodule.h
+++ b/src/H5Rmodule.h
@@ -25,4 +25,11 @@
 #define H5_MY_PKG_ERR  H5E_REFERENCE
 #define H5_MY_PKG_INIT YES
 
+/**
+ * \defgroup H5R H5R
+ * \brief Reference Interface
+ * \details The HDF5 Reference Interface, H5R, provides a mechanism for managing
+ *          HDF5 referenced objects.
+ */
+
 #endif /* _H5Rmodule_H */
diff --git a/src/H5Rpublic.h b/src/H5Rpublic.h
index b2803de..96db2a7 100644
--- a/src/H5Rpublic.h
+++ b/src/H5Rpublic.h
@@ -99,36 +99,501 @@ extern "C" {
 #endif
 
 /* Constructors */
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5R
+ *
+ * \brief Creates an object reference
+ *
+ * \fgdta_loc_id
+ * \param[in] name      Name of object
+ * \oapl_id
+ * \param[out] ref_ptr  Pointer to reference
+ *
+ * \return \herr_t
+ *
+ * \details H5Rcreate_object() creates a reference pointing to the
+ *          object named \p name located at \p loc_id. The parameters \p
+ *          loc_id and \p name are used to locate the object.
+ *
+ *          The parameter \p oapl_id is an object access property list
+ *          identifier for the referenced object. The access property list
+ *          must be of the same type as the object being referenced, that is
+ *          a group, dataset or committed datatype property list.
+ *
+ *          H5R_ref_t is defined in H5Rpublic.h as:   typedef unsigned char
+ *          H5R_ref_t[#H5R_REF_BUF_SIZE];
+ *
+ *          H5Rdestroy() should be used to release the resource from the
+ *          reference.
+ *
+ */
 H5_DLL herr_t H5Rcreate_object(hid_t loc_id, const char *name, hid_t oapl_id, H5R_ref_t *ref_ptr);
+
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5R
+ *
+ * \brief Creates a region reference
+ *
+ * \fgdta_loc_id
+ * \param[in] name      Name of object
+ * \space_id
+ * \oapl_id
+ * \param[out] ref_ptr  Pointer to reference
+ *
+ * \return \herr_t
+ *
+ * \details H5Rcreate_region() creates the reference, \p ref_ptr,
+ *          pointing to the region represented by \p space_id within the
+ *          object named name located at \p loc_id.
+ *
+ *          The parameters \p loc_id and \p name are used to locate the
+ *          object. The parameter \p space_id identifies the dataset region
+ *          that a dataset region reference points to.
+ *
+ *          The parameter \p oapl_id is an object access property list
+ *          identifier for the referenced object. The access property list
+ *          must be of the same type as the object being referenced, that is
+ *          a dataset property list in this case.
+ *
+ *          H5R_ref_t is defined in H5Rpublic.h as:   typedef unsigned char
+ *          H5R_ref_t[#H5R_REF_BUF_SIZE];
+ *
+ *          H5Rdestroy() should be used to release the resource from the
+ *          reference.
+ *
+ * \see function_name()
+ *
+ */
 H5_DLL herr_t H5Rcreate_region(hid_t loc_id, const char *name, hid_t space_id, hid_t oapl_id,
                                H5R_ref_t *ref_ptr);
+
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5R
+ *
+ * \brief Creates an attribute reference
+ *
+ * \fgdta_loc_id
+ * \param[in] name      Name of object
+ * \param[in] attr_name Name of attribute
+ * \oapl_id
+ * \param[out] ref_ptr  Pointer to reference
+ *
+ * \return \herr_t
+ *
+ * \details H5Rcreate_attr() creates the reference, \p ref_ptr, pointing
+ *          to the attribute named \p attr_name and attached to the object
+ *          named \p name located at \p loc_id.
+ *
+ *          The parameters \p loc_id and \p name locate the object. The
+ *          parameter \p attr_name specifies the attribute within the object.
+ *
+ *          The parameter \p oapl_id is an object access property list
+ *          identifier for the object that the referenced attribute is
+ *          attached to. The access property list must be of the same type
+ *          as that object, that is a group, dataset or committed datatype
+ *          property list.
+ *
+ *          H5R_ref_t is defined in H5Rpublic.h as:   typedef unsigned char
+ *          H5R_ref_t[#H5R_REF_BUF_SIZE];
+ *
+ *          H5Rdestroy() should be used to release the resource from the
+ *          reference.
+ *
+ */
 H5_DLL herr_t H5Rcreate_attr(hid_t loc_id, const char *name, const char *attr_name, hid_t oapl_id,
                              H5R_ref_t *ref_ptr);
+
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5R
+ *
+ * \brief Closes a reference
+ *
+ * \param[in] ref_ptr  Pointer to reference
+ *
+ * \return \herr_t
+ *
+ * \details Given a reference, ref_ptr, to an object, region or attribute
+ *          attached to an object, H5R_DESTROY releases allocated resources
+ *          from a previous create call.
+ *
+ *          H5R_ref_t is defined in H5Rpublic.h as: typedef unsigned char
+ *          H5R_ref_t[#H5R_REF_BUF_SIZE];
+ *
+ */
 H5_DLL herr_t H5Rdestroy(H5R_ref_t *ref_ptr);
 
 /* Info */
+
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5R
+ *
+ * \brief Retrieves the type of a reference
+ *
+ * \param[in] ref_ptr  Pointer to reference
+ *
+ * \return Returns a valid reference type if successful; otherwise returns #H5R_UNKNOWN.
+ *
+ * \details Given a reference, \p ref_ptr, H5Rget_type() returns the
+ *          type of the reference.
+ *
+ *          Valid returned reference types are:
+ *
+ *          #H5R_OBJECT2 Object reference version 2
+ *          #H5R_DATASET_REGION2 Region reference version 2
+ *          #H5R_ATTRIBUTE   Attribute reference
+ *
+ *          Note that #H5R_OBJECT1 and #H5R_DATASET REGION1 can never be
+ *          associated to an H5R_ref_t reference and can therefore never be
+ *          returned through that function.
+ *
+ *          H5R_ref_t is defined in H5Rpublic.h as:   typedef unsigned char
+ *          H5R_ref_t[#H5R_REF_BUF_SIZE];
+ *
+ */
 H5_DLL H5R_type_t H5Rget_type(const H5R_ref_t *ref_ptr);
+
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5R
+ *
+ * \brief Determines whether two references are equal
+ *
+ * \param[in]  ref1_ptr  Pointer to reference to compare
+ * \param[in]  ref2_ptr  Pointer to reference to compare
+ *
+ * \return Returns a positive value if the references are equal. Returns
+ *          0 if the references are not equal. Returns a negative value when the
+ *          function fails.
+ *
+ * \details H5Requal() determines whether two references point to the
+ *          same object, region or attribute.
+ *
+ *          H5R_ref_t is defined in H5Rpublic.h as: typedef unsigned char
+ *          H5R_ref_t[#H5R_REF_BUF_SIZE];
+ *
+ */
 H5_DLL htri_t     H5Requal(const H5R_ref_t *ref1_ptr, const H5R_ref_t *ref2_ptr);
+
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5R
+ *
+ * \brief Copies an existing reference
+ *
+ * \param[in]  src_ref_ptr  Pointer to reference to copy
+ * \param[out] dst_ref_ptr  Pointer to output reference
+ *
+ * \return \herr_t
+ *
+ * \details H5Rcopy() creates a copy of an existing reference.
+ *          \p src_ref_ptr points to the reference to copy and \p dst_ref_ptr is the
+ *          pointer to the destination reference.
+ *
+ */
 H5_DLL herr_t     H5Rcopy(const H5R_ref_t *src_ref_ptr, H5R_ref_t *dst_ref_ptr);
 
 /* Dereference */
+
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5R
+ *
+ * \brief Opens the HDF5 object referenced
+ *
+ * \param[in] ref_ptr  Pointer to reference to open
+ * \rapl_id
+ * \oapl_id
+ *
+ * \return \hid_t{object}
+ *
+ * \details Given a reference, \p ref_ptr, to an object, a region in
+ *          an object, or an attribute attached to an object, H5Ropen_object()
+ *          opens that object and returns an identifier.
+ *
+ *          The parameter \p oapl_id is an object access property list
+ *          identifier for the referenced object. The access property list
+ *          must be of the same type as the object being referenced, that is
+ *          a group or dataset property list.
+ *
+ *          H5R_ref_t is defined in H5Rpublic.h as:   typedef unsigned char
+ *          H5R_ref_t[#H5R_REF_BUF_SIZE];
+ *
+ *          The object opened with this function should be closed when it
+ *          is no longer needed so that resource leaks will not develop. Use
+ *          the appropriate close function such as H5Oclose() or H5Dclose()
+ *          for datasets.
+ *
+ */
 H5_DLL hid_t H5Ropen_object(H5R_ref_t *ref_ptr, hid_t rapl_id, hid_t oapl_id);
+
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5R
+ *
+ * \brief Asynchronous version of H5Ropen_object()
+ *
+ * \app_file
+ * \app_func
+ * \app_line
+ * \param[out] ref_ptr  Pointer to reference to open
+ * \rapl_id
+ * \oapl_id
+ * \es_id
+ *
+ * \return \hid_t{object}
+ *
+ * \see H5Ropen_object()
+ *
+ */
 H5_DLL hid_t H5Ropen_object_async(const char *app_file, const char *app_func, unsigned app_line,
                                   H5R_ref_t *ref_ptr, hid_t rapl_id, hid_t oapl_id, hid_t es_id);
+
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5R
+ *
+ * \brief Sets up a dataspace and selection as specified by a region reference.
+ *
+ * \param[in] ref_ptr  Pointer to reference to open
+ * \rapl_id
+ * \oapl_id
+ *
+ * \return \hid_t{dataspace}
+ *
+ * \details H5Ropen_region() creates a copy of the dataspace of the
+ *          dataset pointed to by a region reference, \p ref_ptr, and defines
+ *          a selection matching the selection pointed to by \p ref_ptr within
+ *          the dataspace copy.
+ *
+ *          The parameter \p rapl id is a reference access property list
+ *          identifier for the reference. The access property list can
+ *          be used to access external files that the reference points to
+ *          (through a file access property list).
+ *
+ *          The parameter \p oapl id is an object access property list
+ *          identifier for the referenced object. The access property list
+ *          must be of the same type as the object being referenced, that is
+ *          a dataset property list in that case.
+ *
+ *          Use H5Sclose() to release the dataspace identifier returned by
+ *          this function when the identifier is no longer needed.
+ *
+ */
 H5_DLL hid_t H5Ropen_region(H5R_ref_t *ref_ptr, hid_t rapl_id, hid_t oapl_id);
+
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5R
+ *
+ * \brief Asynchronous version of H5Ropen_region()
+ *
+ * \app_file
+ * \app_func
+ * \app_line
+ * \param[in] ref_ptr  Pointer to reference to open
+ * \rapl_id
+ * \oapl_id
+ * \es_id
+ *
+ * \return \hid_t{dataspace}
+ *
+ * \see H5Ropen_region()
+ *
+ */
 H5_DLL hid_t H5Ropen_region_async(const char *app_file, const char *app_func, unsigned app_line,
                                   H5R_ref_t *ref_ptr, hid_t rapl_id, hid_t oapl_id, hid_t es_id);
+
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5R
+ *
+ * \brief Opens the HDF5 attribute referenced
+ *
+ * \param[in] ref_ptr  Pointer to reference to open
+ * \rapl_id
+ * \aapl_id
+ *
+ * \return \hid_t{attribute}
+ *
+ * \details Given a reference, \p ref_ptr, to an attribute attached to
+ *          an object, H5Ropen_attr() opens the attribute attached to that
+ *          object and returns an identifier.
+ *
+ *          The parameter \p rapl id is a reference access property list
+ *          identifier for the reference. The access property list can
+ *          be used to access external files that the reference points to
+ *          (through a file access property list).
+ *
+ *          The parameter \p aapl_id is an attribute access property list
+ *          identifier for the referenced attribute.
+ *
+ *          The attribute opened with this function should be closed with
+ *          H5Aclose() when it is no longer needed.
+ *
+ */
 H5_DLL hid_t H5Ropen_attr(H5R_ref_t *ref_ptr, hid_t rapl_id, hid_t aapl_id);
+
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5R
+ *
+ * \brief Asynchronous version of H5Ropen_attr()
+ *
+ * \app_file
+ * \app_func
+ * \app_line
+ * \param[in] ref_ptr  Pointer to reference to open
+ * \rapl_id
+ * \aapl_id
+ * \es_id
+ *
+ * \return \hid_t{attribute}
+ *
+ * \see H5Ropen_attr()
+ *
+ */
 H5_DLL hid_t H5Ropen_attr_async(const char *app_file, const char *app_func, unsigned app_line,
                                 H5R_ref_t *ref_ptr, hid_t rapl_id, hid_t aapl_id, hid_t es_id);
 
 /* Get type */
+
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5R
+ *
+ * \brief Retrieves the type of object that an object reference points to
+ *
+ * \param[in] ref_ptr  Pointer to reference to query
+ * \rapl_id
+ * \param[out] obj_type Type of referenced object
+ *
+ * \return \herr_t
+ *
+ * \details Given a reference, \p ref_ptr, H5Rget_obj_type3() retrieves
+ *          the type of the referenced object in \p obj_type.
+ *
+ *          The parameter \p rapl id is a reference access property list
+ *          identifier for the reference. The access property list can
+ *          be used to access external files that the reference points to
+ *          (through a file access property list).
+ *
+ *          Upon success, the function returns in \p obj_type the type of
+ *          the object that the reference points to.  Valid values for this
+ *          referenced object type are as followed (defined in H5Opublic.h):
+ *
+ *          H5O_TYPE_GROUP  Object is a group
+ *          H5O_TYPE_DATASET    Object is a dataset
+ *          H5O_TYPE_NAMED_DATATYPE Object is a named datatype
+ *
+ */
 H5_DLL herr_t H5Rget_obj_type3(H5R_ref_t *ref_ptr, hid_t rapl_id, H5O_type_t *obj_type);
 
 /* Get name */
-H5_DLL ssize_t H5Rget_file_name(const H5R_ref_t *ref_ptr, char *buf, size_t size);
-H5_DLL ssize_t H5Rget_obj_name(H5R_ref_t *ref_ptr, hid_t rapl_id, char *buf, size_t size);
-H5_DLL ssize_t H5Rget_attr_name(const H5R_ref_t *ref_ptr, char *buf, size_t size);
+
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5R
+ *
+ * \brief Retrieves the file name for a referenced object
+ *
+ * \param[in] ref_ptr  Pointer to reference to query
+ * \param[in,out] name Buffer to place the file name of the reference
+ * \param[in] size     Size of the \p name buffer
+ *
+ * \return Returns the length of the name if successful, otherwise, a negative value.
+ *
+ * \details H5Rget_file_name() retrieves the file name for the object,
+ *          region or attribute reference pointed to by \p ref_ptr.
+ *
+ *          Up to \p size characters of the name are returned in \p name;
+ *          additional characters, if any, are not returned to the user
+ *          application. If the length of the name, which determines
+ *          the required value of size, is unknown, a preliminary
+ *          H5Rget_file_name() call can be made. The return value of this
+ *          call will be the size of the file name. That value can then be
+ *          passed in for size in the second call to H5Rget_file_name(),
+ *          which will retrieve the actual name.
+ *
+ */
+H5_DLL ssize_t H5Rget_file_name(const H5R_ref_t *ref_ptr, char *name, size_t size);
+
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5R
+ *
+ * \brief Retrieves the object name for a referenced object
+ *
+ * \param[in] ref_ptr  Pointer to reference to query
+ * \rapl_id
+ * \param[in,out] name Buffer to place the file name of the reference
+ * \param[in] size     Size of the \p name buffer
+ *
+ * \return Returns the length of the name if successful, returning
+ *          0 (zero) if no name is associated with the identifier. Otherwise
+ *          returns a negative value.
+ *
+ * \details H5Rget_obj_name() retrieves the object name for the object,
+ *          region or attribute reference pointed to by \p ref_ptr.
+ *
+ *          The parameter \p rapl id is a reference access property list
+ *          identifier for the reference. The access property list can
+ *          be used to access external files that the reference points to
+ *          (through a file access property list).
+ *
+ *          Up to size characters of the name are returned in name; additional
+ *          characters, if any, are not returned to the user application. If
+ *          the length of the name, which determines the required value of
+ *          \p size, is unknown, a preliminary call to H5Rget_obj_name() call
+ *          can be made. The return value of this call will be the size of the
+ *          object name. That value can then be passed in for \p size in the
+ *          second call to H5Rget_obj_name(), which will retrieve the actual
+ *          name. If there is no name associated with the object identifier
+ *          or if the name is #NULL, H5Rget_obj_name() returns the size of
+ *          the name buffer (the size does not include the #NULL terminator).
+ *
+ *          If \p ref_ptr is an object reference, \p name will be returned with
+ *          a name for the referenced object. If \p ref_ptr is a dataset region
+ *          reference, \p name will contain a name for the object containing
+ *          the referenced region. If \p ref_ptr is an attribute reference, \p
+ *          name will contain a name for the object the attribute is attached
+ *          to. Note that an object in an HDF5 file may have multiple paths
+ *          if there are multiple links pointing to it. This function may
+ *          return any one of these paths.
+ *
+ */
+H5_DLL ssize_t H5Rget_obj_name(H5R_ref_t *ref_ptr, hid_t rapl_id, char *name, size_t size);
+
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5R
+ *
+ * \brief Retrieves the attribute name for a referenced object
+ *
+ * \param[in] ref_ptr  Pointer to reference to query
+ * \param[in,out] name Buffer to place the attribute name of the reference
+ * \param[in] size     Size of the \p name buffer
+ *
+ * \return Returns the length of the name if successful, otherwise, a negative value.
+ *
+ * \details H5Rget_attr_name() retrieves the attribute name for the
+ *          attribute reference pointed to by \p ref_ptr.
+ *
+ *          Up to size characters of the name are returned in \p name;
+ *          additional characters, if any, are not returned to the user
+ *          application. If the length of the name, which determines
+ *          the required value of \p size, is unknown, a preliminary
+ *          H5Rget_attr_name() call can be made. The return value of this
+ *          call will be the size of the attribute name. That value can then
+ *          be passed in for size in the second call to H5Rget_attr_name(),
+ *          which will retrieve the actual name.
+ *
+ */
+H5_DLL ssize_t H5Rget_attr_name(const H5R_ref_t *ref_ptr, char *name, size_t size);
 
 /* API Wrappers for async routines */
 /* (Must be defined _after_ the function prototype) */