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, 666 insertions, 160 deletions

diff --git a/src/H5Gpublic.h b/src/H5Gpublic.h
index 68786dc..416ff2c 100644
--- a/src/H5Gpublic.h
+++ b/src/H5Gpublic.h
@@ -41,24 +41,31 @@
 /* Public Typedefs */
 /*******************/
 
-/* Types of link storage for groups */
+//! <!-- [H5G_storage_t_snip] -->
+/**
+ * Types of link storage for groups
+ */
 typedef enum H5G_storage_type_t {
-    H5G_STORAGE_TYPE_UNKNOWN = -1, /* Unknown link storage type	*/
-    H5G_STORAGE_TYPE_SYMBOL_TABLE, /* Links in group are stored with a "symbol table" */
-                                   /* (this is sometimes called "old-style" groups) */
-    H5G_STORAGE_TYPE_COMPACT,      /* Links are stored in object header */
-    H5G_STORAGE_TYPE_DENSE         /* Links are stored in fractal heap & indexed with v2 B-tree */
+    H5G_STORAGE_TYPE_UNKNOWN = -1, /**< Unknown link storage type	*/
+    H5G_STORAGE_TYPE_SYMBOL_TABLE, /**< Links in group are stored with a "symbol table" */
+                                   /**< (this is sometimes called "old-style" groups) */
+    H5G_STORAGE_TYPE_COMPACT,      /**< Links are stored in object header */
+    H5G_STORAGE_TYPE_DENSE         /**< Links are stored in fractal heap & indexed with v2 B-tree */
 } H5G_storage_type_t;
+//! <!-- [H5G_storage_t_snip] -->
 
-/* Information struct for group (for H5Gget_info/H5Gget_info_by_name/H5Gget_info_by_idx) */
-//! [H5G_info_t_snip]
+//! <!-- [H5G_info_t_snip] -->
+/**
+ * Information struct for group for
+ * H5Gget_info(), H5Gget_info_by_name(), and H5Gget_info_by_idx()
+ */
 typedef struct H5G_info_t {
-    H5G_storage_type_t storage_type; /* Type of storage for links in group */
-    hsize_t            nlinks;       /* Number of links in group */
-    int64_t            max_corder;   /* Current max. creation order value for group */
-    hbool_t            mounted;      /* Whether group has a file mounted on it */
+    H5G_storage_type_t storage_type; /**< Type of storage for links in group */
+    hsize_t            nlinks;       /**< Number of links in group */
+    int64_t            max_corder;   /**< Current max. creation order value for group */
+    hbool_t            mounted;      /**< Whether group has a file mounted on it */
 } H5G_info_t;
-//! [H5G_info_t_snip]
+//! <!-- [H5G_info_t_snip] -->
 
 /********************/
 /* Public Variables */
@@ -120,24 +127,8 @@ H5_DLL hid_t H5Gcreate2(hid_t loc_id, const char *name, hid_t lcpl_id, hid_t gcp
 
 /**
  * --------------------------------------------------------------------------
- * \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()
- *
+ * \ingroup ASYNC
+ * \async_variant_of{H5Gcreate}
  */
 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);
@@ -223,22 +214,8 @@ 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()
- *
+ * \ingroup ASYNC
+ * \async_variant_of{H5Gopen}
  */
 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);
