Polish the command-line reference.
- change options to print --foo=value
- allow option to specify what "value" should be
- update the documentation for the startup options
- add some indentation to the descriptions
- add some spacing between flag texts
--
MOS_MIGRATED_REVID=125960618
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 82b8cdc..3e16f89 100644
--- a/src/main/java/com/google/devtools/common/options/BoolOrEnumConverter.java
+++ b/src/main/java/com/google/devtools/common/options/BoolOrEnumConverter.java
@@ -24,7 +24,6 @@
* the underlying enumeration will be taken.
*/
public abstract class BoolOrEnumConverter<T extends Enum<T>> extends EnumConverter<T>{
-
private T falseValue;
private T trueValue;
@@ -46,6 +45,7 @@
this.falseValue = falseValue;
}
+ @Override
public T convert(String input) throws OptionsParsingException {
try {
return super.convert(input);
diff --git a/src/main/java/com/google/devtools/common/options/Option.java b/src/main/java/com/google/devtools/common/options/Option.java
index e269d33..3b2ca30 100644
--- a/src/main/java/com/google/devtools/common/options/Option.java
+++ b/src/main/java/com/google/devtools/common/options/Option.java
@@ -25,7 +25,6 @@
@Target(ElementType.FIELD)
@Retention(RetentionPolicy.RUNTIME)
public @interface Option {
-
/**
* The name of the option ("--name").
*/
@@ -42,6 +41,12 @@
String help() default "";
/**
+ * A short text string to describe the type of the expected value. E.g., <code>regex</code>. This
+ * is ignored for boolean, tristate, boolean_or_enum, and void options.
+ */
+ String valueHelp() default "";
+
+ /**
* The default value for the option. This method should only be invoked
* directly by the parser implementation. Any access to default values
* should go via the parser to allow for application specific defaults.
diff --git a/src/main/java/com/google/devtools/common/options/OptionsParserImpl.java b/src/main/java/com/google/devtools/common/options/OptionsParserImpl.java
index 6d91dec..3422f78 100644
--- a/src/main/java/com/google/devtools/common/options/OptionsParserImpl.java
+++ b/src/main/java/com/google/devtools/common/options/OptionsParserImpl.java
@@ -815,6 +815,10 @@
|| findConverter(field) instanceof BoolOrEnumConverter;
}
+ static boolean isVoidField(Field field) {
+ return field.getType().equals(Void.class);
+ }
+
static boolean isSpecialNullDefault(String defaultValueString, Field optionField) {
return defaultValueString.equals("null") && !optionField.getType().isPrimitive();
}
diff --git a/src/main/java/com/google/devtools/common/options/OptionsUsage.java b/src/main/java/com/google/devtools/common/options/OptionsUsage.java
index 111a772..b8c19df 100644
--- a/src/main/java/com/google/devtools/common/options/OptionsUsage.java
+++ b/src/main/java/com/google/devtools/common/options/OptionsUsage.java
@@ -133,28 +133,37 @@
static void getUsageHtml(Field optionField, StringBuilder usage, Escaper escaper) {
String plainFlagName = optionField.getAnnotation(Option.class).name();
String flagName = getFlagName(optionField);
+ String valueDescription = optionField.getAnnotation(Option.class).valueHelp();
String typeDescription = getTypeDescription(optionField);
Option annotation = optionField.getAnnotation(Option.class);
usage.append("<dt><code><a name=\"flag--").append(plainFlagName).append("\"></a>--");
- usage.append(flagName).append("</code>");
+ usage.append(flagName);
+ if (OptionsParserImpl.isBooleanField(optionField)
+ || OptionsParserImpl.isVoidField(optionField)) {
+ // Nothing for boolean, tristate, boolean_or_enum, or void options.
+ } else if (!valueDescription.isEmpty()) {
+ usage.append("=").append(escaper.escape(valueDescription));
+ } else if (!typeDescription.isEmpty()) {
+ // Generic fallback, which isn't very good.
+ usage.append("=<").append(escaper.escape(typeDescription)).append(">");
+ }
+ usage.append("</code>");
if (annotation.abbrev() != '\0') {
usage.append(" [<code>-").append(annotation.abbrev()).append("</code>]");
}
- if (!typeDescription.isEmpty()) {
- usage.append(" (").append(escaper.escape(typeDescription)).append("; ");
- if (annotation.allowMultiple()) {
- // Allow-multiple options can't have a default value.
- usage.append("may be used multiple times");
+ if (annotation.allowMultiple()) {
+ // Allow-multiple options can't have a default value.
+ usage.append(" multiple uses are accumulated");
+ } else {
+ // Don't call the annotation directly (we must allow overrides to certain defaults).
+ String defaultValueString = OptionsParserImpl.getDefaultOptionString(optionField);
+ if (OptionsParserImpl.isVoidField(optionField)) {
+ // Void options don't have a default.
+ } else if (OptionsParserImpl.isSpecialNullDefault(defaultValueString, optionField)) {
+ usage.append(" default: see description");
} else {
- // Don't call the annotation directly (we must allow overrides to certain defaults).
- String defaultValueString = OptionsParserImpl.getDefaultOptionString(optionField);
- if (OptionsParserImpl.isSpecialNullDefault(defaultValueString, optionField)) {
- usage.append("default: see description");
- } else {
- usage.append("default: \"").append(escaper.escape(defaultValueString)).append("\"");
- }
+ usage.append(" default: \"").append(escaper.escape(defaultValueString)).append("\"");
}
- usage.append(")");
}
usage.append("</dt>\n");
usage.append("<dd>\n");
