Add the default category and tag to all options.

Move the default from the annotation to every mention. This makes the incompleteness explicit. Will add the defaults to test targets in a separate change.

Once all dependencies are cleaned up, the Option annotation will no longer allow options without the documentationCategory or effectTag, to prevent new options being added without categories while we migrate to the new option categorization.

PiperOrigin-RevId: 160281252

src/main/java/com/google/devtools/build/docgen/BUILD

@@ -23,6 +23,7 @@ java_library(
         "//src/main/java/com/google/devtools/build/lib/rules/objc",
         "//src/main/java/com/google/devtools/build/lib/rules/platform",
         "//src/main/java/com/google/devtools/common/options",
+        "//src/main/protobuf:option_filters_java_proto",
         "//third_party:apache_velocity",
         "//third_party:guava",
         "//third_party:jsr305",
@@ -38,6 +39,7 @@ java_binary(
         "//src/main/java/com/google/devtools/build/lib:bazel-rules",
         "//src/main/java/com/google/devtools/build/lib:build-base",
         "//src/main/java/com/google/devtools/common/options",
+        "//src/main/protobuf:option_filters_java_proto",
     ],
 )
 

src/main/java/com/google/devtools/build/docgen/BuildEncyclopediaOptions.java

@@ -14,7 +14,9 @@
 package com.google.devtools.build.docgen;
 
 import com.google.devtools.common.options.Option;
+import com.google.devtools.common.options.OptionDocumentationCategory;
 import com.google.devtools.common.options.OptionsBase;
