ENT-5039 Improved help text for commands (#6006)

* Improved help text for commands

* Address feedback

build.gradle

@@ -104,7 +104,7 @@ buildscript {
     ext.dependency_checker_version = '5.2.0'
     ext.commons_collections_version = '4.3'
     ext.beanutils_version = '1.9.3'
-    ext.crash_version = '1.7.2'
+    ext.crash_version = '1.7.4'
     ext.jsr305_version = constants.getProperty("jsr305Version")
     ext.shiro_version = '1.4.1'
     ext.artifactory_plugin_version = constants.getProperty('artifactoryPluginVersion')

tools/shell/src/main/java/net/corda/tools/shell/AttachmentShellCommand.java

@@ -2,6 +2,7 @@ package net.corda.tools.shell;
 
 import org.crsh.cli.Command;
 import org.crsh.cli.Man;
+import org.crsh.cli.Usage;
 
 import static net.corda.tools.shell.InteractiveShell.runAttachmentTrustInfoView;
 
@@ -9,6 +10,7 @@ public class AttachmentShellCommand extends InteractiveShellCommand {
 
     @Command
     @Man("Displays the trusted CorDapp attachments that have been manually installed or received over the network")
+    @Usage("Displays the trusted CorDapp attachments that have been manually installed or received over the network")
     public void trustInfo() {
         runAttachmentTrustInfoView(out, ops());
     }

tools/shell/src/main/java/net/corda/tools/shell/CheckpointShellCommand.java

@@ -2,6 +2,7 @@ package net.corda.tools.shell;
 
 import org.crsh.cli.Command;
 import org.crsh.cli.Man;
+import org.crsh.cli.Usage;
 
 import static net.corda.tools.shell.InteractiveShell.*;
 
@@ -9,6 +10,7 @@ public class CheckpointShellCommand extends InteractiveShellCommand {
 
     @Command
     @Man("Outputs the contents of all checkpoints as json to be manually reviewed")
+    @Usage("Outputs the contents of all checkpoints as json to be manually reviewed")
     public void dump() {
         runDumpCheckpoints(ops());
     }

tools/shell/src/main/java/net/corda/tools/shell/FlowShellCommand.java

@@ -31,7 +31,11 @@ public class FlowShellCommand extends InteractiveShellCommand {
     private static final Logger logger = LoggerFactory.getLogger(FlowShellCommand.class);
 
     @Command
-    @Usage("Start a (work)flow on the node. This is how you can change the ledger.")
+    @Usage("Start a (work)flow on the node. This is how you can change the ledger.\n\n" +
+            "\t\t    Starting flow is the primary way in which you command the node to change the ledger.\n" +
+            "\t\t    This command is generic, so the right way to use it depends on the flow you wish to start. You can use the 'flow start'\n" +
+            "\t\t    command with either a full class name, or a substring of the class name that's unambiguous. The parameters to the\n" +
+            "\t\t    flow constructors (the right one is picked automatically) are then specified using the same syntax as for the run command.\n")
     public void start(
             @Usage("The class name of the flow to run, or an unambiguous substring") @Argument String name,
             @Usage("The data to pass as input") @Argument(unquote = false) List<String> input
@@ -55,7 +59,7 @@ public class FlowShellCommand extends InteractiveShellCommand {
                           ANSIProgressRenderer ansiProgressRenderer,
                           ObjectMapper om) {
         if (name == null) {
-            out.println("You must pass a name for the flow, see 'man flow'", Decoration.bold, Color.red);
+            out.println("You must pass a name for the flow. Example: \"start Yo target: Some other company\"", Decoration.bold, Color.red);
             return;
         }
         String inp = input == null ? "" : String.join(" ", input).trim();

tools/shell/src/main/java/net/corda/tools/shell/HashLookupShellCommand.java

@@ -28,7 +28,11 @@ public class HashLookupShellCommand extends InteractiveShellCommand {
         logger.info("Executing command \"hashLookup\".");
 
         if (txIdHash == null) {
-            out.println("Please provide a hexadecimal transaction Id hash value, see 'man hashLookup'", Decoration.bold, Color.red);
+            out.println("Checks if a transaction matching a specified Id hash value is recorded on this node.\n\n" +
+                    "This is mainly intended to be used for troubleshooting notarisation issues when a\n" +
+                    "state is claimed to be already consumed by another transaction.\n\n" +
+                    "Example usage: hashLookup E470FD8A6350A74217B0A99EA5FB71F091C84C64AD0DE0E72ECC10421D03AAC9");
+            out.println("Please provide a hexadecimal transaction Id hash value", Decoration.bold, Color.red);
             return;
         }
 

tools/shell/src/main/java/net/corda/tools/shell/OutputFormatCommand.java

@@ -15,6 +15,7 @@ import org.crsh.text.RenderPrintWriter;
 import java.util.Map;
 
 @Man("Allows you to see and update the format that's currently used for the commands' output.")
+@Usage("Allows you to see and update the format that's currently used for the commands' output.")
 public class OutputFormatCommand extends InteractiveShellCommand {
 
     public OutputFormatCommand() {}