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, 435 insertions, 24 deletions

diff --git a/src/H5public.h b/src/H5public.h
index 1784a11..eb1f573 100644
--- a/src/H5public.h
+++ b/src/H5public.h
@@ -304,15 +304,21 @@ typedef unsigned long      uint32_t;
 #error "nothing appropriate for uint32_t"
 #endif
 
-/* Common iteration orders */
+//! [H5_iter_order_t_snip]
+
+/**
+ * Common iteration orders
+ */
 typedef enum {
-    H5_ITER_UNKNOWN = -1, /* Unknown order */
-    H5_ITER_INC,          /* Increasing order */
-    H5_ITER_DEC,          /* Decreasing order */
-    H5_ITER_NATIVE,       /* No particular order, whatever is fastest */
-    H5_ITER_N             /* Number of iteration orders */
+    H5_ITER_UNKNOWN = -1, /**< Unknown order */
+    H5_ITER_INC,          /**< Increasing order */
+    H5_ITER_DEC,          /**< Decreasing order */
+    H5_ITER_NATIVE,       /**< No particular order, whatever is fastest */
+    H5_ITER_N             /**< Number of iteration orders */
 } H5_iter_order_t;
 
+//! [H5_iter_order_t_snip]
+
 /* Iteration callback values */
 /* (Actually, any positive value will cause the iterator to stop and pass back
  *      that positive value to the function that called the iterator)
@@ -321,18 +327,22 @@ typedef enum {
 #define H5_ITER_CONT  (0)
 #define H5_ITER_STOP  (1)
 
-/*
+//! [H5_index_t_snip]
+
+/**
  * The types of indices on links in groups/attributes on objects.
  * Primarily used for "<do> <foo> by index" routines and for iterating over
  * links in groups/attributes on objects.
  */
 typedef enum H5_index_t {
-    H5_INDEX_UNKNOWN = -1, /* Unknown index type                   */
-    H5_INDEX_NAME,         /* Index on names                       */
-    H5_INDEX_CRT_ORDER,    /* Index on creation order              */
-    H5_INDEX_N             /* Number of indices defined            */
+    H5_INDEX_UNKNOWN = -1, /**< Unknown index type                   */
+    H5_INDEX_NAME,         /**< Index on names                       */
+    H5_INDEX_CRT_ORDER,    /**< Index on creation order              */
+    H5_INDEX_N             /**< Number of indices defined            */
 } H5_index_t;
 
+//! [H5_index_t_snip]
+
 /**
  * Storage info struct used by H5O_info_t and H5F_info_t
  */
@@ -343,45 +353,446 @@ typedef struct H5_ih_info_t {
 } H5_ih_info_t;
 //! [H5_ih_info_t_snip]
 
-/* Tokens are unique and permanent identifiers that are
- * used to reference HDF5 objects in a container. */
+/**
+ * The maximum size allowed for tokens
+ * \details Tokens are unique and permanent identifiers that are
+ *          used to reference HDF5 objects in a container. This allows
+ *          for 128-bit tokens
+ */
+#define H5O_MAX_TOKEN_SIZE (16)
 
-/* The maximum size allowed for tokens */
-#define H5O_MAX_TOKEN_SIZE (16) /* Allows for 128-bit tokens */
+//! [H5O_token_t_snip]
 
+/**
+ * \internal (Hoisted here, since it's used by both the
+ *            H5Lpublic.h and H5Opublic.h headers) */
 /* Type for object tokens */
-/* (Hoisted here, since it's used by both the H5Lpublic.h and H5Opublic.h headers) */
 typedef struct H5O_token_t {
     uint8_t __data[H5O_MAX_TOKEN_SIZE];
 } H5O_token_t;
 
