FORGE-2680. Add a long description to better document command using m…

…an page
forge · Sep 8, 2016 · 7d71b7f · 7d71b7f
1 parent 1ba0b2f
commit 7d71b7f
Show file tree

Hide file tree

Showing 5 changed files with 55 additions and 14 deletions.
diff --git a/shell/impl/src/main/java/org/jboss/forge/addon/shell/aesh/ForgeManProvider.java b/shell/impl/src/main/java/org/jboss/forge/addon/shell/aesh/ForgeManProvider.java
@@ -31,6 +31,7 @@
 import org.jboss.forge.addon.ui.input.InputComponentFactory;
 import org.jboss.forge.addon.ui.input.ManyValued;
 import org.jboss.forge.addon.ui.input.SelectComponent;
+import org.jboss.forge.addon.ui.metadata.UICommandMetadata;
 import org.jboss.forge.addon.ui.util.InputComponents;
 import org.jboss.forge.addon.ui.wizard.UIWizard;
 import org.jboss.forge.furnace.util.OperatingSystemUtils;
@@ -136,10 +137,9 @@ public InputComponentFactory getInputComponentFactory()
          result = result.replaceAll("%description%", cmd.getMetadata(context).getCategory().toString());
 
          result = result.replaceAll("%synopsis%", buildSynopsis(cmd, context, inputs));
-         result = result.replaceAll("%options%", buildOptions(cmd, context, inputs));
+         result = result.replaceAll("%options%", buildOptions(cmd, context, inputs).trim());
          result = result.replaceAll("%addon%", getSourceAddonName(cmd, context));
          result = result.replaceAll("%year%", String.valueOf(Calendar.getInstance().get(Calendar.YEAR)));
-
          return new ByteArrayInputStream(result.getBytes());
       }
       catch (Exception e)
@@ -203,11 +203,19 @@ private String buildOptions(UICommand cmd, UIContext context, List<InputComponen
    {
       StringBuilder result = new StringBuilder();
 
-      if (cmd.getMetadata(context).getDescription() != null)
-         result.append(cmd.getMetadata(context).getDescription());
-      if (UIWizard.class.isAssignableFrom(cmd.getMetadata(context).getType()))
+      UICommandMetadata metadata = cmd.getMetadata(context);
+      if (metadata.getLongDescription() != null)
+      {
+         result.append(metadata.getLongDescription().trim());
+      }
+      else if (metadata.getDescription() != null)
+      {
+         result.append(metadata.getDescription().trim());
+      }
+      if (UIWizard.class.isAssignableFrom(metadata.getType()))
+      {
          result.append(" (*multi-step wizard* - some options may not be auto-documented in this man page.)");
-
+      }
       result.append(OperatingSystemUtils.getLineSeparator()).append(OperatingSystemUtils.getLineSeparator());
 
       Collections.sort(inputs, SHORTNAME_COMPARATOR);
@@ -254,7 +262,7 @@ private String buildOptions(UICommand cmd, UIContext context, List<InputComponen
                   if (choice != null)
                   {
                      Object itemLabel = itemLabelConverter.convert(choice);
-                     result.append("\"" + itemLabel + "\" ");
+                     result.append("\"").append(itemLabel).append("\" ");
                   }
                }
                result.append("] ");
@@ -274,7 +282,7 @@ private String buildOptions(UICommand cmd, UIContext context, List<InputComponen
                               Object itemLabel = value.toString();
                               if (itemLabelConverter != null)
                                  itemLabel = itemLabelConverter.convert(value);
-                              result.append("\"" + itemLabel + "\" ");
+                              result.append("\"").append(itemLabel).append("\" ");
                            }
                         }
                      }
@@ -286,7 +294,7 @@ private String buildOptions(UICommand cmd, UIContext context, List<InputComponen
                            Object itemLabel = value.toString();
                            if (itemLabelConverter != null)
                               itemLabel = itemLabelConverter.convert(value);
-                           result.append("\"" + itemLabel + "\" ");
+                           result.append("\"").append(itemLabel).append("\" ");
                         }
                      }
                   }
