Documentation: Update boolean arity remkop#1400

The default arity for boolean options is 0..1 and no longer 0.
MarkoMackic · Oct 17, 2021 · c0039ae · c0039ae
1 parent e96b63c
commit c0039ae
Show file tree

Hide file tree

Showing 2 changed files with 13 additions and 9 deletions.
diff --git a/docs/index.adoc b/docs/index.adoc
@@ -2347,7 +2347,7 @@ If no `arity` is specified, the number of parameters depends on the field's type
 [grid=cols,cols="30,5,65",options="header"]
 |===
 | @Option Field Type | Default Arity | Notes
-| boolean      | 0 |Boolean options by default don't require an option parameter. The field is set to the opposite of its default value when the option name is recognized. (This can be <<Toggle Boolean Flags,configured>>.)
+| boolean      | 0..1 | Boolean options by default don't require an option parameter. The field is set to the opposite of its default value when the option name is recognized. (This can be <<Toggle Boolean Flags,configured>>.)
 | Single-valued type (e.g., `int`, `String`, `File`) | 1 | The option name must be followed by a value.
 | Multi-valued type (arrays, collections or maps) | 1 | The option name must be followed by a value.
 |===

diff --git a/src/main/java/picocli/CommandLine.java b/src/main/java/picocli/CommandLine.java
@@ -3734,7 +3734,7 @@ public enum ScopeType {
          * command line, a {@link MissingParameterException} is thrown by the {@link #parse(String...)} method.
          * <p>
          * In many cases picocli can deduce the number of required parameters from the field's type.
-         * By default, flags (boolean options) have arity zero,
+         * By default, flags (boolean options) have arity "0..1",
          * and single-valued type fields (String, int, Integer, double, Double, File, Date, etc) have arity one.
          * Generally, fields with types that cannot hold multiple values can omit the {@code arity} attribute.
          * </p><p>
@@ -3746,7 +3746,7 @@ public enum ScopeType {
          * </p>
          * <b>A note on boolean options</b>
          * <p>
-         * By default picocli does not expect boolean options (also called "flags" or "switches") to have a parameter.
+         * By default picocli allows boolean options (also called "flags" or "switches") to have an optional parameter.
          * You can make a boolean option take a required parameter by annotating your field with {@code arity="1"}.
          * For example: </p>
          * <pre>&#064;Option(names = "-v", arity = "1") boolean verbose;</pre>
@@ -3756,12 +3756,11 @@ public enum ScopeType {
          * on the command line, or a {@link MissingParameterException} is thrown by the {@link #parse(String...)}
          * method.
          * </p><p>
-         * To make the boolean parameter possible but optional, define the field with {@code arity = "0..1"}.
+         * To remove the optional parameter, define the field with {@code arity = "0"}.
          * For example: </p>
-         * <pre>&#064;Option(names="-v", arity="0..1") boolean verbose;</pre>
-         * <p>This will accept any of the below without throwing an exception:</p>
+         * <pre>&#064;Option(names="-v", arity="0") boolean verbose;</pre>
+         * <p>This will reject any of the below:</p>
          * <pre>
-         * -v
          * -v true
          * -v false
          * </pre>
@@ -5603,9 +5602,14 @@ static Range adjustForType(Range result, IAnnotatedElement member) {
             return result.isUnspecified ? defaultArity(member) : result;
         }
         /** Returns the default arity {@code Range}: for interactive options/positional parameters,
-         * this is 0; for {@link Option options} this is 0 for booleans and 1 for
-         * other types, for {@link Parameters parameters} booleans have arity 0, arrays or Collections have
+         * this is 0; for {@link Option options} this is effectively "0..1" for booleans and 1 for
+         * other types, for {@link Parameters parameters} booleans have arity 1, arrays or Collections have
          * arity "0..*", and other types have arity 1.
+         * <p><b><em>Implementation Notes</em></b></p>
+         * <p>The returned {@code Range} for boolean options has an <em>effective</em> arity of "0..1".
+         * This is implemented by returning a {@code Range} with arity "0",
+         * and its {@code unspecified} property set to {@code true}.
+         * This implementation may change in the future.</p>
          * @param field the field whose default arity to return
          * @return a new {@code Range} indicating the default arity of the specified field
          * @since 2.0 */