-/*
+//! [H5O_token_t_snip]
+
+/**
  * Allocation statistics info struct
  */
 typedef struct H5_alloc_stats_t {
-    unsigned long long total_alloc_bytes;        /* Running count of total # of bytes allocated */
-    size_t             curr_alloc_bytes;         /* Current # of bytes allocated */
-    size_t             peak_alloc_bytes;         /* Peak # of bytes allocated */
-    size_t             max_block_size;           /* Largest block allocated */
-    size_t             total_alloc_blocks_count; /* Running count of total # of blocks allocated */
-    size_t             curr_alloc_blocks_count;  /* Current # of blocks allocated */
-    size_t             peak_alloc_blocks_count;  /* Peak # of blocks allocated */
+    unsigned long long total_alloc_bytes;        /**< Running count of total # of bytes allocated */
+    size_t             curr_alloc_bytes;         /**< Current # of bytes allocated */
+    size_t             peak_alloc_bytes;         /**< Peak # of bytes allocated */
+    size_t             max_block_size;           /**< Largest block allocated */
+    size_t             total_alloc_blocks_count; /**< Running count of total # of blocks allocated */
+    size_t             curr_alloc_blocks_count;  /**< Current # of blocks allocated */
+    size_t             peak_alloc_blocks_count;  /**< Peak # of blocks allocated */
 } H5_alloc_stats_t;
 
 /* Functions in H5.c */
+/**
+ * \ingroup H5
+ * \brief Initializes the HDF5 library
+ * \return \herr_t
+ *
+ * \details H5open() initializes the HDF5 library.
+ *
+ * \details When the HDF5 library is used in a C application, the library is
+ *          automatically initialized when the first HDf5 function call is
+ *          issued. If one finds that an HDF5 library function is failing
+ *          inexplicably, H5open() can be called first. It is safe to call
+ *          H5open() before an application issues any other function calls to
+ *          the HDF5 library as there are no damaging side effects in calling
+ *          it more than once.
+ */
 H5_DLL herr_t H5open(void);
+/**
+ * \ingroup H5
+ * \brief Flushes all data to disk, closes all open objects, and releases memory
+ * \return \herr_t
+ *
+ * \details H5close() flushes all data to disk, closes all open HDF5 objects,
+ *          and cleans up all memory used by the HDF5 library. This function is
+ *          generally called when the application calls exit(), but may be
+ *          called earlier in the event of an emergency shutdown or out of a
+ *          desire to free all resources used by the HDF5 library.
+ */
 H5_DLL herr_t H5close(void);
+/**
+ * \ingroup H5
+ * \brief Instructs library not to install atexit() cleanup routine
+ * \return \herr_t
+ *
+ * \details H5dont_atexit() indicates to the library that an atexit() cleanup
+ *          routine should not be installed. The major purpose for using this
+ *          function is in situations where the library is dynamically linked
+ *          into an application and is un-linked from the application before
+ *          exit() gets called. In those situations, a routine installed with
+ *          atexit() would jump to a routine which was no longer in memory,
+ *          causing errors.
+ *
+ * \attention In order to be effective, this routine \Emph{must} be called
+ *            before any other HDF5 function calls, and must be called each
+ *            time the library is loaded/linked into the application (the first
+ *            time and after it's been un-loaded).
+ */
 H5_DLL herr_t H5dont_atexit(void);
+/**
+ * \ingroup H5
+ * \brief Garbage collects on all free-lists of all types
+ * \return \herr_t
+ *
+ * \details H5garbage_collect() walks through all garbage collection routines
+ *          of the library, freeing any unused memory.
+ *
+ *          It is not required that H5garbage_collect() be called at any
+ *          particular time; it is only necessary in certain situations where
+ *          the application has performed actions that cause the library to
+ *          allocate many objects. The application should call
+ *          H5garbage_collect() if it eventually releases those objects and
+ *          wants to reduce the memory used by the library from the peak usage
+ *          required.
+ *
+ * \note The library automatically garbage collects all the free lists when the
+ *       application ends.
+ */
 H5_DLL herr_t H5garbage_collect(void);