@@ -296,21 +273,8 @@ 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()
- *
+ * \ingroup ASYNC
+ * \async_variant_of{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 *ginfo /*out*/, hid_t es_id);
@@ -351,23 +315,8 @@ H5_DLL herr_t H5Gget_info_by_name(hid_t loc_id, const char *name, H5G_info_t *gi
 
 /**
  * --------------------------------------------------------------------------
- * \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()
- *
+ * \ingroup ASYNC
+ * \async_variant_of{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 *ginfo /*out*/,
@@ -423,29 +372,8 @@ H5_DLL herr_t H5Gget_info_by_idx(hid_t loc_id, const char *group_name, H5_index_
 
 /**
  * --------------------------------------------------------------------------
- * \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()
- *
+ * \ingroup ASYNC
+ * \async_variant_of{H5Gget_info_by_idx}
  */
 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,
@@ -523,29 +451,18 @@ H5_DLL herr_t H5Grefresh(hid_t group_id);
  *          Failure to release a group with this call will result in
  *          resource leaks.
  *
- * \since 1.0.0
+ * \par Example
+ * \snippet H5F_examples.c mount
  *
- * \version 1.4.0 Fortran function introduced in this release
+ * \since 1.0.0
  *
  */
 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()
- *
+ * \ingroup ASYNC
+ * \async_variant_of{H5Gclose}
  */
 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);
@@ -595,60 +512,649 @@ H5_DLL herr_t H5Gclose_async(const char *app_file, const char *app_func, unsigne
 
 /* Typedefs */
 
-/*
+//! <!-- [H5G_obj_t_snip] -->
+/**
  * An object has a certain type. The first few numbers are reserved for use
  * internally by HDF5. Users may add their own types with higher values.  The
- * values are never stored in the file -- they only exist while an
- * application is running.  An object may satisfy the `isa' function for more
- * than one type.
+ * values are never stored in the file -- they only exist while an application
+ * is running.  An object may satisfy the `isa' function for more than one type.
+ *
+ * \deprecated
  */
 typedef enum H5G_obj_t {
-    H5G_UNKNOWN = -1, /* Unknown object type		*/
-    H5G_GROUP,        /* Object is a group		*/
-    H5G_DATASET,      /* Object is a dataset		*/
-    H5G_TYPE,         /* Object is a named data type	*/
-    H5G_LINK,         /* Object is a symbolic link	*/
-    H5G_UDLINK,       /* Object is a user-defined link */
-    H5G_RESERVED_5,   /* Reserved for future use	*/
-    H5G_RESERVED_6,   /* Reserved for future use	*/
-    H5G_RESERVED_7    /* Reserved for future use	*/
+    H5G_UNKNOWN = -1, /**< Unknown object type		*/
+    H5G_GROUP,        /**< Object is a group		*/
+    H5G_DATASET,      /**< Object is a dataset		*/
+    H5G_TYPE,         /**< Object is a named data type	*/
+    H5G_LINK,         /**< Object is a symbolic link	*/
+    H5G_UDLINK,       /**< Object is a user-defined link */
+    H5G_RESERVED_5,   /**< Reserved for future use	*/
+    H5G_RESERVED_6,   /**< Reserved for future use	*/
+    H5G_RESERVED_7    /**< Reserved for future use	*/
 } H5G_obj_t;
+//! <!-- [H5G_obj_t_snip] -->
 
-/** Define the operator function pointer for for H5Giterate() */
-//! [H5G_iterate_t_snip]
+//! <!-- [H5G_iterate_t_snip] -->
+/**
+ * Callback for H5Giterate()
+ *
+ * \deprecated
+ */
 typedef herr_t (*H5G_iterate_t)(hid_t group, const char *name, void *op_data);
-//! [H5G_iterate_t_snip]
+//! <!-- [H5G_iterate_t_snip] -->
 
-/** Information about an object */
-//! [H5G_stat_t_snip]
+//! <!-- [H5G_stat_t_snip] -->
+/**
+ * Information about an object
+ *
+ * \deprecated
+ */
 typedef struct H5G_stat_t {
-    unsigned long fileno[2]; /*file number			*/
-    unsigned long objno[2];  /*object number			*/
-    unsigned      nlink;     /*number of hard links to object*/
-    H5G_obj_t     type;      /*basic object type		*/
-    time_t        mtime;     /*modification time		*/
-    size_t        linklen;   /*symbolic link value length	*/
-    H5O_stat_t    ohdr;      /* Object header information    */
+    unsigned long fileno[2]; /**< file number			*/
+    unsigned long objno[2];  /**< object number			*/
+    unsigned      nlink;     /**< number of hard links to object*/
+    H5G_obj_t     type;      /**< basic object type		*/
+    time_t        mtime;     /**< modification time		*/
+    size_t        linklen;   /**< symbolic link value length	*/
+    H5O_stat_t    ohdr;      /**< Object header information    */
 } H5G_stat_t;
-//! [H5G_stat_t_snip]
+//! <!-- [H5G_stat_t_snip] -->
 
 /* Function prototypes */
-H5_DLL hid_t     H5Gcreate1(hid_t loc_id, const char *name, size_t size_hint);
-H5_DLL hid_t     H5Gopen1(hid_t loc_id, const char *name);
-H5_DLL herr_t    H5Glink(hid_t cur_loc_id, H5G_link_t type, const char *cur_name, const char *new_name);
-H5_DLL herr_t    H5Glink2(hid_t cur_loc_id, const char *cur_name, H5G_link_t type, hid_t new_loc_id,
-                          const char *new_name);
-H5_DLL herr_t    H5Gmove(hid_t src_loc_id, const char *src_name, const char *dst_name);
-H5_DLL herr_t    H5Gmove2(hid_t src_loc_id, const char *src_name, hid_t dst_loc_id, const char *dst_name);
-H5_DLL herr_t    H5Gunlink(hid_t loc_id, const char *name);
-H5_DLL herr_t    H5Gget_linkval(hid_t loc_id, const char *name, size_t size, char *buf /*out*/);
-H5_DLL herr_t    H5Gset_comment(hid_t loc_id, const char *name, const char *comment);
-H5_DLL int       H5Gget_comment(hid_t loc_id, const char *name, size_t bufsize, char *buf);
-H5_DLL herr_t    H5Giterate(hid_t loc_id, const char *name, int *idx, H5G_iterate_t op, void *op_data);
-H5_DLL herr_t    H5Gget_num_objs(hid_t loc_id, hsize_t *num_objs);
-H5_DLL herr_t    H5Gget_objinfo(hid_t loc_id, const char *name, hbool_t follow_link,
-                                H5G_stat_t *statbuf /*out*/);
-H5_DLL ssize_t   H5Gget_objname_by_idx(hid_t loc_id, hsize_t idx, char *name, size_t size);
+/**
+ *-------------------------------------------------------------------------
+ * \ingroup H5G
+ *
+ * \brief Creates a new group and links it into the file
+ *
+ * \fgdta_loc_id
+ * \param[in] name      Name of the group to create
+ * \param[in] size_hint Optional parameter indicating the number of bytes
+ *                      to reserve for the names that will appear in the group
+ *
+ * \return \hid_t{group}
+ *
+ * \deprecated This function is deprecated in favor of H5Gcreate2().
+ *
+ * \details H5Gcreate1() creates a new group with the specified name at the
+ *          specified location, \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 group will be
+ *          created at the location where the attribute, dataset, or named
+ *          datatype is attached. The name, name, must not already be taken by
+ *          some other object and all parent groups must already exist.
+ *
+ *          \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 length of a group name, or of the name of any object within a
+ *          group, is not limited.
+ *
+ *          \p size_hint is a hint for the number of bytes to reserve to store
+ *          the names which will be eventually added to the new group. Passing a
+ *          value of zero for \p size_hint is usually adequate since the library
+ *          is able to dynamically resize the name heap, but a correct hint may
+ *          result in better performance. If a non-positive value is supplied
+ *          for \p size_hint, then a default size is chosen.
+ *
+ *          The return value is a group identifier for the open group. This
+ *          group identifier should be closed by calling H5Gclose() when it is
+ *          no longer needed.
+ *
+ *          See H5Gcreate_anon() for a discussion of the differences between
+ *          H5Gcreate1() and H5Gcreate_anon().
+ *
+ * \par Example
+ * \snippet H5F_examples.c mount
+ *
+ * \version 1.8.0 Function H5Gcreate() renamed to H5Gcreate1() and deprecated
+ *                in this release.
+ * \since 1.0.0
+ *
+ */
+H5_DLL hid_t H5Gcreate1(hid_t loc_id, const char *name, size_t size_hint);
+/**
+ *-------------------------------------------------------------------------
+ * \ingroup H5G
+ *
+ * \brief Opens an existing group for modification and returns a group
+ *        identifier for that group
+ *
+ * \fgdta_loc_id
+ * \param[in] name      Name of the group to open
+ *
+ * \return \hid_t{group}
+ *
+ * \deprecated This function is deprecated in favor of H5Gopen2().
+ *
+ * \details H5Gopen1() opens an existing group, \p name, at the location
+ *          specified by \p loc_id.
+ *
+ *          H5Gopen1() returns a group identifier for the group that was
+ *          opened. This group identifier should be released by calling
+ *          H5Gclose() when it is no longer needed.
+ *
+ * \version 1.8.0 The function H5Gopen() was renamed to H5Gopen1()
+ *                and deprecated in this release.
+ * \since 1.0.0
+ *
+ */
+H5_DLL hid_t H5Gopen1(hid_t loc_id, const char *name);
+/**
+ *-------------------------------------------------------------------------
+ * \ingroup H5G
+ *
+ * \brief Creates a link of the specified type from \p new_name to \p
+ *        cur_name
+ *
+ * \fg_loc_id{cur_loc_id}
+ * \param[in] type Link type
+ * \param[in] cur_name Name of the existing object
+ * \param[in] new_name New name for the object
+ *
+ * \return \herr_t
+ *
+ * \deprecated This function is deprecated.
+ *
+ * \details H5Glink() creates a new name for an object that has some current
+ *          name, possibly one of many names it currently has.
+ *
+ *          If \p link_type is #H5G_LINK_HARD, then \p cur_name must specify
+ *          the name of an existing object and both names are interpreted
+ *          relative to \p cur_loc_id, which is either a file identifier or a
+ *          group identifier.
+ *
+ *          If \p link_type is #H5G_LINK_SOFT, then \p cur_name can be anything
+ *          and is interpreted at lookup time relative to the group which
+ *          contains the final component of \p new_name. For instance, if \p
+ *          cur_name is \Code{./foo}, \p new_name is \Code{./x/y/bar}, and a
+ *          request is made for \Code{./x/y/bar}, then the actual object looked
+ *          up is \Code{./x/y/./foo}.
+
+ * \version 1.8.0 Function deprecated in this release.
+ *
+ */
+H5_DLL herr_t H5Glink(hid_t cur_loc_id, H5G_link_t type, const char *cur_name, const char *new_name);
+/**
+ *-------------------------------------------------------------------------
+ * \ingroup H5G
+ *
+ * \brief Creates a link of the specified type from \p cur_name to \p
+ *        new_name
+ *
+ * \fg_loc_id{cur_loc_id}
+ * \param[in] cur_name Name of the existing object
+ * \param[in] type Link type
+ * \fg_loc_id{new_loc_id}
+ * \param[in] new_name New name for the object
+ *
+ * \return \herr_t
+ *
+ * \deprecated This function is deprecated.
+ *
+ * \details H5Glink2() creates a new name for an object that has some current
+ *          name, possibly one of many names it currently has.
+ *
+ *          If \p link_type is #H5G_LINK_HARD, then \p cur_name must specify the
+ *          name of an existing object and both names are interpreted relative
+ *          to \p cur_loc_id and \p new_loc_id, respectively, which are either
+ *          file identifiers or group identifiers.
+ *
+ *          If \p link_type is #H5G_LINK_SOFT, then \p cur_name can be anything
+ *          and is interpreted at lookup time relative to the group which
+ *          contains the final component of \p new_name. For instance, if \p
+ *          current_name is \Code{./foo}, \p new_name is \Code{./x/y/bar}, and a
+ *          request is made for \Code{./x/y/bar}, then the actual object looked
+ *          up is \Code{./x/y/./foo}.
+
+ * \version 1.8.0 Function deprecated in this release.
+ *
+ */
+H5_DLL herr_t H5Glink2(hid_t cur_loc_id, const char *cur_name, H5G_link_t type, hid_t new_loc_id,
+                       const char *new_name);
+/**
+ *-------------------------------------------------------------------------
+ * \ingroup H5G
+ *
+ * \brief Renames an object within an HDF5 file
+ *
+ * \fg_loc_id{src_loc_id}
+ * \param[in] src_name Object's original name
+ * \param[in] dst_name Object's new name
+ *
+ * \return \herr_t
+ *
+ * \deprecated This function is deprecated.
+ *
+ * \details H5Gmove() renames an object within an HDF5 file. The original name,
+ *          \p src_name, is unlinked from the group graph and the new name, \p
+ *          dst_name, is inserted as an atomic operation. Both names are
+ *          interpreted relative to \p loc_id, which is either a file or a group
+ *          identifier.
+ *
+ * \attention Exercise care in moving groups as it is possible to render data in
+ *            a file inaccessible with H5Gmove(). See The Group Interface in the
+ *            HDF5 User's Guide.
+ *
+ * \version 1.8.0 Function deprecated in this release.
+ *
+ */
+H5_DLL herr_t H5Gmove(hid_t src_loc_id, const char *src_name, const char *dst_name);
+/**
+ *-------------------------------------------------------------------------
+ * \ingroup H5G
+ *
+ * \brief Renames an object within an HDF5 file
+ *
+ * \fg_loc_id{src_loc_id}
+ * \param[in] src_name Object's original name
+ * \fg_loc_id{dst_loc_id}
+ * \param[in] dst_name Object's new name
+ *
+ * \return \herr_t
+ *
+ * \deprecated This function is deprecated.
+ *
+ * \details H5Gmove2() renames an object within an HDF5 file. The original name,
+ *          \p src_name, is unlinked from the group graph and the new name, \p
+ *          dst_name, is inserted as an atomic operation.
+ *
+ *          \p src_name and \p dst_name are interpreted relative to \p
+ *          src_loc_id and \p dst_loc_id, respectively, which are either file or
+ *          group identifiers.
+ *
+ * \attention Exercise care in moving groups as it is possible to render data in
+ *            a file inaccessible with H5Gmove2(). See The Group Interface in the
+ *            HDF5 User's Guide.
+ *
+ * \version 1.8.0 Function deprecated in this release.
+ *
+ */
+H5_DLL herr_t H5Gmove2(hid_t src_loc_id, const char *src_name, hid_t dst_loc_id, const char *dst_name);
+/**
+ *-------------------------------------------------------------------------
+ * \ingroup H5G
+ *
+ * \brief Removes the link to an object from a group
+ *
+ * \fg_loc_id{loc_id}
+ * \param[in] name Name of the object to unlink
+ *
+ * \return \herr_t
+ *
+ * \deprecated This function is deprecated in favor of the function H5Ldelete().
+ *
+ * \details H5Gunlink() removes the object specified by \p name from the group
+ *          graph and decrements the link count for the object to which \p name
+ *          points. This action eliminates any association between name and the
+ *          object to which name pointed.
+ *
+ *          Object headers keep track of how many hard links refer to an object;
+ *          when the link count reaches zero, the object can be removed from the
+ *          file. Objects which are open are not removed until all identifiers
+ *          to the object are closed.
+ *
+ *          If the link count reaches zero, all file space associated with the
+ *          object will be released, i.e., identified in memory as freespace. If
+ *          any object identifier is open for the object, the space will not be
+ *          released until after the object identifier is closed.
+ *
+ *          Note that space identified as freespace is available for re-use only
+ *          as long as the file remains open; once a file has been closed, the
+ *          HDF5 library loses track of freespace. See “Freespace Management” in
+ *          the HDF5 User's Guide for further details.
+ *
+ * \attention Exercise care in moving groups as it is possible to render data in
+ *            a file inaccessible with H5Gunlink(). See The Group Interface in the
+ *            HDF5 User's Guide.
+ *
+ * \version 1.8.0 Function deprecated in this release.
+ *
+ */
+H5_DLL herr_t H5Gunlink(hid_t loc_id, const char *name);
+/**
+ *-------------------------------------------------------------------------
+ * \ingroup H5G
+ *
+ * \brief Returns the name of the object that the symbolic link points to
+ *
+ * \fg_loc_id{loc_id}
+ * \param[in] name Symbolic link to the object whose name is to be returned
+ * \param[in] size Maximum number of characters of value to be returned
+ * \param[out] buf A buffer to hold the name of the object being sought
+ *
+ * \return \herr_t
+ *
+ * \deprecated This function is deprecated in favor of the function H5Lget_val().
+ *
+ * \details H5Gget_linkval() returns up to size characters of the name of the
+ *          object that the symbolic link name points to.
+ *
+ *          The parameter \p loc_id is a file or group identifier.
+ *
+ *          The parameter \p name must be a symbolic link pointing to the
+ *          desired object and must be defined relative to \p loc_id.
+ *
+ *          If size is smaller than the size of the returned object name, then
+ *          the name stored in the buffer value will not be \c NULL terminated.
+ *
+ *          This function fails if \p name is not a symbolic link. The presence
+ *          of a symbolic link can be tested by passing zero for \p size and \p
+ *          NULL for value.
+ *
+ *          This function should be used only after H5Lget_info1() (or the
+ *          deprecated function H5Gget_objinfo()) has been called to verify that
+ *          name is a symbolic link.
+ *
+ * \version 1.8.0 Function deprecated in this release.
+ *
+ */
+H5_DLL herr_t H5Gget_linkval(hid_t loc_id, const char *name, size_t size, char *buf /*out*/);
+/**
+ *-------------------------------------------------------------------------
+ * \ingroup H5G
+ *
+ * \brief Sets comment for specified object
+ *
+ * \fgdt_loc_id
+ * \param[in] name Name of the object whose comment is to be set or reset
+ *                 name must be \Code{'.'} (dot) if \p loc_id fully specifies
+ *                 the object for which the comment is to be set.
+ * \param[in] comment The new comment
+ *
+ * \return \herr_t
+ *
+ * \deprecated This function is deprecated in favor of the function
+ *             H5Oset_comment().
+ *
+ * \details H5Gset_comment() sets the comment for the object specified by \p
+ *          loc_id and name to comment. Any previously existing comment is
+ *          overwritten.
+ *
+ *          \p loc_id can specify any object in the file. name can be one of the
+ *          following:
+ *          \li The name of the object relative to \p loc_id
+ *          \li An absolute name of the object, starting from \c /, the file’s
+ *              root group
+ *          \li A dot (\c .), if \p loc_id fully specifies the object
+ *
+ *          If \p comment is the empty string or a null pointer, the comment
+ *          message is removed from the object.
+ *
+ *          Comments should be relatively short, null-terminated, ASCII strings.
+ *
+ *          Comments can be attached to any object that has an object header,
+ *          e.g., datasets, groups, and named datatypes, but not symbolic links.
+ *
+ * \version 1.8.0 Function deprecated in this release.
+ *
+ */
+H5_DLL herr_t H5Gset_comment(hid_t loc_id, const char *name, const char *comment);
+/**
+ *-------------------------------------------------------------------------
+ * \ingroup H5G
+ *
+ * \brief Retrieves comment for specified object
+ *
+ * \fgdt_loc_id
+ * \param[in] name Name of the object whose comment is to be set or reset
+ *                 name must be \Code{'.'} (dot) if \p loc_id fully specifies
+ *                 the object for which the comment is to be set.
+ * \param[in] bufsize Maximum number of comment characters to be returned in \p buf.
+ * \param[in] buf The comment
+ *
+ * \return Returns the number of characters in the comment, counting the \c NULL
+ *         terminator, if successful; the value returned may be larger than
+ *         \p bufsize. Otherwise returns a negative value.
+ *
+ * \deprecated This function is deprecated in favor of the function
+ *             H5Oget_comment().
+ *
+ * \details H5Gget_comment() retrieves the comment for the the object specified
+ *          by \p loc_id and \p name. The comment is returned in the buffer \p
+ *          buf.
+ *
+ *          \p loc_id can specify any object in the file. name can be one of the
+ *          following:
+ *          \li The name of the object relative to \p loc_id
+ *          \li An absolute name of the object, starting from \c /, the file’s
+ *              root group
+ *          \li A dot (\c .), if \p loc_id fully specifies the object
+ *
+ *          At most bufsize characters, including a null-terminator, are
+ *          returned in \p buf. The returned value is not null-terminated if the
+ *          comment is longer than the supplied buffer. If the size of the
+ *          comment is unknown, a preliminary \p H5Gget_comment() call will
+ *          return the size of the comment, including space for the
+ *          null-terminator.
+ *
+ *          If an object does not have a comment, the empty string is returned
+ *          in comment.
+ *
+ * \version 1.8.0 Function deprecated in this release.
+ *
+ */
+H5_DLL int H5Gget_comment(hid_t loc_id, const char *name, size_t bufsize, char *buf);
+/**
+ *-------------------------------------------------------------------------
+ * \ingroup H5G
+ *
+ * \brief Iterates over the entries of a group invoking a callback for each
+ *        entry encountered
+ *
+ * \fg_loc_id
+ * \param[in] name Group over which the iteration is performed
+ * \param[in,out] idx Location at which to begin the iteration
+ * \param[in] op Operation to be performed on an object at each step of the
+ *               iteration
+ * \param[in,out] op_data Data associated with the operation
+ *
+ * \return \herr_t
+ *
+ * \deprecated This function is deprecated in favor of the function
+ *             H5Literate1().
+ *
+ * \details H5Giterate() iterates over the members of name in the file or group
+ *          specified with \p loc_id. For each object in the group, the \p
+ *          op_data and some additional information, specified below, are passed
+ *          to the operator function. The iteration begins with the \p idx
+ *          object in the group and the next element to be processed by the
+ *          operator is returned in \p idx. If \p idx is NULL, then the iterator
+ *          starts at the first group member; since no stopping point is
+ *          returned in this case, the iterator cannot be restarted if one of
+ *          the calls to its operator returns non-zero. H5Giterate() does not
+ *          recursively follow links into subgroups of the specified group.
+ *
+ *          The prototype for \ref H5G_iterate_t is:
+ *          \snippet this H5G_iterate_t_snip
+ *
+ *          The operation receives the group identifier for the group being
+ *          iterated over, \p group, the name of the current object within
+ *          the group, \p name, and the pointer to the operator data
+ *          passed in to H5Giterate(), \p op_data.
+ *
+ *          The return values from an operator are:
+ *          \li Zero causes the iterator to continue, returning zero when all
+ *              group members have been processed.
+ *          \li Positive causes the iterator to immediately return that positive
+ *              value, indicating short-circuit success. The iterator can be
+ *              restarted at the next group member.
+ *          \li Negative causes the iterator to immediately return that value,
+ *              indicating failure. The iterator can be restarted at the next
+ *              group member.
+ *
+ *          H5Giterate() assumes that the membership of the group identified by
+ *          \p name remains unchanged through the iteration. If the membership
+ *          changes during the iteration, the function's behavior is undefined.
+ *
+ *          H5Giterate() is not recursive. In particular, if a member of \p name
+ *          is found to be a group, call it \c subgroup_a, H5Giterate() does not
+ *          examine the members of \c subgroup_a. When recursive iteration is
+ *          required, the application must handle the recursion, explicitly
+ *          calling H5Giterate() on discovered subgroups.
+
+ * \version 1.8.0 Function deprecated in this release.
+ *
+ */
+H5_DLL herr_t H5Giterate(hid_t loc_id, const char *name, int *idx, H5G_iterate_t op, void *op_data);
+/**
+ *-------------------------------------------------------------------------
+ * \ingroup H5G
+ *
+ * \brief Returns number of objects in the group specified by its identifier
+ *
+ * \fg_loc_id
+ * \param[out] num_objs Number of objects in the group
+ *
+ * \return \herr_t
+ *
+ * \deprecated This function is deprecated in favor of the function H5Gget_info().
+ *
+ * \details H5Gget_num_objs() returns number of objects in a group. Group is
+ *          specified by its identifier \p loc_id. If a file identifier is
+ *          passed in, then the number of objects in the root group is returned.
+ *
+ * \version 1.8.0 Function deprecated in this release.
+ *
+ */
+H5_DLL herr_t H5Gget_num_objs(hid_t loc_id, hsize_t *num_objs);
+/**
+ *-------------------------------------------------------------------------
+ * \ingroup H5G
+ *
+ * \brief Returns information about an object.
+ *
+ * \fgdt_loc_id
+ * \param[in] name Name of the object for which status is being sought
+ * \param[in] follow_link Link flag
+ * \param[out] statbuf Buffer in which to return information about the object
+ *
+ * \return \herr_t
+ *
+ * \deprecated This function is deprecated in favor of the functions H5Oget_info()
+ *             and H5Lget_info1().
+ *
+ * \details H5Gget_objinfo() returns information about the specified object
+ *          through the \p statbuf argument.
+ *
+ *          A file or group identifier, \p loc_id, and an object name, \p name,
+ *          relative to \p loc_id, are commonly used to specify the
+ *          object. However, if the object identifier is already known to the
+ *          application, an alternative approach is to use that identifier, \c
+ *          obj_id, in place of \p loc_id, and a dot (\c .) in place of \p
+ *          name. Thus, the alternative versions of the first portion of an
+ *          H5Gget_objinfo() call would be as follows:
+ *          \code
+ *          H5Gget_objinfo (loc_id name  ...)
+ *          H5Gget_objinfo (obj_id .     ...)
+ *          \endcode
+ *
+ *          If the object is a symbolic link and follow_link is zero (0), then
+ *          the information returned describes the link itself; otherwise the
+ *          link is followed and the information returned describes the object
+ *          to which the link points. If \p follow_link is non-zero but the
+ *          final symbolic link is dangling (does not point to anything), then
+ *          an error is returned. The \p statbuf fields are undefined for an
+ *          error. The existence of an object can be tested by calling this
+ *          function with a \c NULL \p statbuf.
+ *
+ *          H5Gget_objinfo() fills in the following data structure (defined in
+ *          H5Gpublic.h):
+ *          \snippet this H5G_stat_t_snip
+ *
+ *          where \ref H5O_stat_t (defined in H5Opublic.h) is:
+ *          \snippet H5Opublic.h H5O_stat_t_snip
+ *
+ * \attention Some systems will be able to record the time accurately but unable
+ *            to retrieve the correct time; such systems (e.g., Irix64) will
+ *            report an \c mtime value of 0 (zero).
+ *
+ * \version 1.8.0 Function deprecated in this release.
+ * \version 1.6.1 Two new fields were added to the \ref H5G_stat_t struct in
+ *                this release.
+ *
+ */
+H5_DLL herr_t H5Gget_objinfo(hid_t loc_id, const char *name, hbool_t follow_link,
+                             H5G_stat_t *statbuf /*out*/);
+/**
+ *-------------------------------------------------------------------------
+ * \ingroup H5G
+ *
+ * \brief Returns a name of an object specified by an index
+ *
+ * \fg_loc_id
+ * \param[in] idx Transient index identifying object
+ * \param[in,out] name Pointer to user-provided buffer the object name
+ * \param[in] size Name length
+ *
+ * \return Returns the size of the object name if successful, or 0 if no name is
+ *         associated with the group identifier. Otherwise returns a negative
+ *         value.
+ *
+ * \deprecated This function is deprecated in favor of the function H5Lget_name_by_idx().
+ *
+ * \details H5Gget_objname_by_idx() returns a name of the object specified by
+ *          the index \p idx in the group \p loc_id.
+ *
+ *          The group is specified by a group identifier \p loc_id. If
+ *          preferred, a file identifier may be passed in \p loc_id; that file's
+ *          root group will be assumed.
+ *
+ *          \p idx is the transient index used to iterate through the objects in
+ *          the group. The value of \p idx is any nonnegative number less than
+ *          the total number of objects in the group, which is returned by the
+ *          function H5Gget_num_objs(). Note that this is a transient index; an
+ *          object may have a different index each time a group is opened.
+ *
+ *          The object name is returned in the user-specified buffer \p name.
+ *
+ *          If the size of the provided buffer \p name is less or equal the
+ *          actual object name length, the object name is truncated to
+ *          \Code{max_size - 1} characters.
+ *
+ *          Note that if the size of the object's name is unkown, a preliminary
+ *          call to H5Gget_objname_by_idx() with \p name set to \c NULL will
+ *          return the length of the object's name. A second call to
+ *          H5Gget_objname_by_idx() can then be used to retrieve the actual
+ *          name.
+ *
+ * \version 1.8.0 Function deprecated in this release.
+ * \since 1.6.0
+ *
+ */
+H5_DLL ssize_t H5Gget_objname_by_idx(hid_t loc_id, hsize_t idx, char *name, size_t size);
+/**
+ *-------------------------------------------------------------------------
+ * \ingroup H5G
+ *
+ * \brief Returns the type of an object specified by an index
+ *
+ * \fg_loc_id
+ * \param[in] idx Transient index identifying object
+ *
+ * \return Returns the type of the object if successful. Otherwise returns a
+ *         negative value.
+ *
+ * \deprecated This function is deprecated in favor of the function H5Oget_info().
+ *
+ * \details H5Gget_objtype_by_idx() returns the type of the object specified by
+ *          the index \p idx in the group \p loc_id.
+ *
+ *          The group is specified by a group identifier \p loc_id. If
+ *          preferred, a file identifier may be passed in \p loc_id; that file's
+ *          root group will be assumed.
+ *
+ *          \p idx is the transient index used to iterate through the objects in
+ *          the group. This parameter is described in more detail in the
+ *          discussion of H5Gget_objname_by_idx().
+ *
+ * \version 1.8.0 Function deprecated in this release.
+ * \version 1.6.0 The function return type changed from \c int to the enumerated
+ *                type \ref H5G_obj_t.
+ * \since 1.6.0
+ *
+ */
 H5_DLL H5G_obj_t H5Gget_objtype_by_idx(hid_t loc_id, hsize_t idx);
 
 #endif /* H5_NO_DEPRECATED_SYMBOLS */