First cut of the H5 public API documentation. (#80)

* First cut of the H5 public API documentation.

* Added H5Z "bonus track."

* Applied Quincey's patch.

* Added the missing patches from Quincey's original patch.

* H5PL (complete) and basic H5VL API documentation.

* Added H5I API docs.

* Added H5L API docs.

* First installment from Elena's H5T batch.

* Second installment of Elena's H5T batch.

* Final installment of Elena's H5T batch.

1 files changed, 586 insertions, 33 deletions

diff --git a/src/H5Ipublic.h b/src/H5Ipublic.h
index 697777c..a7c4961 100644
--- a/src/H5Ipublic.h
+++ b/src/H5Ipublic.h
@@ -21,37 +21,41 @@
 /* Public headers needed by this file */
 #include "H5public.h"
 
-/*
- * Library type values.  Start with `1' instead of `0' because it makes the
- * tracing output look better when hid_t values are large numbers.  Change the
- * TYPE_BITS in H5I.c if the MAXID gets larger than 32 (an assertion will
- * fail otherwise).
+/**
+ * Library type values.
+ * \internal Library type values.  Start with `1' instead of `0' because it
+ *           makes the tracing output look better when hid_t values are large
+ *           numbers. Change the TYPE_BITS in H5I.c if the MAXID gets larger
+ *           than 32 (an assertion will fail otherwise).
  *
- * When adding types here, add a section to the 'misc19' test in test/tmisc.c
- * to verify that the H5I{inc|dec|get}_ref() routines work correctly with it.
+ *           When adding types here, add a section to the 'misc19' test in
+ *           test/tmisc.c to verify that the H5I{inc|dec|get}_ref() routines
+ *           work correctly with it. \endinternal
  */
 typedef enum H5I_type_t {
-    H5I_UNINIT = (-2),  /* uninitialized type                           */
-    H5I_BADID  = (-1),  /* invalid Type                                 */
-    H5I_FILE   = 1,     /* type ID for File objects                     */
-    H5I_GROUP,          /* type ID for Group objects                    */
-    H5I_DATATYPE,       /* type ID for Datatype objects                 */
-    H5I_DATASPACE,      /* type ID for Dataspace objects                */
-    H5I_DATASET,        /* type ID for Dataset objects                  */
-    H5I_MAP,            /* type ID for Map objects                      */
-    H5I_ATTR,           /* type ID for Attribute objects                */
-    H5I_VFL,            /* type ID for virtual file layer               */
-    H5I_VOL,            /* type ID for virtual object layer             */
-    H5I_GENPROP_CLS,    /* type ID for generic property list classes    */
-    H5I_GENPROP_LST,    /* type ID for generic property lists           */
-    H5I_ERROR_CLASS,    /* type ID for error classes                    */
-    H5I_ERROR_MSG,      /* type ID for error messages                   */
-    H5I_ERROR_STACK,    /* type ID for error stacks                     */
-    H5I_SPACE_SEL_ITER, /* type ID for dataspace selection iterator     */
-    H5I_NTYPES          /* number of library types, MUST BE LAST!       */
+    H5I_UNINIT      = (-2),     /**< uninitialized type                        */
+    H5I_BADID       = (-1),     /**< invalid Type                              */
+    H5I_FILE        = 1,        /**< type ID for File objects                  */
+    H5I_GROUP,                  /**< type ID for Group objects                 */
+    H5I_DATATYPE,               /**< type ID for Datatype objects              */
+    H5I_DATASPACE,              /**< type ID for Dataspace objects             */
+    H5I_DATASET,                /**< type ID for Dataset objects               */
+    H5I_MAP,                    /**< type ID for Map objects                   */
+    H5I_ATTR,                   /**< type ID for Attribute objects             */
+    H5I_VFL,                    /**< type ID for virtual file layer            */
+    H5I_VOL,                    /**< type ID for virtual object layer          */
+    H5I_GENPROP_CLS,            /**< type ID for generic property list classes */
+    H5I_GENPROP_LST,            /**< type ID for generic property lists        */
+    H5I_ERROR_CLASS,            /**< type ID for error classes                 */
+    H5I_ERROR_MSG,              /**< type ID for error messages                */
+    H5I_ERROR_STACK,            /**< type ID for error stacks                  */
+    H5I_SPACE_SEL_ITER,         /**< type ID for dataspace selection iterator  */
+    H5I_NTYPES                  /**< number of library types, MUST BE LAST!    */
 } H5I_type_t;
 
-/* Type of atoms to return to users */
+/**
+ * Type of atoms to return to users
+ */
 typedef int64_t hid_t;
 
 #define PRIdHID PRId64
@@ -59,13 +63,18 @@ typedef int64_t hid_t;
 #define PRIXHID PRIX64
 #define PRIoHID PRIo64
 
-#define H5_SIZEOF_HID_T H5_SIZEOF_INT64_T
+/**
+ * The size of identifiers
+ */
+#define H5_SIZEOF_HID_T         H5_SIZEOF_INT64_T
 
-/* An invalid object ID. This is also negative for error return. */
-#define H5I_INVALID_HID (-1)
+/**
+ * An invalid object ID. This is also negative for error return.
+ */
+#define H5I_INVALID_HID         (-1)
 
-/*
- * Function for freeing objects. This function will be called with an object
+/**
+ * A function for freeing objects. This function will be called with an object
  * ID type number and a pointer to the object. The function should free the
  * object and return non-negative to indicate that the object
  * can be removed from the ID type. If the function returns negative
@@ -73,11 +82,19 @@ typedef int64_t hid_t;
  */
 typedef herr_t (*H5I_free_t)(void *);
 
-/* Type of the function to compare objects & keys */
+/**
+ * The type of a function to compare objects & keys
+ */
+//! [H5I_search_func_t_snip]
 typedef int (*H5I_search_func_t)(void *obj, hid_t id, void *key);
+//! [H5I_search_func_t_snip]
 
-/* Type of the H5Iiterate callback function */
+/**
+ * The type of H5Iiterate() callback functions
+ */
+//! [H5I_iterate_func_t_snip]
 typedef herr_t (*H5I_iterate_func_t)(hid_t id, void *udata);
+//! [H5I_iterate_func_t_snip]
 
 #ifdef __cplusplus
 extern "C" {
@@ -85,25 +102,561 @@ extern "C" {
 
 /* Public API functions */
 
+/**
+ * \ingroup H5I
+ *
+ * \brief Registers an object under a type and returns an ID for it
+ *
+ * \param[in] type The identifier of the type of the new ID
+ * \param[in] object Pointer to object for which a new ID is created
+ *
+ * \return \hid_t{object}
+ *
+ * \details H5Iregister() allocates and returns a new ID for an object.
+ *
+ * \details The \p type parameter is the identifier for the ID type to which
+ *          this new ID will belong. This identifier must have been created by
+ *          a call to H5Iregister_type().
+ *
+ * \details The \p object parameter is a pointer to the memory which the new ID
+ *          will be a reference to. This pointer will be stored by the library
+ *          and returned via a call to H5Iobject_verify().
+ *
+ */
 H5_DLL hid_t      H5Iregister(H5I_type_t type, const void *object);
+/**
+ * \ingroup H5I
+ *
+ * \brief Returns the object referenced by an ID
+ *
+ * \param[in] id ID to be dereferenced
+ * \param[in] id_type The identifier type
+
+ *
+ * \return Pointer to the object referenced by \p id on success, NULL on failure.
+ *
+ * \details H5Iobject_verify() returns a pointer to the memory referenced by id
+ *          after verifying that \p id is of type \p id_type. This function is
+ *          analogous to dereferencing a pointer in C with type checking.
+ *
+ * \note H5Iobject_verify() does not change the ID it is called on in any way
+ *       (as opposed to H5Iremove_verify(), which removes the ID from its
+ *       type’s hash table).
+ *
+ * \see H5Iregister()
+ *
+ */
 H5_DLL void *     H5Iobject_verify(hid_t id, H5I_type_t id_type);
+/**
+ * \ingroup H5I
+ *
+ * \brief Removes an ID from its type
+ *
+ * \param[in] id The ID to be removed from its type
+ * \param[in] id_type The identifier type
+
+ *
+ * \return Returns a pointer to the memory referred to by \p id on success,
+ *         NULL on failure.
+ *
+ * \details H5Iremove_verify() first ensures that \p id belongs to \p id_type.
+ *          If so, it removes \p id from its type and returns the pointer
+ *          to the memory it referred to. This pointer is the same pointer that
+ *          was placed in storage by H5Iregister(). If id does not belong to
+ *          \p id_type, then NULL is returned.
+ *
+ *          The \p id parameter is the ID which is to be removed from its type.
+ *
+ *          The \p type parameter is the identifier for the ID type which \p id
+ *          is supposed to belong to. This identifier must have been created by
+ *          a call to H5Iregister_type().
+ *
+ * \note This function does NOT deallocate the memory that \p id refers to.
+ *       The pointer returned by H5Iregister() must be deallocated by the user
+ *       to avoid memory leaks.
+ *
+ */
 H5_DLL void *     H5Iremove_verify(hid_t id, H5I_type_t id_type);
+/**
+ * \ingroup H5I
+ *
+ * \brief Retrieves the type of an object
+ *
+ * \obj_id{id}
+ *
+ * \return Returns the object type if successful; otherwise #H5I_BADID.
+ *
+ * \details H5Iget_type() retrieves the type of the object identified by
+ *          \p id.
+ *
+ *          Valid types returned by the function are:
+ *          \id_types
+ *
+ *          If no valid type can be determined or the identifier submitted is
+ *          invalid, the function returns #H5I_BADID.
+ *
+ *          This function is of particular use in determining the type of
+ *          object closing function (H5Dclose(), H5Gclose(), etc.) to call
+ *          after a call to H5Rdereference().
+ *
+ * \note Note that this function returns only the type of object that \p id
+ *       would identify if it were valid; it does not determine whether \p id
+ *       is valid identifier. Validity can be determined with a call to
+ *       H5Iis_valid().
+ *
+ */
 H5_DLL H5I_type_t H5Iget_type(hid_t id);
+/**
+ * \ingroup H5I
+ *
+ * \brief Retrieves an identifier for the file containing the specified object
+ *
+ * \obj_id{id}
+ *
+ * \return \hid_t{file}
+ *
+ * \details H5Iget_file_id() returns the identifier of the file associated with
+ *          the object referenced by \p id.
+ *
+ * \note Note that the HDF5 library permits an application to close a file
+ *       while objects within the file remain open. If the file containing the
+ *       object \p id is still open, H5Iget_file_id() will retrieve the
+ *       existing file identifier. If there is no existing file identifier for
+ *       the file, i.e., the file has been closed, H5Iget_file_id() will reopen
+ *       the file and return a new file identifier. In either case, the file
+ *       identifier must eventually be released using H5Fclose().
+ *
+ * \since 1.6.3
+ *
+ */
 H5_DLL hid_t      H5Iget_file_id(hid_t id);
+/**
+ * \ingroup H5I
+ *
+ * \brief Retrieves a name of an object based on the object identifier
+ *
+ * \obj_id{id}
+ * \param[out] name A buffer for thename associated with the identifier
+ * \param[in] size The size of the \p name buffer; usually the size of
+ *                 the name in bytes plus 1 for a NULL terminator
+ *
+ * \return ssize_t
+ *
+ * \details H5Iget_name() retrieves a name for the object identified by \p id.
+ *
+ * \details Up to size characters of the name are returned in \p name;
+ *          additional characters, if any, are not returned to the user
+ *          application.
+ *
+ *          If the length of the name, which determines the required value of
+ *          \p size, is unknown, a preliminary H5Iget_name() call can be made.
+ *          The return value of this call will be the size in bytes of the
+ *          object name. That value, plus 1 for a NULL terminator, is then
+ *          assigned to size for a second H5Iget_name() call, which will
+ *          retrieve the actual name.
+ *
+ *          If the object identified by \p id is an attribute, as determined
+ *          via H5Iget_type(), H5Iget_name() retrieves the name of the object
+ *          to which that attribute is attached. To retrieve the name of the
+ *          attribute itself, use H5Aget_name().
+ *
+ *          If there is no name associated with the object identifier or if the
+ *          name is NULL, H5Iget_name() returns 0 (zero).
+ *
+ * \note Note that an object in an HDF5 file may have multiple paths if there
+ *       are multiple links pointing to it. This function may return any one of
+ *       these paths. When possible, H5Iget_name() returns the path with which
+ *       the object was opened.
+ *
+ * \since 1.6.0
+ *
+ */
 H5_DLL ssize_t    H5Iget_name(hid_t id, char *name /*out*/, size_t size);
+/**
+ * \ingroup H5I
+ *
+ * \brief Increments the reference count for an object
+ *
+ * \obj_id{id}
+ *
+ * \return Returns a non-negative reference count of the object ID after
+ *         incrementing it if successful; otherwise a negative value is
+ *         returned.
+ *
+ * \details H5Iinc_ref() increments the reference count of the object
+ *          identified by \p id.
+ *
+ *          The reference count for an object ID is attached to the information
+ *          about an object in memory and has no relation to the number of
+ *          links to an object on disk.
+ *
+ *          The reference count for a newly created object will be 1. Reference
+ *          counts for objects may be explicitly modified with this function or
+ *          with H5Idec_ref(). When an object ID's reference count reaches
+ *          zero, the object will be closed. Calling an object ID's \c close
+ *          function decrements the reference count for the ID which normally
+ *          closes the object, but if the reference count for the ID has been
+ *          incremented with this function, the object will only be closed when
+ *          the reference count reaches zero with further calls to H5Idec_ref()
+ *          or the object ID's \c close function.
+ *
+ *          If the object ID was created by a collective parallel call (such as
+ *          H5Dcreate(), H5Gopen(), etc.), the reference count should be
+ *          modified by all the processes which have copies of the ID.
+ *          Generally this means that group, dataset, attribute, file and named
+ *          datatype IDs should be modified by all the processes and that all
+ *          other types of IDs are safe to modify by individual processes.
+ *
+ *          This function is of particular value when an application is
+ *          maintaining multiple copies of an object ID. The object ID can be
+ *          incremented when a copy is made. Each copy of the ID can then be
+ *          safely closed or decremented and the HDF5 object will be closed
+ *          when the reference count for that that object drops to zero.
+ *
+ * \since 1.6.2
+ *
+ */
 H5_DLL int        H5Iinc_ref(hid_t id);
+/**
+ * \ingroup H5I
+ *
+ * \brief Decrements the reference count for an object
+ *
+ * \obj_id{id}
+ *
+ * \return Returns a non-negative reference count of the object ID after
+ *         decrementing it, if successful; otherwise a negative value is
+ *         returned.
+ *
+ * \details H5Idec_ref() decrements the reference count of the object
+ *          identified by \p id.
+ *
+ *          The reference count for an object ID is attached to the information
+ *          about an object in memory and has no relation to the number of
+ *          links to an object on disk.
+ *
+ *          The reference count for a newly created object will be 1. Reference
+ *          counts for objects may be explicitly modified with this function or
+ *          with H5Iinc_ref(). When an object identifier’s reference count
+ *          reaches zero, the object will be closed. Calling an object
+ *          identifier’s \c close function decrements the reference count for
+ *          the identifier which normally closes the object, but if the
+ *          reference count for the identifier has been incremented with
+ *          H5Iinc_ref(), the object will only be closed when the reference
+ *          count reaches zero with further calls to this function or the
+ *          object identifier’s \c close function.
+ *
+ *          If the object ID was created by a collective parallel call (such as
+ *          H5Dcreate(), H5Gopen(), etc.), the reference count should be
+ *          modified by all the processes which have copies of the ID.
+ *          Generally this means that group, dataset, attribute, file and named
+ *          datatype IDs should be modified by all the processes and that all
+ *          other types of IDs are safe to modify by individual processes.
+ *
+ *          This function is of particular value when an application is
+ *          maintaining multiple copies of an object ID. The object ID can be
+ *          incremented when a copy is made. Each copy of the ID can then be
+ *          safely closed or decremented and the HDF5 object will be closed
+ *          when the reference count for that that object drops to zero.
+ *
+ * \since 1.6.2
+ *
+ */
 H5_DLL int        H5Idec_ref(hid_t id);
+/**
+ * \ingroup H5I
+ *
+ * \brief Retrieves the reference count for an object
+ *
+ * \obj_id{id}
+ *
+ * \return Returns a non-negative current reference count of the object
+ *         identifier if successful; otherwise a negative value is returned.
+ *
+ * \details H5Iget_ref() retrieves the reference count of the object identified
+ *          by \p id.
+ *
+ *          The reference count for an object identifier is attached to the
+ *          information about an object in memory and has no relation to the
+ *          number of links to an object on disk.
+ *
+ *          The function H5Iis_valid() is used to determine whether a specific
+ *          object identifier is valid.
+ *
+ * \since 1.6.2
+ *
+ */
 H5_DLL int        H5Iget_ref(hid_t id);
+/**
+ * \ingroup H5I
+ *
+ * \brief Creates and returns a new ID type
+ *
+ * \param[in] hash_size Minimum hash table size (in entries) used to store IDs
+ *                      for the new type
+ * \param[in] reserved Number of reserved IDs for the new type
+ * \param[in] free_func Function used to deallocate space for a single ID
+ *
+ * \return Returns the type identifier on success, negative on failure.
+ *
+ * \details H5Iregister_type() allocates space for a new ID type and returns an
+ *          identifier for it.
+ *
+ *          The \p hash_size parameter indicates the minimum size of the hash
+ *          table used to store IDs in the new type.
+ *
+ *          The \p reserved parameter indicates the number of IDs in this new
+ *          type to be reserved. Reserved IDs are valid IDs which are not
+ *          associated with any storage within the library.
+ *
+ *          The \p free_func parameter is a function pointer to a function
+ *          which returns an herr_t and accepts a \c void*. The purpose of this
+ *          function is to deallocate memory for a single ID. It will be called
+ *          by H5Iclear_type() and H5Idestroy_type() on each ID. This function
+ *          is NOT called by H5Iremove_verify(). The \c void* will be the same
+ *          pointer which was passed in to the H5Iregister() function. The \p
+ *          free_func function should return 0 on success and -1 on failure.
+ *
+ */
 H5_DLL H5I_type_t H5Iregister_type(size_t hash_size, unsigned reserved, H5I_free_t free_func);
+/**
+ * \ingroup H5I
+ *
+ * \brief Deletes all identifiers of the given type
+ *
+ * \param[in] type Identifier of identifier type which is to be cleared of identifiers
+ * \param[in] force Whether or not to force deletion of all identifiers
+ *
+ * \return \herr_t
+ *
+ * \details H5Iclear_type() deletes all identifiers of the type identified by
+ *          the argument \p type.
+ *
+ *          The identifier type's free function is first called on all of these
+ *          identifiers to free their memory, then they are removed from the
+ *          type.
+ *
+ *          If the \p force flag is set to false, only those identifiers whose
+ *          reference counts are equal to 1 will be deleted, and all other
+ *          identifiers will be entirely unchanged. If the force flag is true,
+ *          all identifiers of this type will be deleted.
+ *
+ */
 H5_DLL herr_t     H5Iclear_type(H5I_type_t type, hbool_t force);
+/**
+ * \ingroup H5I
+ *
+ * \brief Removes an identifier type and all identifiers within that type
+ *
+ * \param[in] type Identifier of identifier type which is to be destroyed
+ *
+ * \return \herr_t
+ *
+ * \details H5Idestroy_type deletes an entire identifier type \p type. All
+ *          identifiers of this type are destroyed and no new identifiers of
+ *          this type can be registered.
+ *
+ *          The type’s free function is called on all of the identifiers which
+ *          are deleted by this function, freeing their memory. In addition,
+ *          all memory used by this type’s hash table is freed.
+ *
+ *          Since the H5I_type_t values of destroyed identifier types are
+ *          reused when new types are registered, it is a good idea to set the
+ *          variable holding the value of the destroyed type to #H5I_UNINIT.
+ *
+ */
 H5_DLL herr_t     H5Idestroy_type(H5I_type_t type);
+/**
+ * \ingroup H5I
+ *
+ * \brief Increments the reference count on an ID type
+ *
+ * \param[in] type The identifier of the type whose reference count is to be incremented
+ *
+ * \return Returns the current reference count on success, negative on failure.
+ *
+ * \details H5Iinc_type_ref() increments the reference count on an ID type. The
+ *          reference count is used by the library to indicate when an ID type
+ *          can be destroyed.
+ *
+ *          The type parameter is the identifier for the ID type whose
+ *          reference count is to be incremented. This identifier must have
+ *          been created by a call to H5Iregister_type().
+ *
+ */
 H5_DLL int        H5Iinc_type_ref(H5I_type_t type);
+/**
+ * \ingroup H5I
+ *
+ * \brief Decrements the reference count on an identifier type
+ *
+ * \param[in] type The identifier of the type whose reference count is to be decremented
+ *
+ * \return Returns the current reference count on success, negative on failure.
+ *
+ * \details H5Idec_type_ref() decrements the reference count on an identifier
+ *          type. The reference count is used by the library to indicate when
+ *          an identifier type can be destroyed. If the reference count reaches
+ *          zero, this function will destroy it.
+ *
+ *          The type parameter is the identifier for the identifier type whose
+ *          reference count is to be decremented. This identifier must have
+ *          been created by a call to H5Iregister_type().
+ *
+ */
 H5_DLL int        H5Idec_type_ref(H5I_type_t type);
+/**
+ * \ingroup H5I
+ *
+ * \brief Retrieves the reference count on an ID type
+ *
+ * \param[in] type The identifier of the type whose reference count is to be retieved
+ *
+ * \return Returns the current reference count on success, negative on failure.
+ *
+ * \details H5Iget_type_ref() retrieves the reference count on an ID type. The
+ *          reference count is used by the library to indicate when an ID type
+ *          can be destroyed.
+ *
+ *          The type parameter is the identifier for the ID type whose
+ *          reference count is to be retrieved. This identifier must have been
+ *          created by a call to H5Iregister_type().
+ *
+ */
 H5_DLL int        H5Iget_type_ref(H5I_type_t type);
+/**
+ * \ingroup H5I
+ *
+ * \brief Finds the memory referred to by an ID within the given ID type such
+ *        that some criterion is satisfied
+ *
+ * \param[in] type The identifier of the type to be searched
+ * \param[in] func The function defining the search criteria
+ * \param[in] key A key for the search function
+ *
+ * \return Returns a pointer to the object which satisfies the search function
+ *         on success, NULL on failure.
+ *
+ * \details H5Isearch() searches through a given ID type to find an object that
+ *          satisfies the criteria defined by \p func. If such an object is
+ *          found, the pointer to the memory containing this object is
+ *          returned. Otherwise, NULL is returned. To do this, \p func is
+ *          called on every member of type \p type. The first member to satisfy
+ *          \p func is returned.
+ *
+ *          The \p type parameter is the identifier for the ID type which is to
+ *          be searched. This identifier must have been created by a call to
+ *          H5Iregister_type().
+ *
+ *          The parameter \p func is a function pointer to a function which
+ *          takes three parameters. The first parameter is a \c void* and will
+ *          be a pointer to the object to be tested. This is the same object
+ *          that was placed in storage using H5Iregister(). The second
+ *          parameter is a hid_t and is the ID of the object to be tested. The
+ *          last parameter is a \c void*. This is the \p key parameter and can
+ *          be used however the user finds helpful, or it can be ignored if it
+ *          is not needed. \p func returns 0 if the object it is testing does
+ *          not pass its criteria. A non-zero value should be returned if the
+ *          object does pass its criteria. H5I_search_func_t is defined in
+ *          H5Ipublic.h and is shown below.
+ *          \snippet this H5I_search_func_t_snip
+ *          The \p key parameter will be passed to the search function as a
+ *          parameter. It can be used to further define the search at run-time.
+ *
+ */
 H5_DLL void *     H5Isearch(H5I_type_t type, H5I_search_func_t func, void *key);
+/**
+ * \ingroup H5I
+ *
+ * \brief Calls a callback for each member of the identifier type specified
+ *
+ * \param[in] type The identifier type
+ * \param[in] op The callback function
+ * \param[in,out] op_data The data for the callback function
+ *
+ * \return The last value returned by \p op
+ *
+ * \details H5Iiterate() calls the callback function \p op for each member of
+ *          the identifier type \p type. The callback function type for \p op,
+ *          H5I_iterate_func_t, is defined in H5Ipublic.h as:
+ *          \snippet this H5I_iterate_func_t_snip
+ *          \p op takes as parameters the identifier and a pass through of
+ *          \p op_data, and returns an herr_t.
+ *
+ *          A positive return from op will cause the iteration to stop and
+ *          H5Iiterate() will return the value returned by \p op. A negative
+ *          return from \p op will cause the iteration to stop and H5Iiterate()
+ *          will return failure. A zero return from \p op will allow iteration
+ *          to continue, as long as there are other identifiers remaining in
+ *          type.
+ *
+ * \since 1.12.0
+ *
+ */
 H5_DLL herr_t     H5Iiterate(H5I_type_t type, H5I_iterate_func_t op, void *op_data);
+/**
+ * \ingroup H5I
+ *
+ * \brief Returns the number of identifiers in a given identifier type
+ *
+ * \param[in] type The identifier type
+ * \param[out] num_members Number of identifiers of the specified identifier type
+ *
+ * \return \herr_t
+ *
+ * \details H5Inmembers() returns the number of identifiers of the identifier
+ *          type specified in \p type.
+ *
+ *          The number of identifiers is returned in \p num_members. If no
+ *          identifiers of this type have been registered, the type does not
+ *          exist, or it has been destroyed, \p num_members is returned with
+ *          the value 0.
+ *
+ */
 H5_DLL herr_t     H5Inmembers(H5I_type_t type, hsize_t *num_members);
+/**
+ * \ingroup H5I
+ *
+ * \brief Determines whether an identifier type is registered
+ *
+ * \param[in] type Identifier type
+ *
+ * \return \htri_t
+ *
+ * \details H5Itype_exists() determines whether the given identifier type,
+ *          \p type, is registered with the library.
+ *
+ * \since 1.8.0
+ *
+ */
 H5_DLL htri_t     H5Itype_exists(H5I_type_t type);
+/**
+ * \ingroup H5I
+ *
+ * \brief Determines whether an identifier is valid
+ *
+ * \obj_id{id}
+ *
+ * \return \htri_t
+ *
+ * \details H5Iis_valid() determines whether the identifier \p id is valid.
+ *
+ * \details Valid identifiers are those that have been obtained by an
+ *          application and can still be used to access the original target.
+ *          Examples of invalid identifiers include:
+ *          \li Out of range values: negative, for example
+ *          \li Previously-valid identifiers that have been released:
+ *              for example, a dataset identifier for which the dataset has
+ *              been closed
+ *
+ *          H5Iis_valid() can be used with any type of identifier: object
+ *          identifier, property list identifier, attribute identifier, error
+ *          message identifier, etc. When necessary, a call to H5Iget_type()
+ *          can determine the type of the object that \p id identifies.
+ *
+ * \since 1.8.3
+ *
+ */
 H5_DLL htri_t     H5Iis_valid(hid_t id);
 
 #ifdef __cplusplus