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, 388 insertions, 104 deletions

diff --git a/src/H5Rpublic.h b/src/H5Rpublic.h
index 5d356e9..b33960e 100644
--- a/src/H5Rpublic.h
+++ b/src/H5Rpublic.h
@@ -40,40 +40,54 @@
 /* Public Typedefs */
 /*******************/
 
-/*
+//! <!-- [H5R_type_t_snip] -->
+/**
  * Reference types allowed.
- * DO NOT CHANGE THE ORDER or VALUES as reference type values are encoded into
- * the datatype message header.
+ *
+ * \internal DO NOT CHANGE THE ORDER or VALUES as reference type values are
+ *           encoded into the datatype message header.
  */
 typedef enum {
-    H5R_BADTYPE         = (-1), /* Invalid reference type           */
-    H5R_OBJECT1         = 0,    /* Backward compatibility (object)  */
-    H5R_DATASET_REGION1 = 1,    /* Backward compatibility (region)  */
-    H5R_OBJECT2         = 2,    /* Object reference                 */
-    H5R_DATASET_REGION2 = 3,    /* Region reference                 */
-    H5R_ATTR            = 4,    /* Attribute Reference              */
-    H5R_MAXTYPE         = 5     /* Highest type (invalid)           */
+    H5R_BADTYPE         = (-1), /**< Invalid reference type           */
+    H5R_OBJECT1         = 0,    /**< Backward compatibility (object)  */
+    H5R_DATASET_REGION1 = 1,    /**< Backward compatibility (region)  */
+    H5R_OBJECT2         = 2,    /**< Object reference                 */
+    H5R_DATASET_REGION2 = 3,    /**< Region reference                 */
+    H5R_ATTR            = 4,    /**< Attribute Reference              */
+    H5R_MAXTYPE         = 5     /**< Highest type (invalid)           */
 } H5R_type_t;
+//! <!-- [H5R_type_t_snip] -->
 
 /* Deprecated types are kept for backward compatibility with previous versions */
 
+//! <!-- [hobj_ref_t_snip] -->
 /**
- * Deprecated object reference type that is used with deprecated reference APIs.
- * Note! This type can only be used with the "native" HDF5 VOL connector.
+ * \deprecated Deprecated object reference type that is used with deprecated
+ *             reference APIs.
+ *
+ * \note This type can only be used with the "native" HDF5 VOL connector.
  */
 typedef haddr_t hobj_ref_t;
+//! <!-- [hobj_ref_t_snip] -->
 
+//! <!-- [hdset_reg_ref_t_snip] -->
 /**
- * Dataset region reference type that is used with deprecated reference APIs.
- * (Buffer to store heap ID and index)
- * This needs to be large enough to store largest haddr_t in a worst case
+ * Buffer to store heap ID and index
+ *
+ * This needs to be large enough to store largest #haddr_t in a worst case
  * machine (8 bytes currently) plus an int.
- * Note! This type can only be used with the "native" HDF5 VOL connector.
+ *
+ * \deprecated Dataset region reference type that is used with deprecated
+ *             reference APIs.
+ *
+ * \note This type can only be used with the "native" HDF5 VOL connector.
  */
 typedef struct {
     uint8_t __data[H5R_DSET_REG_REF_BUF_SIZE];
 } hdset_reg_ref_t;
+//! <!-- [hdset_reg_ref_t_snip] -->
 
+//! <!-- [H5R_ref_t_snip] -->
 /**
  * Opaque reference type. The same reference type is used for object,
  * dataset region and attribute references. This is the type that
@@ -81,10 +95,11 @@ typedef struct {
  */
 typedef struct {
     union {
-        uint8_t __data[H5R_REF_BUF_SIZE]; /* opaque data */
-        int64_t align;                    /* ensures alignment */
+        uint8_t __data[H5R_REF_BUF_SIZE]; /**< opaque data */
+        int64_t align;                    /**< ensures alignment */
     } u;
 } H5R_ref_t;
+//! <!-- [H5R_ref_t_snip] -->
 
 /********************/
 /* Public Variables */
@@ -121,8 +136,8 @@ extern "C" {
  *          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];
+ *          \ref H5R_ref_t is defined in H5Rpublic.h as:
+ *          \snippet this H5R_ref_t_snip
  *
  *          H5Rdestroy() should be used to release the resource from the
  *          reference.
@@ -157,14 +172,12 @@ H5_DLL herr_t H5Rcreate_object(hid_t loc_id, const char *name, hid_t oapl_id, H5
  *          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];