+/**
+ * \ingroup H5
+ * \brief Sets free-list size limits
+ *
+ * \param[in] reg_global_lim The cumulative limit, in bytes, on memory used for
+ *                           all regular free lists (Default: 1MB)
+ * \param[in] reg_list_lim The limit, in bytes, on memory used for each regular
+ *                         free list (Default: 64KB)
+ * \param[in] arr_global_lim The cumulative limit, in bytes, on memory used for
+ *                           all array free lists (Default: 4MB)
+ * \param[in] arr_list_lim The limit, in bytes, on memory used for each array
+ *                         free list (Default: 256KB)
+ * \param[in] blk_global_lim The cumulative limit, in bytes, on memory used for
+ *                           all block free lists and, separately, for all
+ *                           factory free lists (Default: 16MB)
+ * \param[in] blk_list_lim The limit, in bytes, on memory used for each block
+ *                         or factory free list (Default: 1MB)
+ * \return \herr_t
+ *
+ * \details H5set_free_list_limits() sets size limits on all types of free
+ *          lists. The HDF5 library uses free lists internally to manage
+ *          memory. The types of free lists used are as follows:
+ *          \li Regular free lists manage memory for single internal data
+ *              structures.
+ *          \li Array free lists manage memory for arrays of internal
+ *              data structures.
+ *          \li Block free lists manage memory for arbitrarily-sized blocks
+ *              of bytes.
+ *          \li Factory free lists manage memory for fixed-size blocks of
+ *              bytes.
+ *
+ *          The parameters specify global and per-list limits; for example, \p
+ *          reg_global_limit and \p reg_list_limit limit the accumulated size
+ *          of all regular free lists and the size of each individual regular
+ *          free list, respectively. Therefore, if an application sets a 1Mb
+ *          limit on each of the global lists, up to 4Mb of total storage might
+ *          be allocated, 1Mb for each of the regular, array, block, and
+ *          factory type lists.
+ *
+ *          The settings specified for block free lists are duplicated for
+ *          factory free lists. Therefore, increasing the global limit on block
+ *          free lists by x bytes will increase the potential free list memory
+ *          usage by 2x bytes.
+ *
+ *          Using a value of -1 for a limit means that no limit is set for the
+ *          specified type of free list.
+ *
+ * \version 1.8.3 Function changed in this release to set factory free list
+ *                memory limits.
+ *
+ * \since 1.6.0
+ */
 H5_DLL herr_t H5set_free_list_limits(int reg_global_lim, int reg_list_lim, int arr_global_lim,
                                      int arr_list_lim, int blk_global_lim, int blk_list_lim);
+/**
+ * \ingroup H5
+ * \brief Gets the current size of the free lists used to manage memory
+ *
+ * \param[out] reg_size The current size of all "regular" free list memory used
+ * \param[out] arr_size The current size of all "array" free list memory used
+ * \param[out] blk_size The current size of all "block" free list memory used
+ * \param[out] fac_size The current size of all "factory" free list memory used
+ * \return \herr_t
+ *
+ * \details H5get_free_list_sizes() obtains the current size of the different
+ *          kinds of free lists that the library uses to manage memory. The
+ *          free list sizes can be set with H5set_free_list_limits() and
+ *          garbage collected with H5garbage_collect(). These lists are global
+ *          for the entire library.
+ *
+ * \since 1.12.1
+ */
 H5_DLL herr_t H5get_free_list_sizes(size_t *reg_size, size_t *arr_size, size_t *blk_size, size_t *fac_size);
