Hdf5 1 12 doxygen merge (#615)

* OESS-98 fix tools test for plugins

* sync fork

* Merge of changes from dev

* Move problem option to bottom of the list until fixed

* HDFFV-11106 - fix parsing optional args

* HDFFV-11106 add note

* grammer fix

* Whitespace after clang formatting

* Undo format version 11 changes

* Update check to working version

* Merge workflow and minor changes from develop

* Update supported platforms

* PR#3 merge from develop

* Merge gcc 10 diagnostics option from develop

* Merge #318 OSX changes from develop

* Merge serval small changes from dev

* fix typo

* Minor non-space formatting changes

* GH #386 copyright corrections for java folder

* revert because logic requires false return

* Merges from develop

#358 patches from vtk
#361 fix header guard spelling

* Remove case statement for H5I_EVENTSET

* Correct call with versioning

* Remove tabs

* Double underscore change

* Merges from develop

#340 clang -Wformat-security warnings
#360 Fixed uninitialized warnings
Remove more underscores from header guards

* Merge #380 from develop

* Correct date entry

* Split format source and commit changes on repo push

* remove pre-split setting

* Change windows TS to use older VS.

* HDFFV-11212 JNI export util and Javadoc

* Suggested review changes

* Another change found

* Committing clang-format changes

* Some Javadoc warning fixes

* Committing clang-format changes

* Updated javadoc fixes

* HDFFV-11228/9 merges from develop

* remove obsolete debug comment

* Fix conflict

* HDFFV-11229 merge changes from develop

* HDFFV-11229 merge second compare from develop

* HDFFV-11229 fix reference file

* HDFFV-11229 update autotools test script for two ref files

* HDFFV-11229 merge dev changes for long double display in tools

* Committing clang-format changes

* Update with changes from develop

* Add "option" command for clang options

* Rework CMake add_custom to use the BYPRODUCTS argument

Update pkgconfig scripts for parallel builds.
Fix install COPYING file reference.
Remove unused round defines.
Change CMake default setting of BUILD_CPP to off.

* Whitespace changes

* Rework CMake add_custom to use the BYPRODUCTS argument

* Revert CMake configure checks for round defines

* With VS 2015 minimum strdup is supported

* Doxygen comments merged from develop

* doxygen build updates

* Correct version string for map functions

Co-authored-by: github-actions <41898282+github-actions[bot]@users.noreply.github.com>

1 files changed, 980 insertions, 54 deletions

diff --git a/src/H5Gpublic.h b/src/H5Gpublic.h
index 99134f8..7f1faf8 100644
--- a/src/H5Gpublic.h
+++ b/src/H5Gpublic.h
@@ -41,22 +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] -->
+/**
+ * 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] -->
 
 /********************/
 /* Public Variables */