+ *          \ref H5R_ref_t is defined in H5Rpublic.h as:
+ *          \snippet this H5R_ref_t_snip
  *
  *          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);
@@ -196,8 +209,8 @@ H5_DLL herr_t H5Rcreate_region(hid_t loc_id, const char *name, hid_t space_id, h
  *          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];
+ *          \ref H5R_ref_t is defined in H5Rpublic.h as:
+ *          \snippet this H5R_ref_t_snip
  *
  *          H5Rdestroy() should be used to release the resource from the
  *          reference.
@@ -216,12 +229,12 @@ H5_DLL herr_t H5Rcreate_attr(hid_t loc_id, const char *name, const char *attr_na
  *
  * \return \herr_t
  *
- * \details Given a reference, ref_ptr, to an object, region or attribute
- *          attached to an object, H5R_DESTROY releases allocated resources
+ * \details Given a reference, \p ref_ptr, to an object, region or attribute
+ *          attached to an object, H5Rdestroy() 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];
+ *          \ref H5R_ref_t is defined in H5Rpublic.h as:
+ *          \snippet this H5R_ref_t_snip
  *
  */
 H5_DLL herr_t H5Rdestroy(H5R_ref_t *ref_ptr);
@@ -236,23 +249,20 @@ H5_DLL herr_t H5Rdestroy(H5R_ref_t *ref_ptr);
  *
  * \param[in] ref_ptr  Pointer to reference
  *
- * \return Returns a valid reference type if successful; otherwise returns #H5R_UNKNOWN.
+ * \return Returns a valid reference type if successful; otherwise returns #H5R_BADTYPE .
  *
  * \details Given a reference, \p ref_ptr, H5Rget_type() returns the
  *          type of the reference.
  *
  *          Valid returned reference types are:
+ *          \snippet this H5R_type_t_snip
  *
- *          #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
+ *          Note that #H5R_OBJECT1 and #H5R_DATASET_REGION1 can never be
+ *          associated to an \ref 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];
+ *          \ref H5R_ref_t is defined in H5Rpublic.h as:
+ *          \snippet this H5R_ref_t_snip
  *
  */
 H5_DLL H5R_type_t H5Rget_type(const H5R_ref_t *ref_ptr);
@@ -273,8 +283,8 @@ H5_DLL H5R_type_t H5Rget_type(const H5R_ref_t *ref_ptr);
  * \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];
+ *          \ref H5R_ref_t is defined in H5Rpublic.h as:
+ *          \snippet this H5R_ref_t_snip
  *
  */
 H5_DLL htri_t H5Requal(const H5R_ref_t *ref1_ptr, const H5R_ref_t *ref2_ptr);
@@ -320,8 +330,8 @@ H5_DLL herr_t H5Rcopy(const H5R_ref_t *src_ref_ptr, H5R_ref_t *dst_ref_ptr);
  *          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];
+ *          \ref H5R_ref_t is defined in H5Rpublic.h as:
+ *          \snippet this H5R_ref_t_snip
  *
  *          The object opened with this function should be closed when it
  *          is no longer needed so that resource leaks will not develop. Use
@@ -333,22 +343,8 @@ 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()
- *
+ * \ingroup ASYNC
+ * \async_variant_of{H5Ropen}
  */
 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);