+/**
+ * \ingroup H5
+ * \brief Gets the memory allocation statistics for the library
+ *
+ * \param[out] stats Memory allocation statistics
+ * \return \herr_t
+ *
+ * \details H5get_alloc_stats() gets the memory allocation statistics for the
+ *          library, if the \c --enable-memory-alloc-sanity-check option was
+ *          given when building the library. Applications can check whether
+ *          this option was enabled detecting if the
+ *          \c H5_MEMORY_ALLOC_SANITY_CHECK macro is defined. This option is
+ *          enabled by default for debug builds of the library and disabled by
+ *          default for non-debug builds. If the option is not enabled, all the
+ *          values returned with be 0. These statistics are global for the
+ *          entire library, but do not include allocations from chunked dataset
+ *          I/O filters or non-native VOL connectors.
+ *
+ * \since 1.12.1
+ */
 H5_DLL herr_t H5get_alloc_stats(H5_alloc_stats_t *stats);
+/**
+ * \ingroup H5
+ * \brief Returns the HDF library release number
+ *
+ * \param[out] majnum The major version number of the library
+ * \param[out] minnum The minor version number of the library
+ * \param[out] relnum The release version number of the library
+ * \return \herr_t
+ *
+ * \details H5get_libversion() retrieves the major, minor, and release numbers
+ *          of the version of the HDF5 library which is linked to the
+ *          application.
+ *
+ */
 H5_DLL herr_t H5get_libversion(unsigned *majnum, unsigned *minnum, unsigned *relnum);
+/**
+ * \ingroup H5
+ * \brief Verifies that HDF5 library versions are consistent
+ *
+ * \param[in] majnum HDF5 library major version number
+ * \param[in] minnum HDF5 library minor version number
+ * \param[in] relnum HDF5 library release number
+ * \return \herr_t
+ *
+ * \details H5check_version() verifies that the version of the HDF5 library
+ *          with which an application was compiled, as indicated by the passed
+ *          parameters, matches the version of the HDF5 library against which
+ *          the application is currently linked.
+ *
+ *          \p majnum is the major version number of the HDF library with which
+ *          the application was compiled, \p minnum is the minor version
+ *          number, and \p relnum is the release number. Consider the following
+ *          example:
+ *
+ *          An official HDF5 release is labelled as follows:
+ *          HDF5 Release \Code{\<majnum\>.\<minnum\>.\<relnum\>}\n
+ *          For example, in HDF5 Release 1.8.5:
+ *          \li 1 is the major version number, \p majnum.
+ *          \li 8 is the minor version number, \p minnum.
+ *          \li 5 is the release number, \p relnum.
+ *
+ *          As stated above, H5check_version() first verifies that the version
+ *          of the HDF5 library with which an application was compiled matches
+ *          the version of the HDF5 library against which the application is
+ *          currently linked. If this check fails, H5check_version() causes the
+ *          application to abort (by means of a standard C abort() call) and
+ *          prints information that is usually useful for debugging. This
+ *          precaution is is taken to avoid the risks of data corruption or
+ *          segmentation faults.
+ *
+ *          The most common cause of this failure is that an application was
+ *          compiled with one version of HDF5 and is dynamically linked with a
+ *          different version different version.
+ *
+ *          If the above test passes, H5check_version() proceeds to verify the
+ *          consistency of additional library version information. This is
+ *          designed to catch source code inconsistencies that do not normally
+ *          cause failures; if this check reveals an inconsistency, an
+ *          informational warning is printed but the application is allowed to
+ *          run.
+ *
+ */
 H5_DLL herr_t H5check_version(unsigned majnum, unsigned minnum, unsigned relnum);
+/**
+ * \ingroup H5
+ * \brief Determines whether the HDF5 library was built with the thread-safety
+ *        feature enabled
+ *
+ * \param[out] is_ts Boolean value indicating whether the library was built
+ *                   with thread-safety enabled
+ * \return \herr_t
+ *
+ * \details The HDF5 library, although not internally multi-threaded, can be
+ *          built with a thread-safety feature enabled that protects internal
+ *          data structures with a mutex. In certain circumstances, it may be
+ *          useful to determine, at run-time, whether the linked HDF5 library
+ *          was built with the thread-safety feature enabled.
+ */
 H5_DLL herr_t H5is_library_threadsafe(hbool_t *is_ts);
