Transferred RM blocks in H5D and H5G to develop (#213)

1 files changed, 335 insertions, 2 deletions

diff --git a/src/H5Gpublic.h b/src/H5Gpublic.h
index f209c3d..e46bef6 100644
--- a/src/H5Gpublic.h
+++ b/src/H5Gpublic.h
@@ -51,12 +51,15 @@ typedef enum H5G_storage_type_t {
 } H5G_storage_type_t;
 
 /* Information struct for group (for H5Gget_info/H5Gget_info_by_name/H5Gget_info_by_idx) */
+//! [H5G_info_t_snip]
 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_info_t;
+//! [H5G_info_t_snip]
+
 
 /********************/
 /* Public Variables */
@@ -69,29 +72,355 @@ typedef struct H5G_info_t {
 extern "C" {
 #endif
 
+/**
+ *-------------------------------------------------------------------------
+ * \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);
 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);
+
+/**
+ *-------------------------------------------------------------------------
+ * \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);
 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);
+
+/**
+ *-------------------------------------------------------------------------
+ * \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);
+
 H5_DLL herr_t H5Gget_info_async(const char *app_file, const char *app_func, unsigned app_line, hid_t loc_id,
                                 H5G_info_t *group_info /*out*/, hid_t es_id);
+
+/**
+ *-------------------------------------------------------------------------
+ * \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);
 H5_DLL herr_t H5Gget_info_by_name_async(const char *app_file, const char *app_func, unsigned app_line,
                                         hid_t loc_id, const char *name, H5G_info_t *group_info /*out*/,
                                         hid_t lapl_id, hid_t es_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 H5Gget_info_by_idx_async(const char *app_file, const char *app_func, unsigned app_line,
                                        hid_t loc_id, const char *group_name, H5_index_t idx_type,
                                        H5_iter_order_t order, hsize_t n, H5G_info_t *group_info /*out*/,
                                        hid_t lapl_id, hid_t es_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.
+ *
+ * \since 1.0.0
+ *
+ * \version 1.4.0 Fortran function introduced in this release
+ *
+ */
 H5_DLL herr_t H5Gclose(hid_t group_id);
 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);
@@ -160,10 +489,13 @@ typedef enum H5G_obj_t {
     H5G_RESERVED_7    /* Reserved for future use	*/
 } H5G_obj_t;
 
-/* Prototype for H5Giterate() operator */
+/** Define the operator function pointer for for H5Giterate() */
+//! [H5G_iterate_t_snip]
 typedef herr_t (*H5G_iterate_t)(hid_t group, const char *name, void *op_data);
+//! [H5G_iterate_t_snip]
 
-/* Information about an object */
+/** Information about an object */
+//! [H5G_stat_t_snip]
 typedef struct H5G_stat_t {
     unsigned long fileno[2]; /*file number			*/
     unsigned long objno[2];  /*object number			*/
@@ -173,6 +505,7 @@ typedef struct H5G_stat_t {
     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);