+import com.google.devtools.common.options.proto.OptionFilters.OptionEffectTag;
 import java.util.List;
 
 /**
@@ -26,6 +28,8 @@ public class BuildEncyclopediaOptions extends OptionsBase {
     abbrev = 'i',
     defaultValue = "",
     allowMultiple = true,
+    documentationCategory = OptionDocumentationCategory.UNCATEGORIZED,
+    effectTags = {OptionEffectTag.UNKNOWN},
     help = "An input directory to read source files"
   )
   public List<String> inputDirs;
@@ -34,6 +38,8 @@ public class BuildEncyclopediaOptions extends OptionsBase {
     name = "provider",
     abbrev = 'p',
     defaultValue = "",
+    documentationCategory = OptionDocumentationCategory.UNCATEGORIZED,
+    effectTags = {OptionEffectTag.UNKNOWN},
     help = "The name of the rule class provider"
   )
   public String provider;
@@ -42,6 +48,8 @@ public class BuildEncyclopediaOptions extends OptionsBase {
     name = "output_dir",
     abbrev = 'o',
     defaultValue = ".",
+    documentationCategory = OptionDocumentationCategory.UNCATEGORIZED,
+    effectTags = {OptionEffectTag.UNKNOWN},
     help = "An output directory."
   )
   public String outputDir;
@@ -50,6 +58,8 @@ public class BuildEncyclopediaOptions extends OptionsBase {
     name = "blacklist",
     abbrev = 'b',
     defaultValue = "",
+    documentationCategory = OptionDocumentationCategory.UNCATEGORIZED,
+    effectTags = {OptionEffectTag.UNKNOWN},
     help = "A path to a file listing rules not to document."
   )
   public String blacklist;
@@ -58,6 +68,8 @@ public class BuildEncyclopediaOptions extends OptionsBase {
     name = "single_page",
     abbrev = '1',
     defaultValue = "false",
+    documentationCategory = OptionDocumentationCategory.UNCATEGORIZED,
+    effectTags = {OptionEffectTag.UNKNOWN},
     help = "Whether to generate the BE as a single HTML page or one page per rule family."
   )
   public boolean singlePage;
@@ -66,6 +78,8 @@ public class BuildEncyclopediaOptions extends OptionsBase {
     name = "help",
     abbrev = 'h',
     defaultValue = "false",
+    documentationCategory = OptionDocumentationCategory.UNCATEGORIZED,
+    effectTags = {OptionEffectTag.UNKNOWN},
     help = "Prints the help string."
   )
   public boolean help;

src/main/java/com/google/devtools/build/lib/BUILD

@@ -371,6 +371,7 @@ java_library(
         "//src/main/java/com/google/devtools/build/lib/buildeventstream/proto:build_event_stream_java_proto",
         "//src/main/java/com/google/devtools/build/lib/buildeventstream/transports",
         "//src/main/java/com/google/devtools/common/options",
+        "//src/main/protobuf:option_filters_java_proto",
         "//third_party:guava",
         "//third_party:joda_time",
         "//third_party:jsr305",
@@ -396,6 +397,7 @@ java_library(
     ],
     deps = [
         "//src/main/java/com/google/devtools/common/options",
+        "//src/main/protobuf:option_filters_java_proto",
     ],
 )
 
@@ -459,6 +461,7 @@ java_library(
         ":vfs",
         "//src/main/java/com/google/devtools/build/lib/cmdline",
         "//src/main/java/com/google/devtools/common/options",
+        "//src/main/protobuf:option_filters_java_proto",
         "//third_party:asm",
         "//third_party:asm-commons",
         "//third_party:asm-util",
@@ -514,6 +517,7 @@ java_library(
         "//src/main/java/com/google/devtools/build/skyframe:skyframe-objects",
         "//src/main/java/com/google/devtools/common/options",
         "//src/main/protobuf:build_java_proto",
+        "//src/main/protobuf:option_filters_java_proto",
         "//third_party:guava",
         "//third_party:jsr305",
         "//third_party/protobuf:protobuf_java",
@@ -713,6 +717,7 @@ java_library(
         "//src/main/java/com/google/devtools/build/skyframe:skyframe-objects",
         "//src/main/java/com/google/devtools/common/options",
         "//src/main/protobuf:crosstool_config_java_proto",
+        "//src/main/protobuf:option_filters_java_proto",
         "//third_party:android_common_25_0_0",
         "//third_party:auto_value",
         "//third_party:guava",
@@ -754,6 +759,7 @@ java_library(
         "//src/main/java/com/google/devtools/build/lib/worker",
         "//src/main/java/com/google/devtools/build/skyframe:skyframe-objects",
         "//src/main/java/com/google/devtools/common/options",
+        "//src/main/protobuf:option_filters_java_proto",
         "//third_party:guava",
         "//third_party:jsr305",
     ],
@@ -774,6 +780,7 @@ java_library(
         "//src/main/java/com/google/devtools/build/lib/query2",
         "//src/main/java/com/google/devtools/build/lib/query2:query-engine",
         "//src/main/java/com/google/devtools/common/options",
+        "//src/main/protobuf:option_filters_java_proto",
         "//third_party:guava",
     ],
 )
@@ -818,6 +825,7 @@ java_library(
         "//src/main/java/com/google/devtools/build/skyframe",
         "//src/main/java/com/google/devtools/build/skyframe:skyframe-objects",
         "//src/main/java/com/google/devtools/common/options",
+        "//src/main/protobuf:option_filters_java_proto",
         "//third_party:aether",
         "//third_party:apache_commons_compress",
         "//third_party:auto_value",
@@ -876,6 +884,7 @@ java_library(
         ":vfs",
         "//src/main/java/com/google/devtools/build/lib/actions",
         "//src/main/java/com/google/devtools/common/options",
+        "//src/main/protobuf:option_filters_java_proto",
         "//third_party:auto_value",
         "//third_party:guava",
         "//third_party:jsr305",
@@ -1027,6 +1036,7 @@ java_library(
         "//src/main/java/com/google/devtools/build/lib/rules/cpp",
         "//src/main/java/com/google/devtools/common/options",
         "//src/main/protobuf:extra_actions_base_java_proto",
+        "//src/main/protobuf:option_filters_java_proto",
         "//third_party:auto_value",
         "//third_party:guava",
         "//third_party:joda_time",
@@ -1067,6 +1077,7 @@ java_library(
         "//src/main/java/com/google/devtools/common/options",
         "//src/main/protobuf:android_deploy_info_java_proto",
         "//src/main/protobuf:apk_manifest_java_proto",
+        "//src/main/protobuf:option_filters_java_proto",
         "//third_party:android_common_25_0_0",
         "//third_party:auto_value",
         "//third_party:guava",
@@ -1093,6 +1104,7 @@ java_library(
         "//src/main/java/com/google/devtools/common/options",
         "//src/main/protobuf:crosstool_config_java_proto",
         "//src/main/protobuf:extra_actions_base_java_proto",
+        "//src/main/protobuf:option_filters_java_proto",
         "//third_party:guava",
         "//third_party:jsr305",
         "//third_party/protobuf:protobuf_java",

src/main/java/com/google/devtools/build/lib/analysis/BuildView.java

@@ -95,9 +95,11 @@
 import com.google.devtools.build.skyframe.WalkableGraph;
 import com.google.devtools.common.options.Converter;
 import com.google.devtools.common.options.Option;
+import com.google.devtools.common.options.OptionDocumentationCategory;
 import com.google.devtools.common.options.OptionsBase;
 import com.google.devtools.common.options.OptionsParser.OptionUsageRestrictions;
 import com.google.devtools.common.options.OptionsParsingException;
+import com.google.devtools.common.options.proto.OptionFilters.OptionEffectTag;
 import java.util.ArrayList;
 import java.util.Collection;
 import java.util.HashMap;
@@ -168,6 +170,8 @@ public static class Options extends OptionsBase {
       defaultValue = "-1",
       category = "what",
       converter = LoadingPhaseThreadCountConverter.class,
+      documentationCategory = OptionDocumentationCategory.UNCATEGORIZED,
+      effectTags = {OptionEffectTag.UNKNOWN},
       help = "Number of parallel threads to use for the loading/analysis phase."
     )
     public int loadingPhaseThreads;
@@ -177,6 +181,8 @@ public static class Options extends OptionsBase {
       abbrev = 'k',
       defaultValue = "false",
       category = "strategy",
+      documentationCategory = OptionDocumentationCategory.UNCATEGORIZED,
+      effectTags = {OptionEffectTag.UNKNOWN},
       help =
           "Continue as much as possible after an error.  While the target that failed, and those "
               + "that depend on it, cannot be analyzed (or built), the other prerequisites of "
@@ -191,6 +197,8 @@ public static class Options extends OptionsBase {
               + " an upcoming Blaze release",
       defaultValue = "false",
       category = "strategy",
+      documentationCategory = OptionDocumentationCategory.UNCATEGORIZED,
+      effectTags = {OptionEffectTag.UNKNOWN},
       help = "Treat visible analysis warnings as errors."
     )
     public boolean analysisWarningsAsErrors;
@@ -199,6 +207,8 @@ public static class Options extends OptionsBase {
       name = "discard_analysis_cache",
       defaultValue = "false",
       category = "strategy",
+      documentationCategory = OptionDocumentationCategory.UNCATEGORIZED,
+      effectTags = {OptionEffectTag.UNKNOWN},
       help =
           "Discard the analysis cache immediately after the analysis phase completes."
               + " Reduces memory usage by ~10%, but makes further incremental builds slower."
@@ -210,6 +220,8 @@ public static class Options extends OptionsBase {
       defaultValue = "",
       category = "experimental",
       converter = RegexFilter.RegexFilterConverter.class,
+      documentationCategory = OptionDocumentationCategory.UNCATEGORIZED,
+      effectTags = {OptionEffectTag.UNKNOWN},
       help = "Filters set of targets to schedule extra_actions for."
     )
     public RegexFilter extraActionFilter;
@@ -218,6 +230,8 @@ public static class Options extends OptionsBase {
       name = "experimental_extra_action_top_level_only",
       defaultValue = "false",
       category = "experimental",
+      documentationCategory = OptionDocumentationCategory.UNCATEGORIZED,
+      effectTags = {OptionEffectTag.UNKNOWN},
       help = "Only schedules extra_actions for top level targets."
     )
     public boolean extraActionTopLevelOnly;
@@ -226,6 +240,8 @@ public static class Options extends OptionsBase {
       name = "version_window_for_dirty_node_gc",
       defaultValue = "0",
       optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED,
+      documentationCategory = OptionDocumentationCategory.UNCATEGORIZED,
+      effectTags = {OptionEffectTag.UNKNOWN},
       help =
           "Nodes that have been dirty for more than this many versions will be deleted"
               + " from the graph upon the next update. Values must be non-negative long integers,"
@@ -238,6 +254,8 @@ public static class Options extends OptionsBase {
       name = "experimental_interleave_loading_and_analysis",
       defaultValue = "true",
       category = "experimental",
+      documentationCategory = OptionDocumentationCategory.UNCATEGORIZED,
+      effectTags = {OptionEffectTag.UNKNOWN},
       help = "No-op."
     )
     public boolean interleaveLoadingAndAnalysis;

src/main/java/com/google/devtools/build/lib/analysis/PlatformOptions.java

@@ -19,7 +19,9 @@
 import com.google.devtools.build.lib.analysis.config.FragmentOptions;
 import com.google.devtools.build.lib.cmdline.Label;
 import com.google.devtools.common.options.Option;
+import com.google.devtools.common.options.OptionDocumentationCategory;
 import com.google.devtools.common.options.OptionsParser;
+import com.google.devtools.common.options.proto.OptionFilters.OptionEffectTag;
 import java.util.List;
 
 /** Command-line options for platform-related configuration. */
