1.8 Merge doxygen changes from develop (#1545)

* Merge doxygen changes from develop

* revert macro code change

* Format correction

1 files changed, 55 insertions, 19 deletions

diff --git a/src/H5public.h b/src/H5public.h
index 3c90c2a..aeb8664 100644
--- a/src/H5public.h
+++ b/src/H5public.h
@@ -11,19 +11,40 @@
  * help@hdfgroup.org.                                                        *
  * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
 
+/*
+ * This file contains public declarations for the HDF5 module.
+ */
+#ifndef H5public_H
+#define H5public_H
+
 /**\defgroup H5 H5
  *
  * Use the functions in this module to manage the life cycle of HDF5 library
  * instances.
  *
+ * <table>
+ * <tr><th>Create</th><th>Read</th></tr>
+ * <tr valign="top">
+ *   <td>
+ *   \snippet{lineno} H5_examples.c create
+ *   </td>
+ *   <td>
+ *   \snippet{lineno} H5_examples.c read
+ *   </td>
+ * <tr><th>Update</th><th>Delete</th></tr>
+ * <tr valign="top">
+ *   <td>
+ *   \snippet{lineno} H5_examples.c update
+ *   </td>
+ *   <td>
+ *   \snippet{lineno} H5_examples.c closing_shop
+ *   \snippet{lineno} H5_examples.c delete
+ *   </td>
+ * </tr>
+ * </table>
+ *
  */
 
-/*
- * This file contains public declarations for the HDF5 module.
- */
-#ifndef H5public_H
-#define H5public_H
-
 /* Include files for public use... */
 /*
  * Since H5pubconf.h is a generated header file, it is messy to try
@@ -63,6 +84,7 @@
 #ifdef H5_HAVE_STDDEF_H
 #include <stddef.h>
 #endif
+
 #ifdef H5_HAVE_PARALLEL
 /* Don't link against MPI C++ bindings */
 #define MPICH_SKIP_MPICXX 1
@@ -199,8 +221,9 @@ extern "C" {
  * Status return values.  Failed integer functions in HDF5 result almost
  * always in a negative value (unsigned failing functions sometimes return
  * zero for failure) while successful return is non-negative (often zero).
- * The negative failure value is most commonly -1, but don't bet on it.  The
- * proper way to detect failure is something like:
+ * The negative failure value is most commonly -1, but don't bet on it.
+ *
+ * The proper way to detect failure is something like:
  * \code
  * if((dset = H5Dopen2(file, name)) < 0)
  *    fprintf(stderr, "unable to open the requested dataset\n");
@@ -227,7 +250,14 @@ typedef int herr_t;
 typedef unsigned int hbool_t;
 typedef int          htri_t;
 
-/* Define the ssize_t type if it not is defined */
+/* The signed version of size_t
+ *
+ * ssize_t is POSIX and not defined in any C standard. It's used in some
+ * public HDF5 API calls so this work-around will define it if it's not
+ * present.
+ *
+ * Use of ssize_t should be discouraged in new code.
+ */
 #if H5_SIZEOF_SSIZE_T == 0
 /* Undefine this size, we will re-define it in one of the sections below */
 #undef H5_SIZEOF_SSIZE_T
@@ -245,8 +275,10 @@ typedef long long ssize_t;
 #endif
 #endif
 
-/* int64_t type is used for creation order field for links.  It may be
- * defined in Posix.1g, otherwise it is defined here.
+/**
+ * The size of file objects.
+ *
+ * \internal Defined as a (minimum) 64-bit integer type.
  */
 #if H5_SIZEOF_INT64_T >= 8
 #elif H5_SIZEOF_INT >= 8
@@ -291,9 +323,11 @@ typedef unsigned long long uint64_t;
 #error "nothing appropriate for uint64_t"
 #endif
 
-/*
- * The sizes of file objects have their own types defined here, use a minimum
- * 64-bit type.
+/**
+ * The size of file objects. Used when negative values are needed to indicate errors.
+ *
+ * \internal Defined as a (minimum) 64-bit integer type. Use of hssize_t
+ * should be discouraged in new code.
  */
 #if H5_SIZEOF_LONG_LONG >= 8
 H5_GCC_DIAG_OFF("long-long")
@@ -313,8 +347,10 @@ H5_GCC_DIAG_ON("long-long")
 #error "nothing appropriate for hsize_t"
 #endif
 
-/*
- * File addresses have their own types.
+/**
+ * The address of an object in the file.
+ *
+ * \internal Defined as a (minimum) 64-bit unsigned integer type.
  */
 #if H5_SIZEOF_INT >= 8
 typedef unsigned haddr_t;
@@ -395,9 +431,9 @@ typedef enum {
 /* (Actually, any positive value will cause the iterator to stop and pass back
  *      that positive value to the function that called the iterator)
  */
-#define H5_ITER_ERROR (-1)
-#define H5_ITER_CONT  (0)
-#define H5_ITER_STOP  (1)
+#define H5_ITER_ERROR (-1) /**< Error, stop iteration */
+#define H5_ITER_CONT  (0)  /**< Continue iteration */
+#define H5_ITER_STOP  (1)  /**< Stop iteration, short-circuit success */
 
 //! <!-- [H5_index_t_snip] -->
 /**