[CLI-339] Help formatter extension #314

- Update changes.xml
- Sort members
- Only use Javadoc @SInCE tags for public and protected elements
- Javadoc: Break before tags
- Javadoc: Write complete sentences.
- Javadoc: Use @code
- Javadoc: Sentences start with a capital letter
- Add missing @OverRide annotation
- Use final
- Rename asArgName to toArgName (it calls another toArgName)
- Whitespace
- Use longer lines
- Normalize test method names
- Name test methods after the methods they test

Author: garydgregory

src/changes/changes.xml

@@ -25,6 +25,7 @@
     <release version="1.9.1" date="YYYY-MM-DD" description="This is a feature and maintenance release. Java 8 or later is required.">
       <!-- FIX -->
       <!-- ADD -->
+      <action type="add" issue="CLI-339" dev="ggregory" due-to="Claude Warren, Gary Gregory">Help formatter extension #314.</action>
       <!-- UPDATE -->
       <action type="update" dev="ggregory" due-to="Gary Gregory, Dependabot">Bump org.apache.commons:commons-parent from 72 to 77 #302, #304, #310, #315, #320.</action>
       <action type="update" dev="ggregory" due-to="Gary Gregory, Dependabot">Bump commons-io:commons-io from 2.16.1 to 2.17.0 #309.</action>

src/main/java/org/apache/commons/cli/HelpFormatter.java

@@ -54,17 +54,17 @@ Licensed to the Apache Software Foundation (ASF) under one or more
  * <p>
  * This produces the following output:
  * </p>