+/**
+ * \ingroup H5
+ * \brief Frees memory allocated by the HDF5 library
+ *
+ * \param[in] mem Buffer to be freed. Can be NULL
+ * \return \herr_t
+ *
+ * \details H5free_memory() frees memory that has been allocated by the caller
+ *          with H5allocate_memory() or by the HDF5 library on behalf of the
+ *          caller.
+ *
+ *          H5Tget_member_name() provides an example of memory allocation on
+ *          behalf of the caller: The function returns a buffer containing the
+ *          name of a compound datatype member. It is the caller’s
+ *          responsibility to eventually free that buffer with H5free_memory().
+ *
+ * \attention It is especially important to use this function to free memory
+ *            allocated by the library on Windows. The C standard library is
+ *            implemented in dynamic link libraries (DLLs) known as the C
+ *            run-time (CRT). Each version of Visual Studio comes with two CRT
+ *            DLLs (debug and release) and allocating and freeing across DLL
+ *            boundaries can cause resource leaks and subtle bugs due to heap
+ *            corruption.\n
+ *            Only use this function to free memory allocated by the HDF5
+ *            Library. It will generally not be safe to use this function to
+ *            free memory allocated by any other means.\n
+ *            Even when using this function, it is still best to ensure that
+ *            all components of a C application are built with the same version
+ *            of Visual Studio and build (debug or release) and thus linked
+ *            against the same CRT.
+ *
+ * \see H5allocate_memory(), H5resize_memory()
+ *
+ * \since 1.8.13
+ *
+ */
 H5_DLL herr_t H5free_memory(void *mem);
+/**
+ * \ingroup H5
+ * \brief Frees memory allocated by the HDF5 library
+ *
+ * \param[in] size The size in bytes of the buffer to be allocated
+ * \param[in] clear Flag whether the new buffer is to be initialized with 0
+ *
+ * \return On success, returns pointer to newly allocated buffer or returns
+ *         NULL if size is 0 (zero).\n
+ *         Returns NULL on failure.
+ *
+ * \details H5allocate_memory() allocates a memory buffer of size bytes that
+ *          will later be freed internally by the HDF5 library.
+ *
+ *          The boolean \p clear parameter specifies whether the buffer should
+ *          be initialized. If clear is \c TRUE, all bits in the buffer are to be
+ *          set to 0 (zero); if clear is \c FALSE, the buffer will not be
+ *          initialized.
+ *
+ *          This function is intended to have the semantics of malloc() and
+ *          calloc(). However, unlike malloc() and calloc() which allow for a
+ *          "special" pointer to be returned instead of NULL, this function
+ *          always returns NULL on failure or when size is set to 0 (zero).
+ *
+ * \note At this time, the only intended use for this function is to allocate
+ *       memory that will be returned to the library as a data buffer from a
+ *       third-party filter.
+ *
+ * \attention To avoid heap corruption, allocated memory should be freed using
+ *            the same library that initially allocated it. In most cases, the
+ *            HDF5 API uses resources that are allocated and freed either
+ *            entirely by the user or entirely by the library, so this is not a
+ *            problem. In rare cases, however, HDF5 API calls will free memory
+ *            that the user allocated. This function allows the user to safely
+ *            allocate this memory.\n
+ *            It is particularly important to use this function to allocate
+ *            memory in Microsoft Windows environments. In Windows, the C
+ *            standard library is implemented in dynamic link libraries (DLLs)
+ *            known as the C run-time (CRT). Each version of Visual Studio
+ *            comes with multiple versions of the CRT DLLs (debug, release, et
+ *            cetera) and allocating and freeing memory across DLL boundaries
+ *            can cause resource leaks and subtle bugs due to heap corruption.\n
+ *            Even when using this function, it is best where possible to
+ *            ensure that all components of a C application are built with the
+ *            same version of Visual Studio and configuration (Debug or
+ *            Release), and thus linked against the same CRT.\n
+ *            Use this function only to allocate memory inside third-party HDF5
+ *            filters. It will generally not be safe to use this function to
+ *            allocate memory for any other purpose.
+ *
+ * \see H5free_memory(), H5resize_memory()
+ *
+ * \since 1.8.15
+ *
+ */
 H5_DLL void * H5allocate_memory(size_t size, hbool_t clear);
