1 files changed, 10 insertions, 5 deletions
diff --git a/src/main/java/com/google/devtools/common/options/BoolOrEnumConverter.java b/src/main/java/com/google/devtools/common/options/BoolOrEnumConverter.java
index 3e16f89a51..17bf7a9a48 100644
--- a/src/main/java/com/google/devtools/common/options/BoolOrEnumConverter.java
+++ b/src/main/java/com/google/devtools/common/options/BoolOrEnumConverter.java
@@ -17,13 +17,16 @@ package com.google.devtools.common.options;
 import com.google.devtools.common.options.Converters.BooleanConverter;
 
 /**
- * Converter that can also convert from booleans and enumerations.
+ * Converter that can convert both the standard set of boolean string values and enumerations. If
+ * there is an overlap in values, those from the underlying enumeration will be taken.
  *
- * <p> This is able to additionally convert from the standard set of
- * boolean string values. If there is an overlap in values, those from
- * the underlying enumeration will be taken.
+ * <p>Note that for the flag to take one of its enum values on the command line, it must be of the
+ * form "--flag=value". That is, "--flag value" and "-f value" (if the flag has a short-form of "f")
+ * will result in "value" being left as residue on the command line. This maintains compatibility
+ * with boolean flags where "--flag true" and "-f true" also leave "true" as residue on the command
+ * line.
  */
-public abstract class BoolOrEnumConverter<T extends Enum<T>> extends EnumConverter<T>{
+public abstract class BoolOrEnumConverter<T extends Enum<T>> extends EnumConverter<T> {
   private T falseValue;
   private T trueValue;
 
@@ -55,6 +58,8 @@ public abstract class BoolOrEnumConverter<T extends Enum<T>> extends EnumConvert
         boolean value = booleanConverter.convert(input);
         return value ? trueValue : falseValue;
       } catch (OptionsParsingException eBoolean) {
+        // TODO(b/111883901): Rethrowing the exception from the enum converter does not report the
+        // allowable boolean values.
         throw eEnum;
       }
     }