Merge clang-tidy changes to public headers (#962)

10 files changed, 57 insertions, 39 deletions

diff --git a/src/H5Dpublic.h b/src/H5Dpublic.h
index b73e62d..2094ff3 100644
--- a/src/H5Dpublic.h
+++ b/src/H5Dpublic.h
@@ -46,11 +46,11 @@
 typedef enum H5D_layout_t {
     H5D_LAYOUT_ERROR = -1,
 
-    H5D_COMPACT    = 0, /**< raw data is very small		     */
-    H5D_CONTIGUOUS = 1, /**< the default				     */
-    H5D_CHUNKED    = 2, /**< slow and fancy			     */
-    H5D_VIRTUAL    = 3, /**< actual data is stored in other datasets     */
-    H5D_NLAYOUTS   = 4  /**< this one must be last!		     */
+    H5D_COMPACT    = 0, /**< raw data is very small */
+    H5D_CONTIGUOUS = 1, /**< the default */
+    H5D_CHUNKED    = 2, /**< slow and fancy */
+    H5D_VIRTUAL    = 3, /**< actual data is stored in other datasets */
+    H5D_NLAYOUTS   = 4  /**< this one must be last! */
 } H5D_layout_t;
 //! <!-- [H5D_layout_t_snip] -->
 
diff --git a/src/H5Epublic.h b/src/H5Epublic.h
index 2f529b3..e0aecac 100644
--- a/src/H5Epublic.h
+++ b/src/H5Epublic.h
@@ -24,7 +24,7 @@
 #include "H5Ipublic.h"
 
 /* Value for the default error stack */
-#define H5E_DEFAULT (hid_t)0
+#define H5E_DEFAULT 0 /* (hid_t) */
 
 /**
  * Different kinds of error information
@@ -38,9 +38,9 @@ typedef struct H5E_error2_t {
     hid_t cls_id;
     /**< Class ID                           */
     hid_t maj_num;
-    /**< Major error ID		                */
+    /**< Major error ID                        */
     hid_t min_num;
-    /**< Minor error number		            */
+    /**< Minor error number                    */
     unsigned line;
     /**< Line in file where error occurs    */
     const char *func_name;
diff --git a/src/H5Fpublic.h b/src/H5Fpublic.h
index 89238b6..96ac0e1 100644
--- a/src/H5Fpublic.h
+++ b/src/H5Fpublic.h
@@ -84,7 +84,7 @@
     (0x0020u) /**< Restrict search to objects opened through current file ID                                 \
                    (as opposed to objects opened through any file ID accessing this file) */
 
-#define H5F_FAMILY_DEFAULT (hsize_t)0
+#define H5F_FAMILY_DEFAULT 0 /* (hsize_t) */
 
 #ifdef H5_HAVE_PARALLEL
 /**
diff --git a/src/H5Lpublic.h b/src/H5Lpublic.h
index bf1de86..f82f263 100644
--- a/src/H5Lpublic.h
+++ b/src/H5Lpublic.h
@@ -44,7 +44,7 @@
 /**
  * \brief Macro to indicate operation occurs on same location
  */
-#define H5L_SAME_LOC (hid_t)0
+#define H5L_SAME_LOC 0 /* (hid_t) */
 
 /**
  * \brief Current version of the H5L_class_t struct
diff --git a/src/H5Mpublic.h b/src/H5Mpublic.h
index f645bc9..25d3058 100644
--- a/src/H5Mpublic.h
+++ b/src/H5Mpublic.h
@@ -139,7 +139,7 @@ H5_DLL hid_t H5Mcreate_anon(hid_t loc_id, hid_t key_type_id, hid_t val_type_id,
  *          H5Mclose() when the application is not longer interested in
  *          accessing it.
  *
- * \since 1.13.0
+ * \since 1.12.0
  *
  */
 H5_DLL hid_t H5Mopen(hid_t loc_id, const char *name, hid_t mapl_id);
@@ -208,7 +208,7 @@ H5_DLL hid_t H5Mget_val_type(hid_t map_id);
  * \details H5Mget_create_plist() returns an identifier for a copy of the
  *          creation property list for a map object specified by \p map_id.
  *
- * \since 1.13.0
+ * \since 1.12.0
  *
  */
 H5_DLL hid_t H5Mget_create_plist(hid_t map_id);
diff --git a/src/H5Ppublic.h b/src/H5Ppublic.h
index 5adb05e..3d6968e 100644
--- a/src/H5Ppublic.h
+++ b/src/H5Ppublic.h
@@ -100,7 +100,7 @@
 #define H5P_CRT_ORDER_INDEXED 0x0002
 
 /* Default value for all property list classes */
-#define H5P_DEFAULT (hid_t)0
+#define H5P_DEFAULT 0 /* (hid_t) */
 
 #ifdef __cplusplus
 extern "C" {
diff --git a/src/H5Tpublic.h b/src/H5Tpublic.h
index b708506..8c36500 100644
--- a/src/H5Tpublic.h
+++ b/src/H5Tpublic.h
@@ -196,9 +196,9 @@ typedef enum H5T_pers_t {
  */
 //! <!-- [H5T_direction_t_snip] -->
 typedef enum H5T_direction_t {
-    H5T_DIR_DEFAULT = 0, /**< default direction is inscendent        */
-    H5T_DIR_ASCEND  = 1, /**< in inscendent order                    */
-    H5T_DIR_DESCEND = 2  /**< in descendent order                    */
+    H5T_DIR_DEFAULT = 0, /**< default direction is ascending         */
+    H5T_DIR_ASCEND  = 1, /**< in ascending order                     */
+    H5T_DIR_DESCEND = 2  /**< in descending order                    */
 } H5T_direction_t;
 //! <!-- [H5T_direction_t_snip] -->
 
@@ -279,7 +279,7 @@ typedef herr_t (*H5T_conv_t)(hid_t src_id, hid_t dst_id, H5T_cdata_t *cdata, siz
  * \returns Valid callback function return values are #H5T_CONV_ABORT,
  *          #H5T_CONV_UNHANDLED and #H5T_CONV_HANDLED.
  *
- * \details If an exception like overflow happenes during conversion, this
+ * \details If an exception like overflow happens during conversion, this
  *          function is called if it's registered through H5Pset_type_conv_cb().
  *
  */
diff --git a/src/H5mpi.c b/src/H5mpi.c
index 9749721..4a8aa44 100644
--- a/src/H5mpi.c
+++ b/src/H5mpi.c
@@ -523,7 +523,7 @@ H5_mpio_create_large_type(hsize_t num_elements, MPI_Aint stride_bytes, MPI_Datat
             MPI_Type_get_extent(old_type, &unused_lb_arg, &old_extent);
         }
 
-        /* Set up the arguments for MPI_Type_struct constructor */
+        /* Set up the arguments for MPI_Type_create_struct() */
         type[0]      = outer_type;
         type[1]      = leftover_type;
         block_len[0] = 1;
diff --git a/src/H5public.h b/src/H5public.h
index 09a2278..9ff8252 100644
--- a/src/H5public.h
+++ b/src/H5public.h
@@ -56,10 +56,15 @@
 #ifdef H5_HAVE_STDDEF_H
 #include <stddef.h>
 #endif
+
 #ifdef H5_HAVE_PARALLEL
 /* Don't link against MPI C++ bindings */
+#ifndef MPICH_SKIP_MPICXX
 #define MPICH_SKIP_MPICXX 1
-#define OMPI_SKIP_MPICXX  1
+#endif
+#ifndef OMPI_SKIP_MPICXX
+#define OMPI_SKIP_MPICXX 1
+#endif
 #include <mpi.h>
 #ifndef MPI_FILE_NULL /* MPIO may be defined in mpi.h already */
 #include <mpio.h>
@@ -233,7 +238,14 @@ typedef int herr_t;
 typedef bool 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
@@ -251,8 +263,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
@@ -297,9 +311,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")
@@ -319,8 +335,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;
diff --git a/src/H5system.c b/src/H5system.c
index 5cbc480..096200b 100644
--- a/src/H5system.c
+++ b/src/H5system.c
@@ -1083,8 +1083,8 @@ const char *H5_optarg;     /* Flag argument (or value)               */
 int
 H5_get_option(int argc, const char **argv, const char *opts, const struct h5_long_options *l_opts)
 {
-    static int sp     = 1;   /* character index in current token */
-    int        optopt = '?'; /* option character passed back to user */
+    static int sp      = 1;   /* character index in current token */
+    int        optchar = '?'; /* option character passed back to user */
 
     if (sp == 1) {
         /* check for more flag-like tokens */
@@ -1115,7 +1115,7 @@ H5_get_option(int argc, const char **argv, const char *opts, const struct h5_lon
         for (i = 0; l_opts && l_opts[i].name; i++) {
             if (HDstrcmp(arg, l_opts[i].name) == 0) {
                 /* we've found a matching long command line flag */
-                optopt = l_opts[i].shortval;
+                optchar = l_opts[i].shortval;
 
                 if (l_opts[i].has_arg != no_arg) {
                     if (H5_optarg == NULL) {
@@ -1128,7 +1128,7 @@ H5_get_option(int argc, const char **argv, const char *opts, const struct h5_lon
                             if (H5_opterr)
                                 HDfprintf(stderr, "%s: option required for \"--%s\" flag\n", argv[0], arg);
 
-                            optopt = '?';
+                            optchar = '?';
                         }
                     }
                 }
@@ -1137,7 +1137,7 @@ H5_get_option(int argc, const char **argv, const char *opts, const struct h5_lon
                         if (H5_opterr)
                             HDfprintf(stderr, "%s: no option required for \"%s\" flag\n", argv[0], arg);
 
-                        optopt = '?';
+                        optchar = '?';
                     }
                 }
                 break;
@@ -1149,7 +1149,7 @@ H5_get_option(int argc, const char **argv, const char *opts, const struct h5_lon
             if (H5_opterr)
                 HDfprintf(stderr, "%s: unknown option \"%s\"\n", argv[0], arg);
 
-            optopt = '?';
+            optchar = '?';
         }
 
         H5_optind++;
@@ -1161,11 +1161,11 @@ H5_get_option(int argc, const char **argv, const char *opts, const struct h5_lon
         register char *cp; /* pointer into current token */
 
         /* short command line option */
-        optopt = argv[H5_optind][sp];
+        optchar = argv[H5_optind][sp];
 
-        if (optopt == ':' || (cp = HDstrchr(opts, optopt)) == 0) {
+        if (optchar == ':' || (cp = HDstrchr(opts, optchar)) == 0) {
             if (H5_opterr)
-                HDfprintf(stderr, "%s: unknown option \"%c\"\n", argv[0], optopt);
+                HDfprintf(stderr, "%s: unknown option \"%c\"\n", argv[0], optchar);
 
             /* if no chars left in this token, move to next token */
             if (argv[H5_optind][++sp] == '\0') {
@@ -1183,9 +1183,9 @@ H5_get_option(int argc, const char **argv, const char *opts, const struct h5_lon
             }
             else if (++H5_optind >= argc) {
                 if (H5_opterr)
-                    HDfprintf(stderr, "%s: value expected for option \"%c\"\n", argv[0], optopt);
+                    HDfprintf(stderr, "%s: value expected for option \"%c\"\n", argv[0], optchar);
 
-                optopt = '?';
+                optchar = '?';
             }
             else {
                 /* flag value is next token */
@@ -1223,5 +1223,5 @@ H5_get_option(int argc, const char **argv, const char *opts, const struct h5_lon
     }
 
     /* return the current flag character found */
-    return optopt;
+    return optchar;
 }