Improve the usage of h5clear (#3757)

- 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.

Fixed GH #3054

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.