@@ -304,9 +312,14 @@ else if (input.hasDefaultValue())
       if (arguments != null)
       {
          result.append("[");
-         result.append(arguments.getLabel() == null ? "L " + arguments.getValueType().getSimpleName()
-                  + "; ... arguments"
-                  : arguments.getLabel());
+         if (arguments.getLabel() == null)
+         {
+            result.append("L ").append(arguments.getValueType().getSimpleName()).append("; ... arguments");
+         }
+         else
+         {
+            result.append(arguments.getLabel());
+         }
          result.append("] ");
       }
 

diff --git a/shell/impl/src/main/java/org/jboss/forge/addon/shell/command/CommandListCommand.java b/shell/impl/src/main/java/org/jboss/forge/addon/shell/command/CommandListCommand.java
@@ -31,6 +31,7 @@
 import org.jboss.forge.addon.ui.result.Result;
 import org.jboss.forge.addon.ui.result.Results;
 import org.jboss.forge.addon.ui.util.Metadata;
+import org.jboss.forge.furnace.util.OperatingSystemUtils;
 
 /**
  * Lists all the available commands
@@ -42,11 +43,19 @@ public class CommandListCommand extends AbstractShellCommand
 {
    @Inject
    private CommandFactory commandFactory;
+   private static final String CMD_LIST_HELP_DESCRIPTION = "List all available commands. Each line starts with the category to which a command belongs followed by the name and the command description."
+           + OperatingSystemUtils.getLineSeparator()
+           + "When a command is not available within the context of the shell where it is executed, then the name of the command is displayed in red otherwise in green."
+           + OperatingSystemUtils.getLineSeparator()
+           + "By example, it is not possible to add a module or fraction using the command 'wildfly-swarm-add-fraction' if the Wildfly Swarm project doesn't exist !";
 
    @Override
    public UICommandMetadata getMetadata(UIContext context)
    {
-      return Metadata.forCommand(getClass()).name("command-list").description("List all available commands.");
+      return Metadata.forCommand(getClass())
+                     .name("command-list")
+                     .description("List all available commands.")
+                     .longDescription(CMD_LIST_HELP_DESCRIPTION);
    }
 
    @Override

diff --git a/shell/impl/src/main/resources/org/jboss/forge/addon/shell/aesh/DefaultManPage.txt b/shell/impl/src/main/resources/org/jboss/forge/addon/shell/aesh/DefaultManPage.txt
@@ -17,8 +17,9 @@ DESCRIPTION
 -----------
 %options%
 
+
 FROM ADDON
-------
+----------
 %addon%
 
 

diff --git a/ui/api/src/main/java/org/jboss/forge/addon/ui/metadata/UICommandMetadata.java b/ui/api/src/main/java/org/jboss/forge/addon/ui/metadata/UICommandMetadata.java
@@ -38,6 +38,12 @@ public interface UICommandMetadata
     */
    String getDescription();
 
+   /**
+    * Returns the long description of the corresponding {@Link UICommand}.
+    * This description will be used to document the command within by the Forge Shell using man
+    */
+   String getLongDescription();
+
    /**
     * Returns the {@link UICategory} of the corresponding {@link UICommand}.
     */

diff --git a/ui/api/src/main/java/org/jboss/forge/addon/ui/util/Metadata.java b/ui/api/src/main/java/org/jboss/forge/addon/ui/util/Metadata.java
@@ -29,6 +29,7 @@ public class Metadata implements UICommandMetadata
 
    private String name;
    private String description;
+   private String longDescription;
    private UICategory category;
    private URL docLocation;
    private boolean deprecated;
@@ -84,6 +85,15 @@ public Metadata description(String description)
       return this;
    }
 
+   /**
+    * Set the long description for the corresponding {@link UICommand}.
+    */
+   public Metadata longDescription(String description)
+   {
+      this.longDescription = description;
+      return this;
+   }
+
    /**
     * Set the {@link UICategory} of the corresponding {@link UICommand}.
     */
@@ -147,6 +157,8 @@ public String getDescription()
       return description;
    }
 
+   @Override public String getLongDescription() { return longDescription; }
+
    @Override
    public UICategory getCategory()
    {