@@ -29,6 +31,8 @@ public class PlatformOptions extends FragmentOptions {
     name = "experimental_host_platform",
     converter = BuildConfiguration.LabelConverter.class,
     defaultValue = "@bazel_tools//platforms:host_platform",
+    documentationCategory = OptionDocumentationCategory.UNCATEGORIZED,
+    effectTags = {OptionEffectTag.UNKNOWN},
     optionUsageRestrictions = OptionsParser.OptionUsageRestrictions.HIDDEN,
     help = "Declare the platform the build is started from"
   )
@@ -40,6 +44,8 @@ public class PlatformOptions extends FragmentOptions {
     name = "experimental_platforms",
     converter = BuildConfiguration.LabelListConverter.class,
     defaultValue = "@bazel_tools//platforms:target_platform",
+    documentationCategory = OptionDocumentationCategory.UNCATEGORIZED,
+    effectTags = {OptionEffectTag.UNKNOWN},
     optionUsageRestrictions = OptionsParser.OptionUsageRestrictions.HIDDEN,
     help = "Declare the platforms targeted by the current build"
   )

src/main/java/com/google/devtools/build/lib/analysis/WorkspaceStatusAction.java

@@ -28,8 +28,10 @@
 import com.google.devtools.build.lib.vfs.Path;
 import com.google.devtools.build.lib.vfs.PathFragment;
 import com.google.devtools.common.options.Option;
