BP-64: Improve the description of 47 commands for bin/bookkeeper (apa…

…che#4102)

BP-64: Improve the description of 47 commands for bin/bookkeeper (apache#4102)

bookkeeper-server/src/main/java/org/apache/bookkeeper/tools/cli/commands/cookie/CreateCookieCommand.java

@@ -42,6 +42,11 @@ public class CreateCookieCommand extends CookieCommand<Flags> {
 
     private static final String NAME = "create";
     private static final String DESC = "Create a cookie for a given bookie";
+    private static final String USAGE = "cookie_create      Create a cookie for a given bookie\n"
+            + "             Usage:  cookie_create [options]\n"
+            + "             Options:\n"
+            + "             * -cf, --cookie-file\n"
+            + "              The file to be uploaded as cookie (param format: `cookieFilePath`)";
 
     /**
      * Flags to create a cookie for a given bookie.
@@ -73,6 +78,7 @@ public CreateCookieCommand(Flags flags) {
     private CreateCookieCommand(Flags flags, PrintStream console) {
         super(CliSpec.<Flags>newBuilder()
             .withName(NAME)
+            .withUsage(USAGE)
             .withDescription(DESC)
             .withFlags(flags)
             .withConsole(console)

bookkeeper-server/src/main/java/org/apache/bookkeeper/tools/cli/commands/cookie/DeleteCookieCommand.java

@@ -41,6 +41,12 @@ public class DeleteCookieCommand extends CookieCommand<Flags> {
     private static final String NAME = "delete";
     private static final String DESC = "Delete a cookie for a given bookie";
 
+    private static final String USAGE = "cookie_delete      Delete a cookie for a given bookie\n"
+            + "             Usage:  cookie_delete [options]\n"
+            + "             Options:\n"
+            + "             * <bookie-id>\n"
+            + "              The bookie-id to be deleted (param format: `address:port`)";
+
     /**
      * Flags to delete a cookie for a given bookie.
      */
@@ -64,6 +70,7 @@ public DeleteCookieCommand(Flags flags) {
     private DeleteCookieCommand(Flags flags, PrintStream console) {
         super(CliSpec.<Flags>newBuilder()
             .withName(NAME)
+            .withUsage(USAGE)
             .withDescription(DESC)
             .withFlags(flags)
             .withConsole(console)

bookkeeper-server/src/main/java/org/apache/bookkeeper/tools/cli/commands/cookie/GenerateCookieCommand.java

@@ -43,6 +43,22 @@ public class GenerateCookieCommand extends CookieCommand<Flags> {
     private static final String NAME = "generate";
     private static final String DESC = "Generate a cookie for a given bookie";
 
+    private static final String USAGE = "cookie_generate      Generate a cookie for a given bookie\n"
+            + "             Usage:  cookie_generate [options]\n"
+            + "             Options:\n"
+            + "               -i, --instance-id\n"
+            + "              The instance id of the cluster that this bookie belongs to."
+            + " If omitted, it will used the instance id of the cluster that this cli connects to. \n"
+            + "             * -j, --journal-dirs\n"
+            + "              The journal directories used by this bookie "
+                                + "(param format: `journalDir1,...,journalDirM`)\n"
+            + "             * -l, --ledger-dirs\n"
+            + "              The ledger directories used by this bookie (param format: `ledgerDir1,...,ledgerDirN`)\n"
+            + "             * -o, --output-file\n"
+            + "              The output file to save the generated cookie (param format: `cookieLocalFilePath`)\n"
+            + "               -ix, --index-dirs\n"
+            + "              The index directories used by this bookie (param format: `indexDir1,...,indexDirN`)";
+
     /**
      * Flags to generate a cookie for a given bookie.
      */
@@ -96,6 +112,7 @@ public GenerateCookieCommand(Flags flags) {
     private GenerateCookieCommand(Flags flags, PrintStream console) {
         super(CliSpec.<Flags>newBuilder()
             .withName(NAME)
+            .withUsage(USAGE)
             .withDescription(DESC)
             .withFlags(flags)
             .withConsole(console)

bookkeeper-server/src/main/java/org/apache/bookkeeper/tools/cli/commands/cookie/GetCookieCommand.java

@@ -42,6 +42,12 @@ public class GetCookieCommand extends CookieCommand<Flags> {
     private static final String NAME = "get";
     private static final String DESC = "Retrieve a cookie for a given bookie";
 
+    private static final String USAGE = "cookie_get      Retrieve a cookie for a given bookie\n"
+            + "             Usage:  cookie_get [options]\n"
+            + "             Options:\n"
+            + "             * <bookie-id>\n"
+            + "              The bookie-id to get (param format: `address:port`)";
+
     /**
      * Flags to delete a cookie for a given bookie.
      */
@@ -65,6 +71,7 @@ public GetCookieCommand(Flags flags) {
     private GetCookieCommand(Flags flags, PrintStream console) {
         super(CliSpec.<Flags>newBuilder()
             .withName(NAME)
+            .withUsage(USAGE)
             .withDescription(DESC)
             .withFlags(flags)
             .withConsole(console)

bookkeeper-server/src/main/java/org/apache/bookkeeper/tools/cli/commands/cookie/UpdateCookieCommand.java

@@ -43,6 +43,14 @@ public class UpdateCookieCommand extends CookieCommand<Flags> {
     private static final String NAME = "update";
     private static final String DESC = "Update a cookie for a given bookie";
 
+    private static final String USAGE = "cookie_update      Update a cookie for a given bookie\n"
+            + "             Usage:  cookie_update [options]\n"
+            + "             Options:\n"
+            + "             * -cf, --cookie-file\n"
+            + "              The file to be uploaded as cookie (param format: `cookieFilePath`)\n"
+            + "             * <bookie-id>\n"
+            + "              Bookie ID (param format: `address:port`)";
+
     /**
      * Flags to create a cookie for a given bookie.
      */
@@ -73,6 +81,7 @@ public UpdateCookieCommand(Flags flags) {
     private UpdateCookieCommand(Flags flags, PrintStream console) {
         super(CliSpec.<Flags>newBuilder()
             .withName(NAME)
+            .withUsage(USAGE)
             .withDescription(DESC)
             .withFlags(flags)
             .withConsole(console)

bookkeeper-server/src/main/java/org/apache/bookkeeper/tools/cli/helpers/BookieShellCommand.java

@@ -23,6 +23,7 @@
 import org.apache.bookkeeper.tools.common.BKCommand;
 import org.apache.bookkeeper.tools.framework.CliFlags;
 import org.apache.commons.configuration.CompositeConfiguration;
+import org.apache.commons.lang3.StringUtils;
 
 /**
  * This is a util class that converts new cli command to old shell command.
@@ -52,7 +53,8 @@ public int runCmd(String[] args) throws Exception {
 
     @Override
     public String description() {
-        return shellCmdName + " [options]";
+        // format as org.apache.bookkeeper.bookie.BookieShell.MyCommand.description
+        return StringUtils.isBlank(bkCmd.getUsage()) ? shellCmdName + " [options]" : bkCmd.getUsage();
     }
 
     @Override

tools/framework/src/main/java/org/apache/bookkeeper/tools/framework/CliCommand.java

@@ -72,4 +72,8 @@ public void usage() {
         // run with "empty args", which will print the usage for this command group.
         Cli.printUsage(spec);
     }
+
+    public String getUsage() {
+        return spec.usage();
+    }
 }

tools/ledger/src/test/java/org/apache/bookkeeper/tools/cli/commands/cookie/CreateCookieCommandTest.java

@@ -76,7 +76,7 @@ public void testMissingBookieId() {
     }
 
     private void assertPrintUsage(String consoleOutput) {
-        assertPrintUsage(consoleOutput, "create [flags] <bookie-id>");
+        assertPrintUsage(consoleOutput, "cookie_create [options]");
     }
 
     /**

tools/ledger/src/test/java/org/apache/bookkeeper/tools/cli/commands/cookie/UpdateCookieCommandTest.java

@@ -76,7 +76,7 @@ public void testMissingBookieId() {
     }
 
     private void assertPrintUsage(String consoleOutput) {
-        assertPrintUsage(consoleOutput, "update [flags] <bookie-id>");
+        assertPrintUsage(consoleOutput, "cookie_update [options]");
     }
 
     /**