@@ -69,18 +78,344 @@ typedef struct H5G_info_t {
 extern "C" {
 #endif
 
-H5_DLL hid_t  H5Gcreate2(hid_t loc_id, const char *name, hid_t lcpl_id, hid_t gcpl_id, hid_t gapl_id);
-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);
-H5_DLL hid_t  H5Gget_create_plist(hid_t group_id);
+/**
+ *-------------------------------------------------------------------------
+ * \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
+ * \lcpl_id
+ * \gcpl_id
+ * \gapl_id
+ *
+ * \return \hid_t{group}
+ *
+ * \details H5Gcreate2() creates a new group in a file. After a
+ *          group has been created, links to datasets and to other groups
+ *          can be added.
+ *
+ *          The \p loc_id and \p name parameters specify where the group
+ *          is located. \p loc_id may be a file, group, dataset, named
+ *          datatype or attribute in the file. 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. \p name is the link to the group;
+ *          \p name may be either an absolute path in the file (the links
+ *          from the root group to the new group) or a relative path from
+ *          \p loc_id (the link(s) from the group specified by \p loc_id
+ *          to the new group).
+ *
+ *          \p lcpl_id, \p gcpl_id, and \p gapl_id are property list
+ *          identifiers. These property lists govern how the link to the
+ *          group is created, how the group is created, and how the group
+ *          can be accessed in the future, respectively. #H5P_DEFAULT can
+ *          be passed in if the default properties are appropriate for
+ *          these property lists. Currently, there are no APIs for the
+ *          group access property list; use #H5P_DEFAULT.
+ *
+ *          The group identifier should be closed by H5Gclose() when access
+ *          is no longer required to prevent resource leaks.
+ *
+ * \since 1.8.0
+ *
+ * \see H5Gopen2(), H5Gclose()
+ *
+ */
+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 Creates a new empty group without linking it into the file structure
+ *
+ * \fgdta_loc_id
+ * \gcpl_id
+ * \gapl_id
+ *
+ * \return \hid_t{group}
+ *
+ * \details H5Gcreate_anon() creates a new empty group in the file
+ *          specified by \p loc_id. With default settings, H5Gcreate_anon()
+ *          provides similar functionality to that provided by
+ *          H5Gcreate1(), with the differences described in the list below.
+ *
+ *          The new group’s creation and access properties are specified
+ *          in \p gcpl_id and \p gapl_id, respectively.
+ *
+ *          H5Gcreate_anon() returns a new group identifier. This identifier
+ *          must be linked into the HDF5 file structure with H5Olink()
+ *          or it will be deleted from the file when the file is closed.
+ *
+ *          The differences between this function and H5Gcreate1() are
+ *          as follows:
+ *
+ *          \li H5Gcreate1() does not provide for the use of custom property
+ *              lists; H5Gcreate1() always uses default properties.
+ *          \li H5Gcreate_anon() neither provides the new group’s name
+ *              nor links it into the HDF5 file structure; those actions
+ *              must be performed separately through a call to H5Olink(),
+ *              which offers greater control over linking.
+ *          \li H5Gcreate_anon() does not directly provide a hint mechanism
+ *              for the group’s heap size. Comparable information can be
+ *              included in the group creation property list \p gcpl_id through
+ *              a H5Pset_local_heap_size_hint() call.
+ *
+ *          A group created with this function should be closed with
+ *          H5Gclose() when the group is no longer needed so that resource
+ *          leaks will not develop.
+ *
+ * \see H5Olink(), H5Dcreate(), Using Identifiers
+ *
+ * \since 1.8.0
+ *
+ */
+H5_DLL hid_t H5Gcreate_anon(hid_t loc_id, hid_t gcpl_id, hid_t gapl_id);
+
+/**
+ *-------------------------------------------------------------------------
+ * \ingroup H5G
+ *
+ * \brief Opens an existing group in a file
+ *
+ * \fgdta_loc_id
+ * \param[in] name      Name of the group to open
+ * \gapl_id
+ *
+ * \return \hid_t{group}
+ *
+ * \details H5Gopen2() opens an existing group, \p name, at the location
+ *          specified by \p loc_id.
+ *
+ *          With default settings, H5Gopen2() provides similar functionality
+ *          to that provided by H5Gopen(). The only difference is that
+ *          H5Gopen2() can provide a group access property list, \p gapl_id.
+ *
+ *          H5Gopen2() returns a group identifier for the group that was
+ *          opened. This group identifier should be released by H5Gclose()
+ *          when it is no longer needed to prevent resource leaks.
+ *
+ * \since 1.8.0
+ *
+ * \see H5Gcreate2(), H5Gclose()
+ *
+ */
+H5_DLL hid_t H5Gopen2(hid_t loc_id, const char *name, hid_t gapl_id);
+
+/**
+ *-------------------------------------------------------------------------
+ * \ingroup H5G
+ *
+ * \brief Gets a group creation property list identifier
+ *
+ * \group_id
+ *
+ * \return \hid_t{creation property list}
+ *
+ * \details H5Gget_create_plist() returns an identifier for the group creation
+ *          property list associated with the group specified by \p group_id.
+ *
+ *          The creation property list identifier should be released with
+ *          H5Gclose() to prevent resource leaks.
+ *
+ * \since 1.8.0
+ *
+ * \see H5Gcreate2(), H5Gclose()
+ *
+ */
+H5_DLL hid_t H5Gget_create_plist(hid_t group_id);
+
+/**
+ *-------------------------------------------------------------------------
+ * \ingroup H5G
+ *
+ * \brief Retrieves information about a group
+ *
+ * \fgdta_loc_id
+ * \param[out] ginfo Struct in which group information is returned
+ *
+ * \return \hid_t{group}
+ *
+ * \details H5Gget_info() retrieves information about the group at location
+ *          specified by \p loc_id. The information is returned in the \p ginfo.
+ *
+ *          \p ginfo is an H5G_info_t struct and is defined (in H5Gpublic.h)
+ *          as follows:
+ *
+ * \snippet this H5G_info_t_snip
+ * Possible values of \p storage_type are:
+ * \storage_type
+ *
+ * \since 1.8.0
+ *
+ * \see H5Gcreate2(), H5Gclose()
+ *
+ */
 H5_DLL herr_t H5Gget_info(hid_t loc_id, H5G_info_t *ginfo);
+
+/**
+ *-------------------------------------------------------------------------
+ * \ingroup H5G
+ *
+ * \brief Retrieves information about a group by its name
+ *
+ * \fgdta_loc_id
+ * \param[in] name      Name of the group to query
+ * \param[out] ginfo Struct in which group information is returned
+ * \lapl_id
+ *
+ * \return \herr_t
+ *
+ * \details H5Gget_info_by_name() retrieves information about the group \p name
+ *          at location specified by \p loc_id. The information is returned in
+ *          the \p ginfo struct.
+ *
+ *          If \p loc_id specifies the group for which information is queried,
+ *          then the group's \p name can be a dot (.).
+ *
+ *          \p ginfo is an H5G_info_t struct and is defined (in H5Gpublic.h)
+ *          as follows:
+ *
+ * \snippet this H5G_info_t_snip
+ * Possible values of \p storage_type are:
+ * \storage_type
+ *
+ * \since 1.8.0
+ *
+ * \see H5Gcreate2(), H5Gclose()
+ *
+ */
 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 Retrieves information about a group, according to the group’s
+ *        position within an index
+ *
+ * \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
+ *
+ * \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
+ *
+ * \details H5Gget_info_by_idx() retrieves the same information
+ *          about a group as retrieved by the function H5Gget_info(),
+ *          but the means of identifying the group differs; the group is
+ *          identified by position in an index rather than by name.
+ *
+ *          \p loc_id and \p group_name specify the group containing
+ *          the group for which information is sought. The groups in \p
+ *          group_name are indexed by \p idx_type; the group for which
+ *          information is retrieved is identified in that index by index
+ *          order, \p order, and index position, \p n.
+ *
+ *          If \p loc_id specifies the group containing the group for
+ *          which information is queried, \p group_name can be a dot (.).
+ *
+ *          Valid values for \p index_type are as follows:
+ * \indexes
+ *          The order in which the index is to be examined, as specified
+ *          by \p order, can be one of the following:
+ * \orders
+ *
+ * \since 1.8.0
+ *
+ * \see H5Gcreate2(), H5Gclose()
+ *
+ */
 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);