@@ -388,22 +384,8 @@ 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()
- *
+ * \ingroup ASYNC
+ * \async_variant_of{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);
@@ -440,22 +422,8 @@ 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()
- *
+ * \ingroup ASYNC
+ * \async_variant_of{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);
@@ -485,10 +453,7 @@ H5_DLL hid_t H5Ropen_attr_async(const char *app_file, const char *app_func, unsi
  *          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
+ *          \snippet H5Opublic.h H5O_type_t_snip
  *
  */
 H5_DLL herr_t H5Rget_obj_type3(H5R_ref_t *ref_ptr, hid_t rapl_id, H5O_type_t *obj_type);
@@ -540,12 +505,12 @@ H5_DLL ssize_t H5Rget_file_name(const H5R_ref_t *ref_ptr, char *name, size_t siz
  * \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
+ *          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
+ *          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 call to H5Rget_obj_name() call
@@ -553,8 +518,8 @@ H5_DLL ssize_t H5Rget_file_name(const H5R_ref_t *ref_ptr, char *name, size_t siz
  *          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).
+ *          or if the name is NULL, H5Rget_obj_name() returns the size of
+ *          the name buffer (the size does not include the \c \0 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
@@ -624,15 +589,334 @@ H5_DLL ssize_t H5Rget_attr_name(const H5R_ref_t *ref_ptr, char *name, size_t siz
 /* Function prototypes */
 #ifndef H5_NO_DEPRECATED_SYMBOLS
 
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5R
+ *
+ * \brief Retrieves the type of object that an object reference points to
+ *
+ * \param[in] id The dataset containing the reference object or the group
+ *            containing that dataset
+ * \param[in] ref_type Type of reference to query
+ * \param[in] ref Reference to query
+ *
+ * \return Returns a valid object type if successful; otherwise returns a
+ *         negative value (#H5G_UNKNOWN).
+ *
+ * \deprecated This function has been renamed from H5Rget_obj_type() and is
+ *             deprecated in favor of the macro H5Rget_obj_type() or the
+ *             function H5Rget_obj_type2().
+ *
+ * \details Given an object reference, \p ref, H5Rget_obj_type1() returns the
+ *          type of the referenced object.
+ *
+ *          A \Emph{reference type} is the type of reference, either an object
+ *          reference or a dataset region reference. An \Emph{object reference}
+ *          points to an HDF5 object while a \Emph{dataset region reference}
+ *          points to a defined region within a dataset.
+ *
+ *          The \Emph{referenced object} is the object the reference points
+ *          to. The \Emph{referenced object type}, or the type of the referenced
+ *          object, is the type of the object that the reference points to.
+ *
+ *          The location identifier, \p id, is the identifier for either the
+ *          dataset containing the object reference or the group containing that
+ *          dataset.
+ *
+ *          Valid reference types, to pass in as \p ref_type, include the
+ *          following:
+ *          \snippet this H5R_type_t_snip
+ *
+ *          If the application does not already know the object reference type,
+ *          that can be determined with three preliminary calls:
+ *
+ *          \li Call H5Dget_type() on the dataset containing the reference to
+ *              get a datatype identifier for the dataset’s datatype.
+ *          \li Using that datatype identifier, H5Tget_class() returns a datatype
+ *              class.\n If the datatype class is #H5T_REFERENCE, H5Tequal() can
+ *              then be used to determine whether the reference’s datatype is
+ *              #H5T_STD_REF_OBJ or #H5T_STD_REF_DSETREG:
+ *              - If the datatype is #H5T_STD_REF_OBJ, the reference object type
+ *                is #H5R_OBJECT.
+ *              - If the datatype is #H5T_STD_REF_DSETREG, the reference object
+ *                type is #H5R_DATASET_REGION.
+ *
+ *          When the function completes successfully, it returns one of the
+ *          following valid object type values (defined in H5Gpublic.h):
+ *          \snippet H5Gpublic.h H5G_obj_t_snip
+ *
+ * \version 1.8.0 Function H5Rget_obj_type() renamed to H5Rget_obj_type1() and
+ *                deprecated in this release.
+ * \since 1.6.0
+ *
+ */
 H5_DLL H5G_obj_t H5Rget_obj_type1(hid_t id, H5R_type_t ref_type, const void *ref);
-H5_DLL hid_t     H5Rdereference1(hid_t obj_id, H5R_type_t ref_type, const void *ref);
+
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5R
+ *
+ * \brief Opens the HDF5 object referenced
+ *
+ * \obj_id
+ * \param[in] ref_type The reference type of \p ref
+ * \param[in] ref Reference to open
+ *
+ * \return Returns identifier of referenced object if successful; otherwise
+ *         returns a negative value.
+ *
+ * \deprecated This function has been renamed from H5Rdereference() and is
+ *             deprecated in favor of the macro H5Rdereference() or the function
+ *             H5Rdereference2().
+ *
+ * \details Given a reference, \p ref, to an object or a region in an object,
+ *          H5Rdereference1() opens that object and returns an identifier.
+ *
+ *          The parameter \p obj_id must be a valid identifier for an object in
+ *          the HDF5 file containing the referenced object, including the file
+ *          identifier.
+ *
+ *          The parameter \p ref_type specifies the reference type of the
+ *          reference \p ref. \p ref_type may contain either of the following
+ *          values:
+ *          - #H5R_OBJECT
+ *          - #H5R_DATASET_REGION
+ *
+ *          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.
+ *
+ * \version 1.10.0 Function H5Rdereference() renamed to H5Rdereference1() and
+ *                 deprecated in this release.
+ * \since 1.8.0
+ *
+ */
+H5_DLL hid_t H5Rdereference1(hid_t obj_id, H5R_type_t ref_type, const void *ref);
 
 #endif /* H5_NO_DEPRECATED_SYMBOLS */
 
-H5_DLL herr_t  H5Rcreate(void *ref, hid_t loc_id, const char *name, H5R_type_t ref_type, hid_t space_id);
-H5_DLL herr_t  H5Rget_obj_type2(hid_t id, H5R_type_t ref_type, const void *ref, H5O_type_t *obj_type);
-H5_DLL hid_t   H5Rdereference2(hid_t obj_id, hid_t oapl_id, H5R_type_t ref_type, const void *ref);
-H5_DLL hid_t   H5Rget_region(hid_t dataset, H5R_type_t ref_type, const void *ref);
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5R
+ *
+ * \brief Creates a reference
+ *
+ * \param[out] ref Reference created by the function call
+ * \param[in] loc_id Location identifier used to locate the object being pointed to
+ * \param[in] name Name of object at location \p loc_id
+ * \param[in] ref_type Type of reference
+ * \param[in] space_id Dataspace identifier with selection. Used only for
+ *                     dataset region references; pass as -1 if reference is
+ *                     an object reference, i.e., of type #H5R_OBJECT
+ *
+ * \return \herr_t
+ *
+ * \details H5Rcreate() creates the reference, \p ref, of the type specified in
+ *          \p ref_type, pointing to the object \p name located at \p loc_id.
+ *
+ *          The HDF5 library maps the void type specified above for \p ref to
+ *          the type specified in \p ref_type, which will be one of the following:
+ *          \snippet this H5R_type_t_snip
+ *
+ *          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. This parameter is used only with
+ *          dataset region references and should be set to -1 if the reference
+ *          is an object reference, #H5R_OBJECT.
+ *
+ * \since 1.8.0
+ */
+H5_DLL herr_t H5Rcreate(void *ref, hid_t loc_id, const char *name, H5R_type_t ref_type, hid_t space_id);
+
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5R
+ *
+ * \brief Retrieves the type of object that an object reference points to
+ *
+ * \param[in] id The dataset containing the reference object or the group
+ *            containing that dataset
+ * \param[in] ref_type Type of reference to query
+ * \param[in] ref Reference to query
+ * \param[out] obj_type Type of referenced object
+ *
+ * \return \herr_t
+ *
+ * \details Given an object reference, \p ref, H5Rget_obj_type2() returns the
+ *          type of the referenced object in \p obj_type.
+ *
+ *          A \Emph{reference type} is the type of reference, either an object
+ *          reference or a dataset region reference. An \Emph{object reference}
+ *          points to an HDF5 object while a \Emph{dataset region reference}
+ *          points to a defined region within a dataset.
+ *
+ *          The \Emph{referenced object} is the object the reference points
+ *          to. The \Emph{referenced object type}, or the type of the referenced
+ *          object, is the type of the object that the reference points to.
+ *
+ *          The location identifier, \p id, is the identifier for either the
+ *          dataset containing the object reference or the group containing that
+ *          dataset.
+ *
+ *          Valid reference types, to pass in as \p ref_type, include the
+ *          following:
+ *          \snippet this H5R_type_t_snip
+ *
+ *          If the application does not already know the object reference type,
+ *          that can be determined with three preliminary calls:
+ *
+ *          \li Call H5Dget_type() on the dataset containing the reference to
+ *              get a datatype identifier for the dataset’s datatype.
+ *          \li Using that datatype identifier, H5Tget_class() returns a datatype
+ *              class.\n If the datatype class is #H5T_REFERENCE, H5Tequal() can
+ *              then be used to determine whether the reference’s datatype is
+ *              #H5T_STD_REF_OBJ or #H5T_STD_REF_DSETREG:
+ *              - If the datatype is #H5T_STD_REF_OBJ, the reference object type
+ *                is #H5R_OBJECT.
+ *              - If the datatype is #H5T_STD_REF_DSETREG, the reference object
+ *                type is #H5R_DATASET_REGION.
+ *
+ *          When the function completes successfully, it returns one of the
+ *          following valid object type values (defined in H5Opublic.h):
+ *          \snippet H5Opublic.h H5O_type_t_snip
+ *
+ * \since 1.8.0
+ *
+ */
+H5_DLL herr_t H5Rget_obj_type2(hid_t id, H5R_type_t ref_type, const void *ref, H5O_type_t *obj_type);
+
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5R
+ *
+ * \brief Opens the HDF5 object referenced
+ *
+ * \obj_id
+ * \oapl_id
+ * \param[in] ref_type The reference type of \p ref
+ * \param[in] ref Reference to open
+ *
+ * \return Returns identifier of referenced object if successful; otherwise
+ *         returns a negative value.
+ *
+ * \details Given a reference, \p ref, to an object or a region in an object,
+ *          H5Rdereference2() opens that object and returns an identifier.
+ *
+ *          The parameter \p obj_id must be a valid identifier for the HDF5 file
+ *          containing the referenced object or for any object in that HDF5
+ *          file.
+ *
+ *          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 datatype property list.
+ *
+ *          The parameter \p ref_type specifies the reference type of the
+ *          reference \p ref. \p ref_type may contain either of the following
+ *          values:
+ *          - #H5R_OBJECT
+ *          - #H5R_DATASET_REGION
+ *
+ *          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.
+ *
+ * \since 1.10.0
+ *
+ */
+H5_DLL hid_t H5Rdereference2(hid_t obj_id, hid_t oapl_id, H5R_type_t ref_type, const void *ref);
+
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5R
+ *
+ * \brief Sets up a dataspace and selection as specified by a region reference
+ *
+ * \param[in] dataset File identifier or identifier for any object in the file
+ *                    containing the referenced region
+ * \param[in] ref_type Reference type of \p ref, which must be #H5R_DATASET_REGION
+ * \param[in] ref Region reference to open
+ *
+ * \return Returns a valid dataspace identifier if successful; otherwise returns
+ *         a negative value.
+ *
+ * \details H5Rget_region() creates a copy of the dataspace of the dataset
+ *          pointed to by a region reference, \p ref, and defines a selection
+ *          matching the selection pointed to by ref within the dataspace copy.
+ *
+ *          \p dataset is used to identify the file containing the referenced
+ *          region; it can be a file identifier or an identifier for any object
+ *          in the file.
+ *
+ *          The parameter \p ref_type specifies the reference type of \p ref and
+ *          must contain the value #H5R_DATASET_REGION.
+ *
+ *          Use H5Sclose() to release the dataspace identifier returned by this
+ *          function when the identifier is no longer needed.
+ *
+ */
+H5_DLL hid_t H5Rget_region(hid_t dataset, H5R_type_t ref_type, const void *ref);
+
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup H5R
+ *
+ * \brief Retrieves a name for a referenced object
+ *
+ * \param[in] loc_id Identifier for the file containing the reference or for
+ *                   any object in that file
+ * \param[in] ref_type Type of reference
+ * \param[in] ref An object or dataset region reference
+ * \param[out] name A buffer to place the name of the referenced object or
+ *                  dataset region. If \c NULL, then this call will return the
+ *                  size in bytes of the name.
+ * \param[in] size The size of the \p name buffer. When the size is passed in,
+ *                 the \c NULL terminator needs to be included.
+ *
+ * \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_name() retrieves a name for the object identified by \p ref.\n
+ *          \p loc_id is used to identify the file containing the reference. It
+ *          can be the file identifier for the file containing the reference or
+ *          an identifier for any object in that file.
+ *
+ *          \ref H5R_type_t is the reference type of \p ref. Valid values
+ *          include the following:
+ *          \snippet this H5R_type_t_snip
+ *
+ *          \p ref is the reference for which the target object’s name is
+ *          sought.
+ *
+ *          If \p ref is an object reference, \p name will be returned with a
+ *          name for the referenced object. If \p ref is a dataset region
+ *          reference, \p name will contain a name for the object containing the
+ *          referenced region.
+ *
+ *          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 \p
+ *          size, is unknown, a preliminary H5Rget_name() call can be made. The
+ *          return value of this call will be the size of the object name. That
+ *          value can then be assigned to \p size for a second H5Rget_name()
+ *          call, which will retrieve the actual name.
+ *
+ *          If there is no name associated with the object identifier or if the
+ *          \p name is \c NULL, H5Rget_name() returns the size of the \p name
+ *          buffer (the size does not include the \p NULL terminator).
+ *
+ *          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.
+ *
+ * \since 1.8.0
+ */
 H5_DLL ssize_t H5Rget_name(hid_t loc_id, H5R_type_t ref_type, const void *ref, char *name, size_t size);
 
 #ifdef __cplusplus