diff --git a/src/main/java/picocli/CommandLine.java b/src/main/java/picocli/CommandLine.java
index dce5d9f85..9c4a100e5 100644
--- a/src/main/java/picocli/CommandLine.java
+++ b/src/main/java/picocli/CommandLine.java
@@ -3746,7 +3746,8 @@ public enum ScopeType {
          * </p>
          * <b>A note on boolean options</b>
          * <p>
-         * By default picocli allows boolean options (also called "flags" or "switches") to have an optional parameter.
+         * By default picocli allows boolean options (also called "flags" or "switches") to have an optional parameter,
+         * which must be either "true" or "false" (lowercase, other values are rejected).
          * 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>