- * <pre>
- * usage: myapp -f &lt;FILE&gt; [-h] [-v]
+ * <pre>{@code
+ * usage: myapp -f <FILE> [-h] [-v]
  * Do something useful with an input file
  *
- *  -f,--file &lt;FILE&gt;   The file to be processed
+ *  -f,--file <FILE>   The file to be processed
  *  -h,--help
  *  -v,--version       Print the version of the application
  *
  * Please report issues at https://example.com/issues
- * </pre>
- * @deprecated Use {@link org.apache.commons.cli.help.HelpFormatter}
+ * }</pre>
+ * @deprecated Use {@link org.apache.commons.cli.help.HelpFormatter}.
  */
 @Deprecated
 public class HelpFormatter {

src/main/java/org/apache/commons/cli/help/AbstractHelpFormatter.java

@@ -20,31 +20,34 @@ Licensed to the Apache Software Foundation (ASF) under one or more
 
 /**
  * An abstract implementation of {@link HelpWriter} that writes output to an {@link Appendable} instance.
+ *
  * @since 1.10.0
  */
 public abstract class AbstractHelpWriter implements HelpWriter {
+
     /**
      * The Appendable instance to write to.
      */
     protected final Appendable output;
 
     /**
      * Constructs an instance using the provided Appendable instance.
+     *
      * @param output the Appendable instance to write to.
      */
     protected AbstractHelpWriter(final Appendable output) {
         this.output = output;
     }
 
     @Override
-    public Appendable append(final CharSequence text) throws IOException {
-        output.append(text);
+    public Appendable append(final char ch) throws IOException {
+        output.append(ch);
         return this;
     }
 
     @Override
-    public Appendable append(final char ch) throws IOException {
-        output.append(ch);
+    public Appendable append(final CharSequence text) throws IOException {
+        output.append(text);
         return this;
     }
 

src/main/java/org/apache/commons/cli/help/AbstractHelpWriter.java

@@ -29,6 +29,7 @@ Licensed to the Apache Software Foundation (ASF) under one or more
  * <p>
  * Example:
  * </p>
+ *
  * <pre>
  * Options options = new Options();
  * options.addOption(OptionBuilder.withLongOpt("file").withDescription("The file to be processed").hasArg().withArgName("FILE").isRequired().create('f'));
@@ -44,6 +45,7 @@ Licensed to the Apache Software Foundation (ASF) under one or more
  * <p>
  * This produces the following output:
  * </p>
+ *
  * <pre>
  *     {@code
  * usage: myapp -f <FILE> [-h] [-v]
@@ -56,47 +58,41 @@ Licensed to the Apache Software Foundation (ASF) under one or more
  * Please report issues at https://example.com/issues
  * }
  * </pre>
+ *
  * @since 1.10.0
  */
 public class HelpFormatter extends AbstractHelpFormatter {
-    /** Default number of characters per line */
-    public static final int DEFAULT_WIDTH = 74;
-
-    /** Default padding to the left of each line */
-    public static final int DEFAULT_LEFT_PAD = 1;
-
-    /** Number of space characters to be prefixed to each description line */
-    public static final int DEFAULT_INDENT = 3;
-
-    /** The default number of spaces between columns in the options table */
-    public static final int DEFAULT_COLUMN_SPACING = 5;
-
-    /** If {@code true} show the "Since" column, otherwise ignore it. */
-    private final boolean showSince;
 
     /**
-     * A builder for the HelpFormatter.  Intended to make more complex uses of the HelpFormatter class easier.
-     * Default values are:
+     * A builder for the HelpFormatter. Intended to make more complex uses of the HelpFormatter class easier. Default values are:
      * <ul>
-     *     <li>showSince = true</li>
-     *     <li>helpWriter = a {@link TextHelpWriter} writing to {@code System.out}</li>
-     *     <li>optionFormatter.Builder = the default {@link OptionFormatter.Builder}</li>
+     * <li>showSince = true</li>
+     * <li>helpWriter = a {@link TextHelpWriter} writing to {@code System.out}</li>
+     * <li>optionFormatter.Builder = the default {@link OptionFormatter.Builder}</li>
      * </ul>
      */
     public static class Builder {
+
         /** If {@code true} show the "Since" column, otherwise ignore it. */
         private boolean showSince;
+
         /** The {@link HelpWriter} to use */
         private HelpWriter helpWriter;
+
         /** The {@link OptionFormatter.Builder} to use to format options in the table. */
         private OptionFormatter.Builder optionFormatBuilder;
+
         /** The string to separate option groups with */
         private String optionGroupSeparator;
+
         /** The comparator to sort lists of options */
         private Comparator<Option> comparator;
+
         /**
-         * Constructor.
-         * <p>sets the showSince to {@code true}</p>
+         * Constructs a new instace.
+         * <p>
+         * Sets {@code showSince} to {@code true}.
+         * </p>
          */
         public Builder() {
             showSince = true;
@@ -105,27 +101,29 @@ public Builder() {
         }
 
         /**
-         * Sets the showSince flag.
-         * @param showSince the desired value of the showSince flag.
+         * Constructs the {@link HelpFormatter}.
+         *
          * @return this.
          */
-        public Builder setShowSince(final boolean showSince) {
-            this.showSince = showSince;
-            return this;
+        public HelpFormatter build() {
+            validate();
+            return new HelpFormatter(this);
         }
 
         /**
-         * Sets the {@link HelpWriter}.
-         * @param helpWriter the {@link HelpWriter} to use.
+         * Sets the comparator to use for sorting opitons. If set to {@code null} no sorting is performed.
+         *
+         * @param comparator The comparator to use for sorting opitons.
          * @return this
          */
-        public Builder setSerializer(final HelpWriter helpWriter) {
-            this.helpWriter = helpWriter;
+        public Builder setComparator(final Comparator<Option> comparator) {
+            this.comparator = comparator;
             return this;
         }
 
         /**
          * Sets the {@link OptionFormatter.Builder}.
+         *
          * @param optionFormatBuilder the {@link OptionFormatter.Builder} to use.
          * @return this
          */
@@ -135,8 +133,8 @@ public Builder setOptionFormatBuilder(final OptionFormatter.Builder optionFormat
         }
 
         /**
-         * Sets the OptionGroup separator.  Normally " | " or something similar to denote that only one option may
-         * be chosen.
+         * Sets the OptionGroup separator. Normally " | " or something similar to denote that only one option may be chosen.
+         *
          * @param optionGroupSeparator the string to separate option group elements with.
          * @return this
          */
@@ -146,17 +144,30 @@ public Builder setOptionGroupSeparator(final String optionGroupSeparator) {
         }
 
         /**
-         * Sets the comparator to use for sorting opitons.  If set to {@code null} no sorting is performed.
-         * @param comparator The comparator to use for sorting opitons.
+         * Sets the {@link HelpWriter}.
+         *
+         * @param helpWriter the {@link HelpWriter} to use.
          * @return this
          */
-        public Builder setComparator(final Comparator<Option> comparator) {
-            this.comparator = comparator;
+        public Builder setSerializer(final HelpWriter helpWriter) {
+            this.helpWriter = helpWriter;
+            return this;
+        }
+
+        /**
+         * Sets the showSince flag.
+         *
+         * @param showSince the desired value of the showSince flag.
+         * @return this.
+         */
+        public Builder setShowSince(final boolean showSince) {
+            this.showSince = showSince;
             return this;
         }
 
         /**
          * Performs a sanity check and sets default values if they are not set.
+         *
          * @return this.
          */
         private Builder validate() {
@@ -168,55 +179,63 @@ private Builder validate() {
             }
             return this;
         }
-
-        /**
-         * Constructs the {@link HelpFormatter}.
-         * @return this.
-         */
-        public HelpFormatter build() {
-            validate();
-            return new HelpFormatter(this);
-        }
     }
 
+    /** Default number of characters per line */
+    public static final int DEFAULT_WIDTH = 74;
+
+    /** Default padding to the left of each line */
+    public static final int DEFAULT_LEFT_PAD = 1;
+
+    /** Number of space characters to be prefixed to each description line */
+    public static final int DEFAULT_INDENT = 3;
+
+    /** The default number of spaces between columns in the options table */
+    public static final int DEFAULT_COLUMN_SPACING = 5;
+
+    /** If {@code true} show the "Since" column, otherwise ignore it. */
+    private final boolean showSince;
+
     /**
      * Constructs a new instance using the default {@link Builder}.
+     *
      * @see Builder
      */
     public HelpFormatter() {
         this(new Builder().validate());
     }
 
-    /**
-     * Convenience constructor to create an instance using the specified {@link HelpWriter} and the
-     * remaining default {@link Builder}.
-     * @param helpWriter the {@link HelpWriter} to use.
-     */
-    public HelpFormatter(final HelpWriter helpWriter) {
-        this(new Builder().setSerializer(helpWriter).validate());
-    }
-
     /**
      * Constructs the Help formatter.
+     *
      * @param builder the Builder to build from.
      */
     private HelpFormatter(final Builder builder) {
-        super(builder.helpWriter, builder.optionFormatBuilder, builder.comparator,
-                builder.optionGroupSeparator);
+        super(builder.helpWriter, builder.optionFormatBuilder, builder.comparator, builder.optionGroupSeparator);
 
         this.showSince = builder.showSince;
     }
 
+    /**
+     * Convenience constructor to create an instance using the specified {@link HelpWriter} and the remaining default {@link Builder}.
+     *
+     * @param helpWriter the {@link HelpWriter} to use.
+     */
+    public HelpFormatter(final HelpWriter helpWriter) {
+        this(new Builder().setSerializer(helpWriter).validate());
+    }
+
     /**
      * Gets the table definition for the options.
+     *
      * @param options the collection of {@link Option} instances to create the table from.
      * @return A {@link TableDefinition} to display the options.
      */
+    @Override
     public TableDefinition getTableDefinition(final Iterable<Option> options) {
         // set up the base TextStyle for the columns configured for the Option opt and arg values..
-        TextStyle.Builder builder = new TextStyle.Builder().setAlignment(TextStyle.Alignment.LEFT)
-                .setIndent(DEFAULT_LEFT_PAD).setScalable(false);
-        List<TextStyle> styles = new ArrayList<>();
+        final TextStyle.Builder builder = new TextStyle.Builder().setAlignment(TextStyle.Alignment.LEFT).setIndent(DEFAULT_LEFT_PAD).setScalable(false);
+        final List<TextStyle> styles = new ArrayList<>();
         styles.add(builder.get());
         // set up showSince column
         builder.setScalable(true).setLeftPad(DEFAULT_COLUMN_SPACING);
@@ -229,12 +248,12 @@ public TableDefinition getTableDefinition(final Iterable<Option> options) {
         styles.add(builder.get());
 
         // setup the rows for the table.
-        List<List<String>> rows = new ArrayList<>();
-        StringBuilder sb = new StringBuilder();
-        for (Option option : options) {
-            List<String> row = new ArrayList<>();
+        final List<List<String>> rows = new ArrayList<>();
+        final StringBuilder sb = new StringBuilder();
+        for (final Option option : options) {
+            final List<String> row = new ArrayList<>();
             // create an option formatter to correctly format the parts of the option
-            OptionFormatter formatter = optionFormatBuilder.build(option);
+            final OptionFormatter formatter = optionFormatBuilder.build(option);
             sb.setLength(0);
             // append the opt values.
             sb.append(formatter.getBothOpt());
@@ -253,7 +272,7 @@ public TableDefinition getTableDefinition(final Iterable<Option> options) {
         }
 
         // return the TableDefinition with the proper column headers.
-        return showSince ? TableDefinition.from("", styles, Arrays.asList("Options", "Since", "Description"), rows) :
-                TableDefinition.from("", styles, Arrays.asList("Options", "Description"), rows);
+        return showSince ? TableDefinition.from("", styles, Arrays.asList("Options", "Since", "Description"), rows)
+                : TableDefinition.from("", styles, Arrays.asList("Options", "Description"), rows);
     }
 }