Merge pull request #2367 in HDFFV/hdf5 from ~DYOUNG/werror:unused to develop

* commit '50aac126d7c4082c2aeb0f3a68cad26bd1cd9783':
  Start to document the function/parameter/variable attribute macros.
  Filter all of the new _USED / _UNUSED type modifiers.
  H5_HAVE_PARALLEL, _DEBUG_API, etc.  Add attributes to some variables and parameters that are unused under some configurations.

16 files changed, 124 insertions, 32 deletions

diff --git a/bin/trace b/bin/trace
index 0256da6..de6a83f 100755
--- a/bin/trace
+++ b/bin/trace
@@ -239,7 +239,11 @@ sub argstring ($$$) {
   # certain type qualifiers, and indirection.
   $atype =~ s/^\bconst\b//;
   $atype =~ s/\bH5_ATTR_UNUSED\b//g;
+  $atype =~ s/\bH5_ATTR_DEPRECATED_USED\b//g;
   $atype =~ s/\bH5_ATTR_NDEBUG_UNUSED\b//g;
+  $atype =~ s/\bH5_ATTR_DEBUG_API_USED\b//g;
+  $atype =~ s/\bH5_ATTR_PARALLEL_UNUSED\b//g;
+  $atype =~ s/\bH5_ATTR_PARALLEL_USED\b//g;
   $atype =~ s/\s+/ /g;
   $ptr = length $1 if  $atype =~ s/(\*+)//;
   $atype =~ s/^\s+//;
diff --git a/doc/code-conventions.md b/doc/code-conventions.md
new file mode 100644
index 0000000..ff3b4cf
--- /dev/null
+++ b/doc/code-conventions.md
@@ -0,0 +1,57 @@
+# HDF5 Library Code Conventions
+
+This document describes some practices that are new, or newly
+documented, starting in 2020.
+
+## Function / Variable Attributes
+
+In H5private.h, the library provides platform-independent macros
+for qualifying function and variable definitions.
+
+### Functions that accept `printf(3)` and `scanf(3)` format strings
+
+Label functions that accept a `printf(3)`-compliant format string with
+`H5_ATTR_FORMAT(printf,format_argno,variadic_argno)`, where
+the format string is the `format_argno`th argument (counting from 1)
+and the variadic arguments start with the `variadic_argno`th.
+
+Functions that accept a `scanf(3)`-compliant format string should
+be labeled `H5_ATTR_FORMAT(scanf,format_argno,variadic_argno)`.
+
+### Functions that do never return
+
+The definition of a function that always causes the program to abort and hang
+should be labeled `H5_ATTR_NORETURN` to help the compiler see which flows of
+control are infeasible.
+
+### Other attributes
+
+**TBD**
+
+### Unused variables and parameters
+
+Compilers will warn about unused parameters and variables—developers should pay
+attention to those warnings and make an effort to prevent them.
+
+Some function parameters and variables are unused in *all* configurations of
+the project.  Ordinarily, such parameters and variables should be deleted.
+However, sometimes it is possible to foresee a parameter being used, or
+removing it would change an API, or a parameter has to be defined to conform a
+function to some function pointer type.  In those cases, it's permissible to
+mark a symbol `H5_ATTR_UNUSED`.
+
+Other parameters and variables are unused in *some* configurations of the
+project, but not all.  A symbol may fall into disuse in some configuration in
+the future—then the compiler should warn, and the symbol should not be
+defined—so developers should try to label a sometimes-unused symbol with an
+attribute that's specific to the configurations where the symbol is (or is not)
+expected to be used.  The library provides the following attributes for that
+purpose:
+
+* `H5_ATTR_DEPRECATED_USED`: used only if deprecated symbols are enabled
+* `H5_ATTR_NDEBUG_UNUSED`: used only if `NDEBUG` is *not* \#defined
+* `H5_ATTR_DEBUG_API_USED`: used if the debug API is enabled
+* `H5_ATTR_PARALLEL_UNUSED`: used only if Parallel HDF5 *is not* configured
+* `H5_ATTR_PARALLEL_USED`: used only if Parallel HDF5 *is* configured
+
+Some attributes may be phased in or phased out in the future.
diff --git a/src/H5B2leaf.c b/src/H5B2leaf.c
index 7ed0468..c1221ba 100644
--- a/src/H5B2leaf.c
+++ b/src/H5B2leaf.c
@@ -1051,7 +1051,7 @@ H5B2__assert_leaf(const H5B2_hdr_t H5_ATTR_NDEBUG_UNUSED *hdr,
  *-------------------------------------------------------------------------
  */
 H5_ATTR_PURE herr_t
-H5B2__assert_leaf2(const H5B2_hdr_t *hdr, const H5B2_leaf_t *leaf, const H5B2_leaf_t H5_ATTR_UNUSED *leaf2)
+H5B2__assert_leaf2(const H5B2_hdr_t H5_ATTR_NDEBUG_UNUSED *hdr, const H5B2_leaf_t H5_ATTR_NDEBUG_UNUSED *leaf, const H5B2_leaf_t H5_ATTR_UNUSED *leaf2)
 {
     /* General sanity checking on node */
     HDassert(leaf->nrec <= hdr->node_info->split_nrec);
diff --git a/src/H5I.c b/src/H5I.c
index 2ba8a2a..b233d23 100644
--- a/src/H5I.c
+++ b/src/H5I.c
@@ -215,7 +215,8 @@ H5I_term_package(void)
  *-------------------------------------------------------------------------
  */
 H5I_type_t
-H5Iregister_type(size_t hash_size, unsigned reserved, H5I_free_t free_func)
+H5Iregister_type(size_t H5_ATTR_DEBUG_API_USED hash_size, unsigned reserved,
+    H5I_free_t free_func)
 {
     H5I_class_t *cls = NULL;            /* New ID class */
     H5I_type_t new_type;                /* New ID type value */
diff --git a/src/H5Odbg.c b/src/H5Odbg.c
index b8190ae..3c91cae 100644
--- a/src/H5Odbg.c
+++ b/src/H5Odbg.c
@@ -153,7 +153,7 @@ H5O__assert(const H5O_t *oh)
 
     /* Loop over all messages in object header */
     for(u = 0, curr_msg = &oh->mesg[0]; u < oh->nmesgs; u++, curr_msg++) {
-        uint8_t *curr_hdr;      /* Start of current message header */
+        uint8_t H5_ATTR_NDEBUG_UNUSED *curr_hdr;      /* Start of current message header */
         size_t  curr_tot_size;  /* Total size of current message (including header) */
 
         curr_hdr = curr_msg->raw - H5O_SIZEOF_MSGHDR_OH(oh);
@@ -164,7 +164,7 @@ H5O__assert(const H5O_t *oh)
             free_space += curr_tot_size;
         else if(H5O_CONT_ID == curr_msg->type->id) {
             H5O_cont_t *cont = (H5O_cont_t *)curr_msg->native;
-            hbool_t found_chunk = FALSE;        /* Found a chunk that matches */
+            hbool_t H5_ATTR_NDEBUG_UNUSED found_chunk = FALSE;        /* Found a chunk that matches */
 
             HDassert(cont);
 
diff --git a/src/H5Pfapl.c b/src/H5Pfapl.c
index 9a04c3e..7866464 100644
--- a/src/H5Pfapl.c
+++ b/src/H5Pfapl.c
@@ -4479,7 +4479,8 @@ H5P_facc_mdc_log_location_close(const char H5_ATTR_UNUSED *name, size_t H5_ATTR_
  *-------------------------------------------------------------------------
  */
 herr_t
-H5Pset_evict_on_close(hid_t fapl_id, hbool_t evict_on_close)
+H5Pset_evict_on_close(hid_t fapl_id,
+    hbool_t H5_ATTR_PARALLEL_UNUSED evict_on_close)
 {
     H5P_genplist_t *plist;          /* property list pointer */
     herr_t ret_value = SUCCEED;     /* return value */
diff --git a/src/H5VLnative_attr.c b/src/H5VLnative_attr.c
index e54c49f..8072cd5 100644
--- a/src/H5VLnative_attr.c
+++ b/src/H5VLnative_attr.c
@@ -525,7 +525,8 @@ done:
  */
 herr_t
 H5VL__native_attr_optional(void H5_ATTR_UNUSED *obj, H5VL_attr_optional_t opt_type,
-    hid_t H5_ATTR_UNUSED dxpl_id, void H5_ATTR_UNUSED **req, va_list arguments)
+    hid_t H5_ATTR_UNUSED dxpl_id, void H5_ATTR_UNUSED **req,
+    va_list H5_ATTR_DEPRECATED_USED arguments)
 {
     herr_t ret_value = SUCCEED;    /* Return value */
 
diff --git a/src/H5VLnative_group.c b/src/H5VLnative_group.c
index 3fdb2d9..236ee9d 100644
--- a/src/H5VLnative_group.c
+++ b/src/H5VLnative_group.c
@@ -266,8 +266,9 @@ done:
  *-------------------------------------------------------------------------
  */
 herr_t
-H5VL__native_group_optional(void *obj, H5VL_group_optional_t optional_type,
-    hid_t H5_ATTR_UNUSED dxpl_id, void H5_ATTR_UNUSED **req, va_list arguments)
+H5VL__native_group_optional(void H5_ATTR_UNUSED *obj,
+    H5VL_group_optional_t optional_type, hid_t H5_ATTR_UNUSED dxpl_id,
+    void H5_ATTR_UNUSED **req, va_list H5_ATTR_DEPRECATED_USED arguments)
 {
     herr_t ret_value = SUCCEED;    /* Return value */
 
diff --git a/src/H5Z.c b/src/H5Z.c
index 53186f1..2f477a3 100644
--- a/src/H5Z.c
+++ b/src/H5Z.c
@@ -585,7 +585,8 @@ done:
  *-------------------------------------------------------------------------
  */
 static int
-H5Z__flush_file_cb(void *obj_ptr, hid_t H5_ATTR_UNUSED obj_id, void *key)
+H5Z__flush_file_cb(void *obj_ptr, hid_t H5_ATTR_UNUSED obj_id,
+    void *key H5_ATTR_PARALLEL_USED)
 {
     H5F_t          *f           = (H5F_t *)obj_ptr;     /* File object for operations */
 #ifdef H5_HAVE_PARALLEL
diff --git a/src/H5private.h b/src/H5private.h
index 700fe8a..3759446 100644
--- a/src/H5private.h
+++ b/src/H5private.h
@@ -304,17 +304,38 @@
  * file). Be sure to update that file if the #ifdefs change here.
  */
 #ifdef __cplusplus
-#   define H5_ATTR_FORMAT(X,Y,Z)  /*void*/
-#   define H5_ATTR_UNUSED         /*void*/
-#   define H5_ATTR_NDEBUG_UNUSED  /*void*/
-#   define H5_ATTR_NORETURN       /*void*/
-#   define H5_ATTR_CONST          /*void*/
-#   define H5_ATTR_PURE           /*void*/
-#   define H5_ATTR_FALLTHROUGH    /*void*/
+#   define H5_ATTR_FORMAT(X,Y,Z)                /*void*/
+#   define H5_ATTR_UNUSED                       /*void*/
+#   define H5_ATTR_DEPRECATED_USED              /*void*/
+#   define H5_ATTR_NDEBUG_UNUSED                /*void*/
+#   define H5_ATTR_DEBUG_API_USED               /*void*/
+#   define H5_ATTR_PARALLEL_UNUSED              /*void*/
+#   define H5_ATTR_PARALLEL_USED                /*void*/
+#   define H5_ATTR_NORETURN                     /*void*/
+#   define H5_ATTR_CONST                        /*void*/
+#   define H5_ATTR_PURE                         /*void*/
+#   define H5_ATTR_FALLTHROUGH                  /*void*/
 #else /* __cplusplus */
 #if defined(H5_HAVE_ATTRIBUTE) && !defined(__SUNPRO_C)
 #   define H5_ATTR_FORMAT(X,Y,Z)  __attribute__((format(X, Y, Z)))
 #   define H5_ATTR_UNUSED       __attribute__((unused))
+#ifdef H5_HAVE_PARALLEL
+#   define H5_ATTR_PARALLEL_UNUSED       __attribute__((unused))
+#   define H5_ATTR_PARALLEL_USED         /*void*/
+#else
+#   define H5_ATTR_PARALLEL_UNUSED       /*void*/
+#   define H5_ATTR_PARALLEL_USED         __attribute__((unused))
+#endif
+#ifdef H5_NO_DEPRECATED_SYMBOLS
+#define H5_ATTR_DEPRECATED_USED    H5_ATTR_UNUSED
+#else /* H5_NO_DEPRECATED_SYMBOLS */
+#define H5_ATTR_DEPRECATED_USED    /*void*/
+#endif /* H5_NO_DEPRECATED_SYMBOLS */
+#ifdef H5_DEBUG_API
+#define H5_ATTR_DEBUG_API_USED    /*void*/
+#else /* H5_DEBUG_API */
+#define H5_ATTR_DEBUG_API_USED    H5_ATTR_UNUSED
+#endif /* H5_DEBUG_API */
 #ifndef NDEBUG
 #define H5_ATTR_NDEBUG_UNUSED     /*void*/
 #else /* NDEBUG */
@@ -329,13 +350,17 @@
 #   define H5_ATTR_FALLTHROUGH  /*void*/
 #endif
 #else
-#   define H5_ATTR_FORMAT(X,Y,Z)  /*void*/
-#   define H5_ATTR_UNUSED         /*void*/
-#   define H5_ATTR_NDEBUG_UNUSED  /*void*/
-#   define H5_ATTR_NORETURN       /*void*/
-#   define H5_ATTR_CONST          /*void*/
-#   define H5_ATTR_PURE           /*void*/
-#   define H5_ATTR_FALLTHROUGH    /*void*/
+#   define H5_ATTR_FORMAT(X,Y,Z)    /*void*/
+#   define H5_ATTR_UNUSED           /*void*/
+#   define H5_ATTR_NDEBUG_UNUSED    /*void*/
+#   define H5_ATTR_DEBUG_API_USED   /*void*/
+#   define H5_ATTR_DEPRECATED_USED  /*void*/
+#   define H5_ATTR_PARALLEL_UNUSED  /*void*/
+#   define H5_ATTR_PARALLEL_USED    /*void*/
+#   define H5_ATTR_NORETURN         /*void*/
+#   define H5_ATTR_CONST            /*void*/
+#   define H5_ATTR_PURE             /*void*/
+#   define H5_ATTR_FALLTHROUGH      /*void*/
 #endif
 #endif /* __cplusplus */
 
diff --git a/test/gen_new_super.c b/test/gen_new_super.c
index f6ce589..ed43a39 100644
--- a/test/gen_new_super.c
+++ b/test/gen_new_super.c
@@ -24,7 +24,7 @@
  */
 
 #include <assert.h>
-#include "hdf5.h"
+#include "testhdf5.h"
 
 #define TESTFILE   "tsupern.h5"
 #define ISTORE_IK  64
@@ -50,7 +50,7 @@ main(void)
 {
     hid_t       file;           /* File IDs for old & new files */
     hid_t       fcpl;           /* File creation property list */
-    herr_t      ret;            /* Generic return value */
+    herr_t      H5_ATTR_NDEBUG_UNUSED ret;
 
     /* Create a file creation property list */
     fcpl = H5Pcreate(H5P_FILE_CREATE);
diff --git a/test/gen_nullspace.c b/test/gen_nullspace.c
index 9d76deb..e4e75ac 100644
--- a/test/gen_nullspace.c
+++ b/test/gen_nullspace.c
@@ -24,8 +24,8 @@
  *      put into the 'test' directory in the 1.6.x branch of the library.
  */
 
-#include "hdf5.h"
 #include <assert.h>
+#include "testhdf5.h"
 
 #define NULLFILE   "tnullspace.h5"
 #define NULLDATASET  "null_dataset"
@@ -39,7 +39,7 @@ main(void)
     hid_t sid;          /* Dataspace ID */
     hid_t did;          /* Dataset ID */
     hid_t attr;         /* Attribute ID */
-    herr_t ret;         /* Generic return value */
+    herr_t H5_ATTR_NDEBUG_UNUSED ret;         /* Generic return value */
 
     /* Create the file */
     fid = H5Fcreate(NULLFILE, H5F_ACC_TRUNC, H5P_DEFAULT, H5P_DEFAULT);
diff --git a/test/gen_plist.c b/test/gen_plist.c
index 8f38b1a..8fc8a05 100644
--- a/test/gen_plist.c
+++ b/test/gen_plist.c
@@ -458,7 +458,7 @@ encode_plist(hid_t plist_id, int little_endian, int word_length, const char *fil
     herr_t ret = 0;
     void *temp_buf = NULL;
     size_t temp_size = 0;
-    ssize_t write_size;
+    ssize_t H5_ATTR_NDEBUG_UNUSED write_size;
     char filename[1024];
 
     /* Generate filename */
diff --git a/test/gen_specmetaread.c b/test/gen_specmetaread.c
index d06bd59..fd484d1 100644
--- a/test/gen_specmetaread.c
+++ b/test/gen_specmetaread.c
@@ -23,9 +23,10 @@
  *      the library on the trunk as of when this file is checked in.
  */
 
-#include "hdf5.h"
 #include <assert.h>
 
+#include "testhdf5.h"
+
 #define FILENAME        "specmetaread.h5"
 #define DIM             10
 
@@ -39,7 +40,7 @@ main(void)
     hsize_t     dim[1] = {DIM};
     unsigned    data[DIM];
     unsigned    u;
-    herr_t      ret;         /* Generic return value */
+    herr_t      H5_ATTR_NDEBUG_UNUSED ret;
 
     /* Initialize the data */
     for(u = 0; u < DIM; u++)
diff --git a/test/ttsafe_cancel.c b/test/ttsafe_cancel.c
index dd52232..f6bcd0d 100644
--- a/test/ttsafe_cancel.c
+++ b/test/ttsafe_cancel.c
@@ -61,7 +61,7 @@ tts_cancel(void)
     pthread_attr_t attribute;
     hid_t dataset;
     int buffer;
-    int ret;
+    int H5_ATTR_NDEBUG_UNUSED ret;
 
     /* make thread scheduling global */
     ret=pthread_attr_init(&attribute);
diff --git a/tools/test/h5dump/h5dumpgentest.c b/tools/test/h5dump/h5dumpgentest.c
index e68e622..d72664e 100644
--- a/tools/test/h5dump/h5dumpgentest.c
+++ b/tools/test/h5dump/h5dumpgentest.c
@@ -3093,7 +3093,7 @@ static void gent_array1(void)
     hsize_t  sdims1[] = {SPACE1_DIM1};
     hsize_t  tdims1[] = {ARRAY1_DIM1};
     int        i,j;        /* counting variables */
-    herr_t  ret;  /* Generic return value  */
+    herr_t  ret H5_ATTR_NDEBUG_UNUSED;  /* Generic return value  */
 
     /* Allocate and initialize array data to write */
     for(i=0; i<SPACE1_DIM1; i++)