Add new option categorization and tagging information to HelpCommand's output.

If setting flag --use_new_category_enum, group the options by the new categories in both the command line output and the "everything-as-html" output used for the generated docs at https://bazel.build/versions/master/docs/command-line-reference.html. In the html output, the effect and metadata tags are listed for each option, with links to their descriptions at the bottom of the page. The tags only appear in the terminal output in -l/--long/--help_verbosity=long, and only the names appear.

This is still experimental as the majority of options do not yet use the new categorization system. The new output can be seen in command-line-reference.html format by adding the new flag to the "help everything-as-html" line in //src/main/java/com/google/devtools/build/lib:gen_command-line-reference.

The html output is in the same order as before (by blaze rule, with inherited options not repeated), which means it still has duplicate options, that should ideally be fixed separately. I propose either dropping the high-level grouping and just grouping the options by documentation category, or potentially grouping them by optionsbase in some non-class-naming way, and listing the commands that they apply to, as more and more optionsbases are used by multiple commands without being inherited (for example, all BuildEventServiceOptions are listed 20 times). People probably use ctrl-f to navigate this page anyway. Once we know that we only list each option once, we can actually have links to the options, which will make it possible to have links in the expansion lists.

Issue #3758

RELNOTES: added experimental --use_new_category_enum to the help command to output options grouped by the new type of category.
PiperOrigin-RevId: 170116553

1 files changed, 73 insertions, 0 deletions

diff --git a/src/test/java/com/google/devtools/common/options/OptionFilterDescriptionsTest.java b/src/test/java/com/google/devtools/common/options/OptionFilterDescriptionsTest.java
new file mode 100644
index 0000000000..a8d2814a5b
--- /dev/null
+++ b/src/test/java/com/google/devtools/common/options/OptionFilterDescriptionsTest.java
@@ -0,0 +1,73 @@
+// Copyright 2017 The Bazel Authors. All rights reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//    http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+package com.google.devtools.common.options;
+
+import static com.google.common.truth.Truth.assertThat;
+
+import com.google.common.collect.ImmutableMap;
+import java.util.ArrayList;
+import java.util.Collections;
+import org.junit.Test;
+import org.junit.runner.RunWith;
+import org.junit.runners.JUnit4;
+
+/** Tests that we have descriptions for every option tag. */
+@RunWith(JUnit4.class)
+public class OptionFilterDescriptionsTest {
+
+  @Test
+  public void documentationOrderIncludesAllDocumentedCategories() {
+    // Expect the documentation order to include everything but the undocumented category.
+    ArrayList<OptionDocumentationCategory> docOrderPlusUndocumented = new ArrayList<>();
+    Collections.addAll(docOrderPlusUndocumented, OptionFilterDescriptions.documentationOrder);
+    docOrderPlusUndocumented.add(OptionDocumentationCategory.UNDOCUMENTED);
+
+    assertThat(OptionDocumentationCategory.values())
+        .asList()
+        .containsExactlyElementsIn(docOrderPlusUndocumented);
+  }
+
+  @Test
+  public void optionDocumentationCategoryDescriptionsContainsAllCategories() {
+    // Check that we have a description for all valid option categories.
+    ImmutableMap<OptionDocumentationCategory, String> optionCategoryDescriptions =
+        OptionFilterDescriptions.getOptionCategoriesEnumDescription("blaze");
+
+    assertThat(OptionDocumentationCategory.values())
+        .asList()
+        .containsExactlyElementsIn(optionCategoryDescriptions.keySet());
+  }
+
+  @Test
+  public void optionEffectTagDescriptionsContainsAllTags() {
+    // Check that we have a description for all valid option tags.
+    ImmutableMap<OptionEffectTag, String> optionEffectTagDescription =
+        OptionFilterDescriptions.getOptionEffectTagDescription("blaze");
+
+    assertThat(OptionEffectTag.values())
+        .asList()
+        .containsExactlyElementsIn(optionEffectTagDescription.keySet());
+  }
+
+  @Test
+  public void optionMetadataTagDescriptionsContainsAllTags() {
+    // Check that we have a description for all valid option tags.
+    ImmutableMap<OptionMetadataTag, String> optionMetadataTagDescription =
+        OptionFilterDescriptions.getOptionMetadataTagDescription("blaze");
+
+    assertThat(OptionMetadataTag.values())
+        .asList()
+        .containsExactlyElementsIn(optionMetadataTagDescription.keySet());
+  }
+}