CLI-217: More DefaultParser constructor docs.

Author: chtompki

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

@@ -57,14 +57,44 @@ public class DefaultParser implements CommandLineParser
     /** Flag indicating if partial matching of long options is supported. */
     private  boolean allowPartialMatching;
 
-    /** Creates a new DefaultParser instance with partial matching enabled. */
+    /**
+     * Creates a new DefaultParser instance with partial matching enabled.
+     *
+     * By "partial matching" we mean that given the following code:
+     * <pre>
+     *     {@code
+     *          final Options options = new Options();
+     *      options.addOption(new Option("d", "debug", false, "Turn on debug."));
+     *      options.addOption(new Option("e", "extract", false, "Turn on extract."));
+     *      options.addOption(new Option("o", "option", true, "Turn on option with argument."));
+     *      }
+     * </pre>
+     * with "partial matching" turned on, <code>-de</code> only matches the
+     * <code>"debug"</code> option. However, with "partial matching" disabled,
+     * <code>-de</code> would enable both <code>debug</code> as well as
+     * <code>extract</code> options.
+     */
     public DefaultParser() {
         this.allowPartialMatching = true;
     }
 
     /**
      * Create a new DefaultParser instance with the specified partial matching policy.
      *
+     * By "partial matching" we mean that given the following code:
+     * <pre>
+     *     {@code
+     *          final Options options = new Options();
+     *      options.addOption(new Option("d", "debug", false, "Turn on debug."));
+     *      options.addOption(new Option("e", "extract", false, "Turn on extract."));
+     *      options.addOption(new Option("o", "option", true, "Turn on option with argument."));
+     *      }
+     * </pre>
+     * with "partial matching" turned on, <code>-de</code> only matches the
+     * <code>"debug"</code> option. However, with "partial matching" disabled,
+     * <code>-de</code> would enable both <code>debug</code> as well as
+     * <code>extract</code> options.
+     *
      * @param allowPartialMatching if partial matching of long options shall be enabled
      */
     public DefaultParser(final boolean allowPartialMatching) {

src/site/xdoc/usage.xml

@@ -90,6 +90,21 @@ CommandLine cmd = parser.parse( options, args);</source>
 else {
     // print the date
 }</source>
+        <p>
+          <h4>Note.</h4>
+          As of version 1.5-SNAPSHOT (as of 7/31/2017), the
+          <code>DefaultParser</code>'s constructor now has an override with
+          the signature <code>DefaultParser(final boolean allowPartialMatching)</code>.
+          Given the following code:
+          <source>final Options options = new Options();
+options.addOption(new Option("d", "debug", false, "Turn on debug."));
+options.addOption(new Option("e", "extract", false, "Turn on extract."));
+options.addOption(new Option("o", "option", true, "Turn on option with argument."));</source>
+          we define "partial matching" as <code>-de</code> only matching the
+          <code>"debug"</code> option. We can consequently, now, turn this off and have
+          <code>-de</code> match both the <code>debug</code> option as well as the
+          <code>extract</code> option.
+        </p>
       </subsection>
       <subsection name="International Time">
         <p>