+import com.google.devtools.common.options.OptionDocumentationCategory;
 import com.google.devtools.common.options.OptionsBase;
 import com.google.devtools.common.options.OptionsParser.OptionUsageRestrictions;
+import com.google.devtools.common.options.proto.OptionFilters.OptionEffectTag;
 import java.io.IOException;
 import java.util.HashMap;
 import java.util.List;
@@ -61,6 +63,8 @@ public static class Options extends OptionsBase {
       defaultValue = "",
       category = "misc",
       valueHelp = "<string>",
+      documentationCategory = OptionDocumentationCategory.UNCATEGORIZED,
+      effectTags = {OptionEffectTag.UNKNOWN},
       help = "Embed source control revision or release label in binary"
     )
     public String embedLabel;
@@ -69,6 +73,8 @@ public static class Options extends OptionsBase {
       name = "experimental_embed_timestamp_epoch",
       defaultValue = "-1",
       optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED,
+      documentationCategory = OptionDocumentationCategory.UNCATEGORIZED,
+      effectTags = {OptionEffectTag.UNKNOWN},
       help = "Alternative timestamp to be used in stamping the binary"
     )
     public long embedTimestampEpoch;
@@ -79,6 +85,8 @@ public static class Options extends OptionsBase {
       category = "misc",
       converter = OptionsUtils.PathFragmentConverter.class,
       valueHelp = "<path>",
+      documentationCategory = OptionDocumentationCategory.UNCATEGORIZED,
+      effectTags = {OptionEffectTag.UNKNOWN},
       help =
           "A command invoked at the beginning of the build to provide status "
               + "information about the workspace in the form of key/value pairs.  "