+/**
+ * \ingroup H5
+ * \brief Resizes and, if required, re-allocates memory that will later be
+ *        freed internally by the HDF5 library
+ *
+ * \param[in] mem Pointer to a buffer to be resized. May be NULL
+ * \param[in] size New size of the buffer, in bytes
+
+ *
+ * \return On success, returns pointer to resized or reallocated buffer
+ *         or returns NULL if size is 0 (zero).\n
+ *         Returns NULL on failure.
+ *
+ * \details H5resize_memory() takes a pointer to an existing buffer and resizes
+ *          the buffer to match the value in \p size. If necessary, the buffer
+ *          is reallocated. If \p size is 0, the buffer is released.
+ *
+ *          The input buffer must either be NULL or have been allocated by
+ *          H5allocate_memory() since the input buffer may be freed by the
+ *          library.
+ *
+ *          For certain behaviors, the pointer \p mem may be passed in as NULL.
+ *
+ *          This function is intended to have the semantics of realloc():
+ *
+ *          <table>
+ *            <tr><td>\Code{H5resize_memory(buffer, size)}</td>
+ *                <td>Resizes buffer. Returns pointer to resized buffer.</td></tr>
+ *            <tr><td>\Code{H5resize_memory(NULL, size)}</td>
+ *                <td>Allocates memory using HDF5 Library allocator.
+ *                    Returns pointer to new buffer</td></tr>
+ *            <tr><td>\Code{H5resize_memory(buffer, 0)}</td>
+ *                <td>Frees memory using HDF5 Library allocator.
+ *                    Returns NULL.</td></tr>
+ *            <tr><td>\Code{H5resize_memory(NULL, 0)}</td>
+ *                <td>Returns NULL (undefined in C standard).</td></tr>
+ *          </table>
+ *
+ *          Unlike realloc(), which allows for a "special pointer to be
+ *          returned instead of NULL, this function always returns NULL on
+ *          failure or when size is 0 (zero).
+ *
+ * \note At this time, the only intended use for this function is to resize or
+ *       reallocate memory that will be returned to the library (and eventually
+ *       to the user) as a data buffer from a third-party HDF5 filter.
+ *
+ * \attention To avoid heap corruption, allocated memory should be freed using
+ *            the same library that initially allocated it. In most cases, the
+ *            HDF5 API uses resources that are allocated and freed either
+ *            entirely by the user or entirely by the library, so this is not a
+ *            problem. In rare cases, however, HDF5 API calls will free memory
+ *            that the user allocated. This function allows the user to safely
+ *            allocate this memory.\n
+ *            It is particularly important to use this function to resize
+ *            memory on Microsoft Windows systems. In Windows, the C standard
+ *            library is implemented in dynamic link libraries (DLLs) known as
+ *            the C run-time (CRT). Each version of Visual Studio comes with
+ *            multiple versions of the CRT DLLs (debug, release, et cetera) and
+ *            allocating and freeing memory across DLL boundaries can cause
+ *            resource leaks and subtle bugs due to heap corruption.\n
+ *            Even when using this function, it is still best to ensure that
+ *            all components of a C application are built with the same version
+ *            of Visual Studio and the same configuration (Debug or Release),
+ *            and thus linked against the same CRT.\n
+ *            Only use this function to resize memory inside third-party HDF5
+ *            filters. It will generally not be safe to use this function to
+ *            resize memory for any other purpose.
+ *
+ * \see H5allocate_memory(), H5free_memory()
+ *
+ * \since 1.8.15
+ *
+ */
 H5_DLL void * H5resize_memory(void *mem, size_t size);
 
 #ifdef __cplusplus