commit 6f09666d994b3bd7663eb3f95e2aeaf63c85b0d7
author Ulf Adams <ulfjack@google.com> Mon Jun 27 15:51:23 2016 +0000
committer Dmitry Lomov <dslomov@google.com> Mon Jun 27 17:07:06 2016 +0000
tree 18de52fd63aa95f497579ff926513106d9c956df
parent d19116235914e058ace1023103c7c92252207694

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

src/main/java/com/google/devtools/common/options/OptionsUsage.java

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("=&lt;").append(escaper.escape(typeDescription)).append("&gt");
+    }
+    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");