Add helpful text to h5clear (#3754)

Added text to the usage of h5clear to explain that this tool is not
for fixing corrupted files but simply for helping in the inspection
of the damage..

Fixed expected output for testing the modified usage.

3 files changed, 27 insertions, 6 deletions

diff --git a/tools/src/misc/h5clear.c b/tools/src/misc/h5clear.c
index 31f7c17..ea3e072 100644
--- a/tools/src/misc/h5clear.c
+++ b/tools/src/misc/h5clear.c
@@ -61,6 +61,13 @@ static struct h5_long_options l_opts[] = {
 static void
 usage(const char *prog)
 {
+    fprintf(stdout, "h5clear clears superblock status flag field, removes metadata cache image, prints\n");
+    fprintf(stdout, "EOA and EOF, or sets EOA of a file.  It is not a general repair tool and should not\n");
+    fprintf(stdout, "be used to fix file corruption.  If a process doesn't shut down cleanly, the\n");
+    fprintf(stdout, "superblock mark can be left that prevents opening a file without SWMR.  Then,\n");
+    fprintf(stdout, "h5clear can be used to remove this superblock mark so that the file can be inspected\n");
+    fprintf(stdout, "and appropriate actions can be taken.\n");
+    fprintf(stdout, "\n");
     fprintf(stdout, "usage: %s [OPTIONS] file_name\n", prog);
     fprintf(stdout, "  OPTIONS\n");
     fprintf(stdout, "   -h, --help                Print a usage message and exit\n");
@@ -73,8 +80,8 @@ usage(const char *prog)
     fprintf(stdout,
             "                             C is >= 0; C is optional and will default to 1M when not set.\n");
     fprintf(stdout,
-            "                             This option helps to repair a crashed file where the stored EOA\n");
-    fprintf(stdout, "                             in the superblock is different from the actual EOF.\n");
+            "                             This option helps to repair a crashed SWMR file when the stored\n");
+    fprintf(stdout, "                             EOA in the superblock is different from the actual EOF.\n");
     fprintf(stdout, "                             The file's EOA and EOF will be the same after applying\n");
     fprintf(stdout, "                             this option to the file.\n");
     fprintf(stdout, "\n");
diff --git a/tools/test/misc/expected/h5clear_missing_file.ddl b/tools/test/misc/expected/h5clear_missing_file.ddl
index c7a2118..fe659af 100644
--- a/tools/test/misc/expected/h5clear_missing_file.ddl
+++ b/tools/test/misc/expected/h5clear_missing_file.ddl
@@ -1,3 +1,10 @@
+h5clear clears superblock status flag field, removes metadata cache image, prints
+EOA and EOF, or sets EOA of a file.  It is not a general repair tool and should not
+be used to fix file corruption.  If a process doesn't shut down cleanly, the
+superblock mark can be left that prevents opening a file without SWMR.  Then,
+h5clear can be used to remove this superblock mark so that the file can be inspected
+and appropriate actions can be taken.
+
 usage: h5clear [OPTIONS] file_name
   OPTIONS
    -h, --help                Print a usage message and exit
@@ -8,8 +15,8 @@ usage: h5clear [OPTIONS] file_name
    --increment=C             Set the file's EOA to the maximum of (EOA, EOF) + C for
                              the file <file_name>.
                              C is >= 0; C is optional and will default to 1M when not set.
-                             This option helps to repair a crashed file where the stored EOA
-                             in the superblock is different from the actual EOF.
+                             This option helps to repair a crashed SWMR file when the stored
+                             EOA in the superblock is different from the actual EOF.
                              The file's EOA and EOF will be the same after applying
                              this option to the file.
 
diff --git a/tools/test/misc/expected/h5clear_usage.ddl b/tools/test/misc/expected/h5clear_usage.ddl
index c7a2118..fe659af 100644
--- a/tools/test/misc/expected/h5clear_usage.ddl
+++ b/tools/test/misc/expected/h5clear_usage.ddl
@@ -1,3 +1,10 @@
+h5clear clears superblock status flag field, removes metadata cache image, prints
+EOA and EOF, or sets EOA of a file.  It is not a general repair tool and should not
+be used to fix file corruption.  If a process doesn't shut down cleanly, the
+superblock mark can be left that prevents opening a file without SWMR.  Then,
+h5clear can be used to remove this superblock mark so that the file can be inspected
+and appropriate actions can be taken.
+
 usage: h5clear [OPTIONS] file_name
   OPTIONS
    -h, --help                Print a usage message and exit
@@ -8,8 +15,8 @@ usage: h5clear [OPTIONS] file_name
    --increment=C             Set the file's EOA to the maximum of (EOA, EOF) + C for
                              the file <file_name>.
                              C is >= 0; C is optional and will default to 1M when not set.
-                             This option helps to repair a crashed file where the stored EOA
-                             in the superblock is different from the actual EOF.
+                             This option helps to repair a crashed SWMR file when the stored
+                             EOA in the superblock is different from the actual EOF.
                              The file's EOA and EOF will be the same after applying
                              this option to the file.