-H5_DLL herr_t H5Gclose(hid_t group_id);
+
+/**
+ *-------------------------------------------------------------------------
+ * \ingroup H5G
+ *
+ * \brief Flushes all buffers associated with a group to disk
+ *
+ * \group_id
+ *
+ * \return \herr_t
+ *
+ * \details H5Gflush() causes all buffers associated with a group to be
+ *          immediately flushed to disk without removing the data from
+ *          the cache.
+ *
+ * \attention
+ *          HDF5 does not possess full control over buffering. H5G_FLUSH
+ *          flushes the internal HDF5 buffers and then asks the operating
+ *          system (the OS) to flush the system buffers for the open
+ *          files. After that, the OS is responsible for ensuring that
+ *          the data is actually flushed to disk.
+ *
+ * \since 1.8.0
+ *
+ * \see H5Gcreate2(), H5Gclose()
+ *
+ */
 H5_DLL herr_t H5Gflush(hid_t group_id);
+
+/**
+ *-------------------------------------------------------------------------
+ * \ingroup H5G
+ *
+ * \brief Refreshes all buffers associated with a group
+ *
+ * \group_id
+ *
+ * \return \herr_t
+ *
+ * \details H5Grefresh() causes all buffers associated with a group to be
+ *          cleared and immediately re-loaded with updated contents from disk.
+ *
+ *          This function essentially closes the group, evicts all
+ *          metadata associated with it from the cache, and then re-opens
+ *          the group. The reopened group is automatically re-registered
+ *          with the same identifier.
+ *
+ * \since 1.8.0
+ *
+ * \see H5Gcreate2(), H5Gclose()
+ *
+ */
 H5_DLL herr_t H5Grefresh(hid_t group_id);
 
+/**
+ *-------------------------------------------------------------------------
+ * \ingroup H5G
+ *
+ * \brief Closes the specified group
+ *
+ * \group_id
+ *
+ * \return \herr_t
+ *
+ * \details H5Gclose() releases resources used by a group which was
+ *          opened by H5Gcreate() or H5Gopen().  After closing a group,
+ *          \p group_id cannot be used again until another H5Gcreate()
+ *          or H5Gopen() is called on it.
+ *
+ *          Failure to release a group with this call will result in
+ *          resource leaks.
+ *
+ * \par Example
+ * \snippet H5F_examples.c mount
+ *
+ * \since 1.0.0
+ *
+ */
+H5_DLL herr_t H5Gclose(hid_t group_id);
+
 /* Symbols defined for compatibility with previous versions of the HDF5 API.
  *
  * Use of these symbols is deprecated.
@@ -104,56 +439,647 @@ H5_DLL herr_t H5Grefresh(hid_t group_id);
 
 /* 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] -->
 
-/* Prototype for H5Giterate() operator */
+//! <!-- [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] -->
 
-/* Information about an object */
+//! <!-- [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] -->
 
 /* 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 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. This
+ *          value must be between 0 and UINT32_MAX (inclusive). If this
+ *          parameter is zero, a default value will be used.
+ *
+ *          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 */