Split out option usage restriction from option category.

These are two different concepts. Do not remove category overload compatibility in this CL, to keep this change limited to converting the current uses of category.

With some flyby formatting fixes on affected OptionsBases.

RELNOTES: None.
PiperOrigin-RevId: 153390002

23 files changed, 2222 insertions, 1635 deletions

diff --git a/src/main/java/com/google/devtools/build/lib/analysis/BuildView.java b/src/main/java/com/google/devtools/build/lib/analysis/BuildView.java
index 036e7473b1..5d56cf31d4 100644
--- a/src/main/java/com/google/devtools/build/lib/analysis/BuildView.java
+++ b/src/main/java/com/google/devtools/build/lib/analysis/BuildView.java
@@ -95,6 +95,7 @@ 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.OptionsBase;
+import com.google.devtools.common.options.OptionsParser.OptionUsageRestrictions;
 import com.google.devtools.common.options.OptionsParsingException;
 import java.util.ArrayList;
 import java.util.Collection;
@@ -156,9 +157,9 @@ import javax.annotation.Nullable;
 public class BuildView {
 
   /**
-   * Options that affect the <i>mechanism</i> of analysis.  These are distinct from {@link
-   * com.google.devtools.build.lib.analysis.config.BuildOptions}, which affect the <i>value</i>
-   * of a BuildConfiguration.
+   * Options that affect the <i>mechanism</i> of analysis. These are distinct from {@link
+   * com.google.devtools.build.lib.analysis.config.BuildOptions}, which affect the <i>value</i> of a
+   * BuildConfiguration.
    */
   public static class Options extends OptionsBase {
     @Option(
@@ -170,42 +171,54 @@ public class BuildView {
     )
     public int loadingPhaseThreads;
 
-    @Option(name = "keep_going",
-            abbrev = 'k',
-            defaultValue = "false",
-            category = "strategy",
-            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 these"
-                + " targets can be analyzed (or built) all the same.")
+    @Option(
+      name = "keep_going",
+      abbrev = 'k',
+      defaultValue = "false",
+      category = "strategy",
+      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 "
+              + "these targets can be analyzed (or built) all the same."
+    )
     public boolean keepGoing;
 
-    @Option(name = "analysis_warnings_as_errors",
-            deprecationWarning = "analysis_warnings_as_errors is now a no-op and will be removed in"
-                              + " an upcoming Blaze release",
-            defaultValue = "false",
-            category = "strategy",
-            help = "Treat visible analysis warnings as errors.")
+    @Option(
+      name = "analysis_warnings_as_errors",
+      deprecationWarning =
+          "analysis_warnings_as_errors is now a no-op and will be removed in"
+              + " an upcoming Blaze release",
+      defaultValue = "false",
+      category = "strategy",
+      help = "Treat visible analysis warnings as errors."
+    )
     public boolean analysisWarningsAsErrors;
 
-    @Option(name = "discard_analysis_cache",
-            defaultValue = "false",
-            category = "strategy",
-            help = "Discard the analysis cache immediately after the analysis phase completes."
-                + " Reduces memory usage by ~10%, but makes further incremental builds slower.")
+    @Option(
+      name = "discard_analysis_cache",
+      defaultValue = "false",
+      category = "strategy",
+      help =
+          "Discard the analysis cache immediately after the analysis phase completes."
+              + " Reduces memory usage by ~10%, but makes further incremental builds slower."
+    )
     public boolean discardAnalysisCache;
 
-    @Option(name = "experimental_extra_action_filter",
-            defaultValue = "",
-            category = "experimental",
-            converter = RegexFilter.RegexFilterConverter.class,
-            help = "Filters set of targets to schedule extra_actions for.")
+    @Option(
+      name = "experimental_extra_action_filter",
+      defaultValue = "",
+      category = "experimental",
+      converter = RegexFilter.RegexFilterConverter.class,
+      help = "Filters set of targets to schedule extra_actions for."
+    )
     public RegexFilter extraActionFilter;
 
-    @Option(name = "experimental_extra_action_top_level_only",
-            defaultValue = "false",
-            category = "experimental",
-            help = "Only schedules extra_actions for top level targets.")
+    @Option(
+      name = "experimental_extra_action_top_level_only",
+      defaultValue = "false",
+      category = "experimental",
+      help = "Only schedules extra_actions for top level targets."
+    )
     public boolean extraActionTopLevelOnly;
 
     @Option(
@@ -220,12 +233,15 @@ public class BuildView {
     )
     public boolean extraActionTopLevelOnlyWithAspects;
 
-    @Option(name = "version_window_for_dirty_node_gc",
-            defaultValue = "0",
-            category = "undocumented",
-            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,"
-                + " or -1 indicating the maximum possible window.")
+    @Option(
+      name = "version_window_for_dirty_node_gc",
+      defaultValue = "0",
+      optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED,
+      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,"
+              + " or -1 indicating the maximum possible window."
+    )
     public long versionWindowForDirtyNodeGc;
 
     @Deprecated
diff --git a/src/main/java/com/google/devtools/build/lib/analysis/WorkspaceStatusAction.java b/src/main/java/com/google/devtools/build/lib/analysis/WorkspaceStatusAction.java
index 21d3d38730..b02bf3b4af 100644
--- a/src/main/java/com/google/devtools/build/lib/analysis/WorkspaceStatusAction.java
+++ b/src/main/java/com/google/devtools/build/lib/analysis/WorkspaceStatusAction.java
@@ -29,6 +29,7 @@ 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.OptionsBase;
+import com.google.devtools.common.options.OptionsParser.OptionUsageRestrictions;
 import java.io.IOException;
 import java.util.HashMap;
 import java.util.List;
@@ -55,29 +56,34 @@ public abstract class WorkspaceStatusAction extends AbstractAction {
    * Options controlling the workspace status command.
    */
   public static class Options extends OptionsBase {
-    @Option(name = "embed_label",
-        defaultValue = "",
-        category = "misc",
-        valueHelp = "<string>",
-        help = "Embed source control revision or release label in binary")
+    @Option(
+      name = "embed_label",
+      defaultValue = "",
+      category = "misc",
+      valueHelp = "<string>",
+      help = "Embed source control revision or release label in binary"
+    )
     public String embedLabel;
 
     @Option(
       name = "experimental_embed_timestamp_epoch",
       defaultValue = "-1",
-      category = "undocumented",
+      optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED,
       help = "Alternative timestamp to be used in stamping the binary"
     )
     public long embedTimestampEpoch;
 
-    @Option(name = "workspace_status_command",
-        defaultValue = "",
-        category = "misc",
-        converter = OptionsUtils.PathFragmentConverter.class,
-        valueHelp = "<path>",
-        help = "A command invoked at the beginning of the build to provide status "
-            + "information about the workspace in the form of key/value pairs.  "
-            + "See the User's Manual for the full specification.")
+    @Option(
+      name = "workspace_status_command",
+      defaultValue = "",
+      category = "misc",
+      converter = OptionsUtils.PathFragmentConverter.class,
+      valueHelp = "<path>",
+      help =
+          "A command invoked at the beginning of the build to provide status "
+              + "information about the workspace in the form of key/value pairs.  "
+              + "See the User's Manual for the full specification."
+    )
     public PathFragment workspaceStatusCommand;
   }
 
diff --git a/src/main/java/com/google/devtools/build/lib/analysis/config/BuildConfiguration.java b/src/main/java/com/google/devtools/build/lib/analysis/config/BuildConfiguration.java
index c38cfc2e5e..8c733c5db1 100644
--- a/src/main/java/com/google/devtools/build/lib/analysis/config/BuildConfiguration.java
+++ b/src/main/java/com/google/devtools/build/lib/analysis/config/BuildConfiguration.java
@@ -75,6 +75,7 @@ import com.google.devtools.common.options.Converter;
 import com.google.devtools.common.options.Converters;
 import com.google.devtools.common.options.EnumConverter;
 import com.google.devtools.common.options.Option;
+import com.google.devtools.common.options.OptionsParser.OptionUsageRestrictions;
 import com.google.devtools.common.options.OptionsParsingException;
 import com.google.devtools.common.options.TriState;
 import java.util.ArrayList;
@@ -479,123 +480,153 @@ public final class BuildConfiguration {
    */
   public static class Options extends FragmentOptions implements Cloneable {
     @Option(
-        name = "define",
-        converter = Converters.AssignmentConverter.class,
-        defaultValue = "",
-        category = "semantics",
-        allowMultiple = true,
-        help = "Each --define option specifies an assignment for a build variable."
+      name = "define",
+      converter = Converters.AssignmentConverter.class,
+      defaultValue = "",
+      category = "semantics",
+      allowMultiple = true,
+      help = "Each --define option specifies an assignment for a build variable."
     )
     public List<Map.Entry<String, String>> commandLineBuildVariables;
 
-    @Option(name = "cpu",
-        defaultValue = "",
-        category = "semantics",
-        converter = AutoCpuConverter.class,
-        help = "The target CPU.")
+    @Option(
+      name = "cpu",
+      defaultValue = "",
+      category = "semantics",
+      converter = AutoCpuConverter.class,
+      help = "The target CPU."
+    )
     public String cpu;
 
     /**
      * Allows a configuration to record if --experimental_multi_cpu was used to set a cpu value.
-     * This is necessary to ensure that a configuration transition that sets cpu does not erase
-     * the difference between a pair of configurations created by --experimental_multi_cpu, leading
-     * to a crash when the configurations are treated as the same.
+     * This is necessary to ensure that a configuration transition that sets cpu does not erase the
+     * difference between a pair of configurations created by --experimental_multi_cpu, leading to a
+     * crash when the configurations are treated as the same.
      *
      * <p>TODO(b/33780512): Remove once dynamic configurations are used.
      */
-    @Option(name = "experimental multi cpu distinguisher",
-        defaultValue = "",
-        category = "internal")
+    @Option(
+      name = "experimental multi cpu distinguisher",
+      defaultValue = "",
+      optionUsageRestrictions = OptionUsageRestrictions.INTERNAL
+    )
     public String experimentalMultiCpuDistinguisher;
 
-    @Option(name = "min_param_file_size",
-        defaultValue = "32768",
-        category = "undocumented",
-        help = "Minimum command line length before creating a parameter file.")
+    @Option(
+      name = "min_param_file_size",
+      defaultValue = "32768",
+      optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED,
+      help = "Minimum command line length before creating a parameter file."
+    )
     public int minParamFileSize;
 
-    @Option(name = "experimental_extended_sanity_checks",
-        defaultValue = "false",
-        category = "undocumented",
-        help  = "Enables internal validation checks to make sure that configured target "
-            + "implementations only access things they should. Causes a performance hit.")
+    @Option(
+      name = "experimental_extended_sanity_checks",
+      defaultValue = "false",
+      optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED,
+      help =
+          "Enables internal validation checks to make sure that configured target "
+              + "implementations only access things they should. Causes a performance hit."
+    )
     public boolean extendedSanityChecks;
 
-    @Option(name = "experimental_allow_runtime_deps_on_neverlink",
-        defaultValue = "true",
-        category = "undocumented",
-        help = "Flag to help transition from allowing to disallowing runtime_deps on neverlink"
-            + " Java archives. The depot needs to be cleaned up to roll this out by default.")
+    @Option(
+      name = "experimental_allow_runtime_deps_on_neverlink",
+      defaultValue = "true",
+      optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED,
+      help =
+          "Flag to help transition from allowing to disallowing runtime_deps on neverlink"
+              + " Java archives. The depot needs to be cleaned up to roll this out by default."
+    )
     public boolean allowRuntimeDepsOnNeverLink;
 
-    @Option(name = "strict_filesets",
-        defaultValue = "false",
-        category = "semantics",
-        help = "If this option is enabled, filesets crossing package boundaries are reported "
-            + "as errors. It does not work when check_fileset_dependencies_recursively is "
-            + "disabled.")
+    @Option(
+      name = "strict_filesets",
+      defaultValue = "false",
+      category = "semantics",
+      help =
+          "If this option is enabled, filesets crossing package boundaries are reported "
+              + "as errors. It does not work when check_fileset_dependencies_recursively is "
+              + "disabled."
+    )
     public boolean strictFilesets;
 
     // Plugins are build using the host config. To avoid cycles we just don't propagate
     // this option to the host config. If one day we decide to use plugins when building
     // host tools, we can improve this by (for example) creating a compiler configuration that is
     // used only for building plugins.
-    @Option(name = "plugin",
-        converter = LabelConverter.class,
-        allowMultiple = true,
-        defaultValue = "",
-        category = "flags",
-        help = "Plugins to use in the build. Currently works with java_plugin.")
+    @Option(
+      name = "plugin",
+      converter = LabelConverter.class,
+      allowMultiple = true,
+      defaultValue = "",
+      category = "flags",
+      help = "Plugins to use in the build. Currently works with java_plugin."
+    )
     public List<Label> pluginList;
 
-    @Option(name = "plugin_copt",
-        converter = PluginOptionConverter.class,
-        allowMultiple = true,
-        category = "flags",
-        defaultValue = ":",
-        help = "Plugin options")
+    @Option(
+      name = "plugin_copt",
+      converter = PluginOptionConverter.class,
+      allowMultiple = true,
+      category = "flags",
+      defaultValue = ":",
+      help = "Plugin options"
+    )
     public List<Map.Entry<String, String>> pluginCoptList;
 
-    @Option(name = "stamp",
-        defaultValue = "false",
-        category = "semantics",
-        help = "Stamp binaries with the date, username, hostname, workspace information, etc.")
+    @Option(
+      name = "stamp",
+      defaultValue = "false",
+      category = "semantics",
+      help = "Stamp binaries with the date, username, hostname, workspace information, etc."
+    )
     public boolean stampBinaries;
 
     // This default value is always overwritten in the case of "bazel coverage" by
     // CoverageCommand.setDefaultInstrumentationFilter().
-    @Option(name = "instrumentation_filter",
-        converter = RegexFilter.RegexFilterConverter.class,
-        defaultValue = "-/javatests[/:]",
-        category = "semantics",
-        help = "When coverage is enabled, only rules with names included by the "
-            + "specified regex-based filter will be instrumented. Rules prefixed "
-            + "with '-' are excluded instead. Note that only non-test rules are "
-            + "instrumented unless --instrument_test_targets is enabled.")
+    @Option(
+      name = "instrumentation_filter",
+      converter = RegexFilter.RegexFilterConverter.class,
+      defaultValue = "-/javatests[/:]",
+      category = "semantics",
+      help =
+          "When coverage is enabled, only rules with names included by the "
+              + "specified regex-based filter will be instrumented. Rules prefixed "
+              + "with '-' are excluded instead. Note that only non-test rules are "
+              + "instrumented unless --instrument_test_targets is enabled."
+    )
     public RegexFilter instrumentationFilter;
 
-    @Option(name = "instrument_test_targets",
-        defaultValue = "false",
-        category = "semantics",
-        help = "When coverage is enabled, specifies whether to consider instrumenting test rules. "
-            + "When set, test rules included by --instrumentation_filter are instrumented. "
-            + "Otherwise, test rules are always excluded from coverage instrumentation.")
+    @Option(
+      name = "instrument_test_targets",
+      defaultValue = "false",
+      category = "semantics",
+      help =
+          "When coverage is enabled, specifies whether to consider instrumenting test rules. "
+              + "When set, test rules included by --instrumentation_filter are instrumented. "
+              + "Otherwise, test rules are always excluded from coverage instrumentation."
+    )
     public boolean instrumentTestTargets;
 
-    @Option(name = "host_cpu",
-        defaultValue = "",
-        category = "semantics",
-        converter = AutoCpuConverter.class,
-        help = "The host CPU.")
+    @Option(
+      name = "host_cpu",
+      defaultValue = "",
+      category = "semantics",
+      converter = AutoCpuConverter.class,
+      help = "The host CPU."
+    )
     public String hostCpu;
 
-    @Option(name = "compilation_mode",
-        abbrev = 'c',
-        converter = CompilationMode.Converter.class,
-        defaultValue = "fastbuild",
-        category = "semantics", // Should this be "flags"?
-        help = "Specify the mode the binary will be built in. "
-            + "Values: 'fastbuild', 'dbg', 'opt'.")
+    @Option(
+      name = "compilation_mode",
+      abbrev = 'c',
+      converter = CompilationMode.Converter.class,
+      defaultValue = "fastbuild",
+      category = "semantics", // Should this be "flags"?
+      help = "Specify the mode the binary will be built in. " + "Values: 'fastbuild', 'dbg', 'opt'."
+    )
     public CompilationMode compilationMode;
 
     /**
@@ -603,31 +634,37 @@ public final class BuildConfiguration {
      * to a constant, so that the output files for the host are completely independent of those for
      * the target, no matter what options are in force (k8/piii, opt/dbg, etc).
      */
-    @Option(name = "output directory name",
-        defaultValue = "null",
-        category = "internal")
+    @Option(
+      name = "output directory name",
+      defaultValue = "null",
+      optionUsageRestrictions = OptionUsageRestrictions.INTERNAL
+    )
     public String outputDirectoryName;
 
-    @Option(name = "platform_suffix",
-        defaultValue = "null",
-        category = "misc",
-        help = "Specifies a suffix to be added to the configuration directory.")
+    @Option(
+      name = "platform_suffix",
+      defaultValue = "null",
+      category = "misc",
+      help = "Specifies a suffix to be added to the configuration directory."
+    )
     public String platformSuffix;
 
     // TODO(bazel-team): The test environment is actually computed in BlazeRuntime and this option
     // is not read anywhere else. Thus, it should be in a different options class, preferably one
     // specific to the "test" command or maybe in its own configuration fragment.
     // BlazeRuntime, though.
-    @Option(name = "test_env",
-        converter = Converters.OptionalAssignmentConverter.class,
-        allowMultiple = true,
-        defaultValue = "",
-        category = "testing",
-        help = "Specifies additional environment variables to be injected into the test runner "
-            + "environment. Variables can be either specified by name, in which case its value "
-            + "will be read from the Bazel client environment, or by the name=value pair. "
-            + "This option can be used multiple times to specify several variables. "
-            + "Used only by the 'bazel test' command."
+    @Option(
+      name = "test_env",
+      converter = Converters.OptionalAssignmentConverter.class,
+      allowMultiple = true,
+      defaultValue = "",
+      category = "testing",
+      help =
+          "Specifies additional environment variables to be injected into the test runner "
+              + "environment. Variables can be either specified by name, in which case its value "
+              + "will be read from the Bazel client environment, or by the name=value pair. "
+              + "This option can be used multiple times to specify several variables. "
+              + "Used only by the 'bazel test' command."
     )
     public List<Map.Entry<String, String>> testEnvironment;
 
@@ -650,226 +687,273 @@ public final class BuildConfiguration {
     )
     public List<Map.Entry<String, String>> actionEnvironment;
 
-    @Option(name = "collect_code_coverage",
-        defaultValue = "false",
-        category = "testing",
-        help = "If specified, Bazel will instrument code (using offline instrumentation where "
-            + "possible) and will collect coverage information during tests. Only targets that "
-            + " match --instrumentation_filter will be affected. Usually this option should "
-            + " not be specified directly - 'bazel coverage' command should be used instead."
+    @Option(
+      name = "collect_code_coverage",
+      defaultValue = "false",
+      category = "testing",
+      help =
+          "If specified, Bazel will instrument code (using offline instrumentation where "
+              + "possible) and will collect coverage information during tests. Only targets that "
+              + " match --instrumentation_filter will be affected. Usually this option should "
+              + " not be specified directly - 'bazel coverage' command should be used instead."
     )
     public boolean collectCodeCoverage;
 
-    @Option(name = "microcoverage",
-        defaultValue = "false",
-        category = "testing",
-        help = "If specified with coverage, Blaze will collect microcoverage (per test method "
-            + "coverage) information during tests. Only targets that match "
-            + "--instrumentation_filter will be affected. Usually this option should not be "
-            + "specified directly - 'blaze coverage --microcoverage' command should be used "
-            + "instead."
+    @Option(
+      name = "microcoverage",
+      defaultValue = "false",
+      category = "testing",
+      help =
+          "If specified with coverage, Blaze will collect microcoverage (per test method "
+              + "coverage) information during tests. Only targets that match "
+              + "--instrumentation_filter will be affected. Usually this option should not be "
+              + "specified directly - 'blaze coverage --microcoverage' command should be used "
+              + "instead."
     )
     public boolean collectMicroCoverage;
 
-    @Option(name = "coverage_support",
-        converter = LabelConverter.class,
-        defaultValue = "@bazel_tools//tools/test:coverage_support",
-        category = "testing",
-        help = "Location of support files that are required on the inputs of every test action "
-            + "that collects code coverage. Defaults to '//tools/test:coverage_support'.")
+    @Option(
+      name = "coverage_support",
+      converter = LabelConverter.class,
+      defaultValue = "@bazel_tools//tools/test:coverage_support",
+      category = "testing",
+      help =
+          "Location of support files that are required on the inputs of every test action "
+              + "that collects code coverage. Defaults to '//tools/test:coverage_support'."
+    )
     public Label coverageSupport;
 
-    @Option(name = "coverage_report_generator",
-        converter = LabelConverter.class,
-        defaultValue = "@bazel_tools//tools/test:coverage_report_generator",
-        category = "testing",
-        help = "Location of the binary that is used to generate coverage reports. This must "
-            + "currently be a filegroup that contains a single file, the binary. Defaults to "
-            + "'//tools/test:coverage_report_generator'.")
+    @Option(
+      name = "coverage_report_generator",
+      converter = LabelConverter.class,
+      defaultValue = "@bazel_tools//tools/test:coverage_report_generator",
+      category = "testing",
+      help =
+          "Location of the binary that is used to generate coverage reports. This must "
+              + "currently be a filegroup that contains a single file, the binary. Defaults to "
+              + "'//tools/test:coverage_report_generator'."
+    )
     public Label coverageReportGenerator;
 
-    @Option(name = "experimental_use_llvm_covmap",
-        defaultValue = "false",
-        category = "experimental",
-        help = "If specified, Bazel will generate llvm-cov coverage map information rather than "
-            + "gcov when collect_code_coverage is enabled."
+    @Option(
+      name = "experimental_use_llvm_covmap",
+      defaultValue = "false",
+      category = "experimental",
+      help =
+          "If specified, Bazel will generate llvm-cov coverage map information rather than "
+              + "gcov when collect_code_coverage is enabled."
     )
     public boolean useLLVMCoverageMapFormat;
 
-    @Option(name = "cache_test_results",
-        defaultValue = "auto",
-        category = "testing",
-        abbrev = 't', // it's useful to toggle this on/off quickly
-        help = "If 'auto', Bazel will only rerun a test if any of the following conditions apply: "
-            + "(1) Bazel detects changes in the test or its dependencies "
-            + "(2) the test is marked as external "
-            + "(3) multiple test runs were requested with --runs_per_test "
-            + "(4) the test failed "
-            + "If 'yes', the caching behavior will be the same as 'auto' except that "
-            + "it may cache test failures and test runs with --runs_per_test. "
-            + "If 'no', all tests will be always executed.")
+    @Option(
+      name = "cache_test_results",
+      defaultValue = "auto",
+      category = "testing",
+      abbrev = 't', // it's useful to toggle this on/off quickly
+      help =
+          "If 'auto', Bazel will only rerun a test if any of the following conditions apply: "
+              + "(1) Bazel detects changes in the test or its dependencies "
+              + "(2) the test is marked as external "
+              + "(3) multiple test runs were requested with --runs_per_test "
+              + "(4) the test failed "
+              + "If 'yes', the caching behavior will be the same as 'auto' except that "
+              + "it may cache test failures and test runs with --runs_per_test. "
+              + "If 'no', all tests will be always executed."
+    )
     public TriState cacheTestResults;
 
     @Deprecated
-    @Option(name = "test_result_expiration",
-        defaultValue = "-1", // No expiration by defualt.
-        category = "testing",
-        help = "This option is deprecated and has no effect.")
+    @Option(
+      name = "test_result_expiration",
+      defaultValue = "-1", // No expiration by defualt.
+      category = "testing",
+      help = "This option is deprecated and has no effect."
+    )
     public int testResultExpiration;
 
-    @Option(name = "test_sharding_strategy",
-        defaultValue = "explicit",
-        category = "testing",
-        converter = TestActionBuilder.ShardingStrategyConverter.class,
-        help = "Specify strategy for test sharding: "
-            + "'explicit' to only use sharding if the 'shard_count' BUILD attribute is present. "
-            + "'disabled' to never use test sharding. "
-            + "'experimental_heuristic' to enable sharding on remotely executed tests without an "
-            + "explicit  'shard_count' attribute which link in a supported framework. Considered "
-            + "experimental.")
+    @Option(
+      name = "test_sharding_strategy",
+      defaultValue = "explicit",
+      category = "testing",
+      converter = TestActionBuilder.ShardingStrategyConverter.class,
+      help =
+          "Specify strategy for test sharding: "
+              + "'explicit' to only use sharding if the 'shard_count' BUILD attribute is present. "
+              + "'disabled' to never use test sharding. "
+              + "'experimental_heuristic' to enable sharding on remotely executed tests without an "
+              + "explicit  'shard_count' attribute which link in a supported framework. Considered "
+              + "experimental."
+    )
     public TestActionBuilder.TestShardingStrategy testShardingStrategy;
 
-    @Option(name = "runs_per_test",
-        allowMultiple = true,
-        defaultValue = "1",
-        category = "testing",
-        converter = RunsPerTestConverter.class,
-        help = "Specifies number of times to run each test. If any of those attempts "
-            + "fail for any reason, the whole test would be considered failed. "
-            + "Normally the value specified is just an integer. Example: --runs_per_test=3 "
-            + "will run all tests 3 times. "
-            + "Alternate syntax: regex_filter@runs_per_test. Where runs_per_test stands for "
-            + "an integer value and regex_filter stands "
-            + "for a list of include and exclude regular expression patterns (Also see "
-            + "--instrumentation_filter). Example: "
-            + "--runs_per_test=//foo/.*,-//foo/bar/.*@3 runs all tests in //foo/ "
-            + "except those under foo/bar three times. "
-            + "This option can be passed multiple times. ")
+    @Option(
+      name = "runs_per_test",
+      allowMultiple = true,
+      defaultValue = "1",
+      category = "testing",
+      converter = RunsPerTestConverter.class,
+      help =
+          "Specifies number of times to run each test. If any of those attempts "
+              + "fail for any reason, the whole test would be considered failed. "
+              + "Normally the value specified is just an integer. Example: --runs_per_test=3 "
+              + "will run all tests 3 times. "
+              + "Alternate syntax: regex_filter@runs_per_test. Where runs_per_test stands for "
+              + "an integer value and regex_filter stands "
+              + "for a list of include and exclude regular expression patterns (Also see "
+              + "--instrumentation_filter). Example: "
+              + "--runs_per_test=//foo/.*,-//foo/bar/.*@3 runs all tests in //foo/ "
+              + "except those under foo/bar three times. "
+              + "This option can be passed multiple times. "
+    )
     public List<PerLabelOptions> runsPerTest;
 
-    @Option(name = "build_runfile_links",
-        defaultValue = "true",
-        category = "strategy",
-        help = "If true, build runfiles symlink forests for all targets.  "
-            + "If false, write only manifests when possible.")
+    @Option(
+      name = "build_runfile_links",
+      defaultValue = "true",
+      category = "strategy",
+      help =
+          "If true, build runfiles symlink forests for all targets.  "
+              + "If false, write only manifests when possible."
+    )
     public boolean buildRunfiles;
 
-    @Option(name = "legacy_external_runfiles",
-        defaultValue = "true",
-        category = "strategy",
-        help = "If true, build runfiles symlink forests for external repositories under "
-            + ".runfiles/wsname/external/repo (in addition to .runfiles/repo).")
+    @Option(
+      name = "legacy_external_runfiles",
+      defaultValue = "true",
+      category = "strategy",
+      help =
+          "If true, build runfiles symlink forests for external repositories under "
+              + ".runfiles/wsname/external/repo (in addition to .runfiles/repo)."
+    )
     public boolean legacyExternalRunfiles;
 
-    @Option(name = "test_arg",
-        allowMultiple = true,
-        defaultValue = "",
-        category = "testing",
-        help = "Specifies additional options and arguments that should be passed to the test "
-            + "executable. Can be used multiple times to specify several arguments. "
-            + "If multiple tests are executed, each of them will receive identical arguments. "
-            + "Used only by the 'bazel test' command."
+    @Option(
+      name = "test_arg",
+      allowMultiple = true,
+      defaultValue = "",
+      category = "testing",
+      help =
+          "Specifies additional options and arguments that should be passed to the test "
+              + "executable. Can be used multiple times to specify several arguments. "
+              + "If multiple tests are executed, each of them will receive identical arguments. "
+              + "Used only by the 'bazel test' command."
     )
     public List<String> testArguments;
 
-    @Option(name = "test_filter",
-        allowMultiple = false,
-        defaultValue = "null",
-        category = "testing",
-        help = "Specifies a filter to forward to the test framework.  Used to limit "
-            + "the tests run. Note that this does not affect which targets are built.")
+    @Option(
+      name = "test_filter",
+      allowMultiple = false,
+      defaultValue = "null",
+      category = "testing",
+      help =
+          "Specifies a filter to forward to the test framework.  Used to limit "
+              + "the tests run. Note that this does not affect which targets are built."
+    )
     public String testFilter;
 
-    @Option(name = "check_fileset_dependencies_recursively",
-        defaultValue = "true",
-        category = "semantics",
-        help = "If false, fileset targets will, whenever possible, create "
-            + "symlinks to directories instead of creating one symlink for each "
-            + "file inside the directory. Disabling this will significantly "
-            + "speed up fileset builds, but targets that depend on filesets will "
-            + "not be rebuilt if files are added, removed or modified in a "
-            + "subdirectory which has not been traversed.")
+    @Option(
+      name = "check_fileset_dependencies_recursively",
+      defaultValue = "true",
+      category = "semantics",
+      help =
+          "If false, fileset targets will, whenever possible, create "
+              + "symlinks to directories instead of creating one symlink for each "
+              + "file inside the directory. Disabling this will significantly "
+              + "speed up fileset builds, but targets that depend on filesets will "
+              + "not be rebuilt if files are added, removed or modified in a "
+              + "subdirectory which has not been traversed."
+    )
     public boolean checkFilesetDependenciesRecursively;
 
     @Option(
-        name = "experimental_skyframe_native_filesets",
-        defaultValue = "false",
-        category = "experimental",
-        help =
-            "If true, Blaze will use the skyframe-native implementation of the Fileset rule."
-                + " This offers improved performance in incremental builds of Filesets as well as"
-                + " correct incremental behavior, but is not yet stable. The default is false,"
-                + " meaning Blaze uses the legacy impelementation of Fileset."
+      name = "experimental_skyframe_native_filesets",
+      defaultValue = "false",
+      category = "experimental",
+      help =
+          "If true, Blaze will use the skyframe-native implementation of the Fileset rule."
+              + " This offers improved performance in incremental builds of Filesets as well as"
+              + " correct incremental behavior, but is not yet stable. The default is false,"
+              + " meaning Blaze uses the legacy impelementation of Fileset."
     )
     public boolean skyframeNativeFileset;
 
     @Option(
-        name = "run_under",
-        category = "run",
-        defaultValue = "null",
-        converter = RunUnderConverter.class,
-        help =
-            "Prefix to insert in front of command before running. "
-                + "Examples:\n"
-                + "\t--run_under=valgrind\n"
-                + "\t--run_under=strace\n"
-                + "\t--run_under='strace -c'\n"
-                + "\t--run_under='valgrind --quiet --num-callers=20'\n"
-                + "\t--run_under=//package:target\n"
-                + "\t--run_under='//package:target --options'\n"
+      name = "run_under",
+      category = "run",
+      defaultValue = "null",
+      converter = RunUnderConverter.class,
+      help =
+          "Prefix to insert in front of command before running. "
+              + "Examples:\n"
+              + "\t--run_under=valgrind\n"
+              + "\t--run_under=strace\n"
+              + "\t--run_under='strace -c'\n"
+              + "\t--run_under='valgrind --quiet --num-callers=20'\n"
+              + "\t--run_under=//package:target\n"
+              + "\t--run_under='//package:target --options'\n"
     )
     public RunUnder runUnder;
 
-    @Option(name = "distinct_host_configuration",
-        defaultValue = "true",
-        category = "strategy",
-        help = "Build all the tools used during the build for a distinct configuration from "
-            + "that used for the target program. When this is disabled, the same configuration "
-            + "is used for host and target programs. This may cause undesirable rebuilds of tools "
-            + "such as the protocol compiler (and then everything downstream) whenever a minor "
-            + "change is made to the target configuration, such as setting the linker options. "
-            + "When this enabled (the default), a distinct configuration will be used to build the "
-            + "tools, preventing undesired rebuilds. However, certain libraries will then "
-            + "need to be compiled twice, once for each configuration, which may cause some "
-            + "builds to be slower. As a rule of thumb, this option is likely to benefit "
-            + "users that make frequent changes in configuration (e.g. opt/dbg).  "
-            + "Please read the user manual for the full explanation.")
+    @Option(
+      name = "distinct_host_configuration",
+      defaultValue = "true",
+      category = "strategy",
+      help =
+          "Build all the tools used during the build for a distinct configuration from that used "
+              + "for the target program. When this is disabled, the same configuration is used for "
+              + "host and target programs. This may cause undesirable rebuilds of tools such as "
+              + "the protocol compiler (and then everything downstream) whenever a minor change "
+              + "is made to the target configuration, such as setting the linker options. When "
+              + "this is enabled (the default), a distinct configuration will be used to build the "
+              + "tools, preventing undesired rebuilds. However, certain libraries will then need "
+              + "to be compiled twice, once for each configuration, which may cause some builds "
+              + "to be slower. As a rule of thumb, this option is likely to benefit users that "
+              + "make frequent changes in configuration (e.g. opt/dbg).  "
+              + "Please read the user manual for the full explanation."
+    )
     public boolean useDistinctHostConfiguration;
 
-    @Option(name = "check_visibility",
-        defaultValue = "true",
-        category = "checking",
-        help = "If disabled, visibility errors are demoted to warnings.")
+    @Option(
+      name = "check_visibility",
+      defaultValue = "true",
+      category = "checking",
+      help = "If disabled, visibility errors are demoted to warnings."
+    )
     public boolean checkVisibility;
 
     // Moved from viewOptions to here because license information is very expensive to serialize.
     // Having it here allows us to skip computation of transitive license information completely
     // when the setting is disabled.
-    @Option(name = "check_licenses",
-        defaultValue = "false",
-        category = "checking",
-        help = "Check that licensing constraints imposed by dependent packages "
-            + "do not conflict with distribution modes of the targets being built. "
-            + "By default, licenses are not checked.")
+    @Option(
+      name = "check_licenses",
+      defaultValue = "false",
+      category = "checking",
+      help =
+          "Check that licensing constraints imposed by dependent packages "
+              + "do not conflict with distribution modes of the targets being built. "
+              + "By default, licenses are not checked."
+    )
     public boolean checkLicenses;
 
     @Option(
-        name = "enforce_constraints",
-        defaultValue = "true",
-        category = "undocumented",
-        help =
-            "Checks the environments each target is compatible with and reports errors if any "
-                + "target has dependencies that don't support the same environments",
-        oldName = "experimental_enforce_constraints"
+      name = "enforce_constraints",
+      defaultValue = "true",
+      optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED,
+      help =
+          "Checks the environments each target is compatible with and reports errors if any "
+              + "target has dependencies that don't support the same environments",
+      oldName = "experimental_enforce_constraints"
     )
     public boolean enforceConstraints;
 
-    @Option(name = "experimental_action_listener",
-        allowMultiple = true,
-        defaultValue = "",
-        category = "experimental",
-        converter = LabelConverter.class,
-        help = "Use action_listener to attach an extra_action to existing build actions.")
+    @Option(
+      name = "experimental_action_listener",
+      allowMultiple = true,
+      defaultValue = "",
+      category = "experimental",
+      converter = LabelConverter.class,
+      help = "Use action_listener to attach an extra_action to existing build actions."
+    )
     public List<Label> actionListeners;
 
     // TODO(bazel-team): Either remove this flag once transparent compression is shown to not
@@ -878,38 +962,45 @@ public final class BuildConfiguration {
     @Option(
       name = "experimental_transparent_compression",
       defaultValue = "true",
-      category = "undocumented",
+      optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED,
       help =
           "Enables gzip compression for the contents of FileWriteActions, which reduces "
               + "memory usage in the analysis phase at the expense of additional time overhead."
     )
     public boolean transparentCompression;
 
-    @Option(name = "is host configuration",
-        defaultValue = "false",
-        category = "internal",
-        help = "Shows whether these options are set for host configuration.")
+    @Option(
+      name = "is host configuration",
+      defaultValue = "false",
+      optionUsageRestrictions = OptionUsageRestrictions.INTERNAL,
+      help = "Shows whether these options are set for host configuration."
+    )
     public boolean isHost;
 
-    @Option(name = "features",
-        allowMultiple = true,
-        defaultValue = "",
-        category = "flags",
-        help = "The given features will be enabled or disabled by default for all packages. "
-            + "Specifying -<feature> will disable the feature globally. "
-            + "Negative features always override positive ones. "
-            + "This flag is used to enable rolling out default feature changes without a "
-            + "Blaze release.")
+    @Option(
+      name = "features",
+      allowMultiple = true,
+      defaultValue = "",
+      category = "flags",
+      help =
+          "The given features will be enabled or disabled by default for all packages. "
+              + "Specifying -<feature> will disable the feature globally. "
+              + "Negative features always override positive ones. "
+              + "This flag is used to enable rolling out default feature changes without a "
+              + "Blaze release."
+    )
     public List<String> defaultFeatures;
 
-    @Option(name = "target_environment",
-        converter = LabelConverter.class,
-        allowMultiple = true,
-        defaultValue = "",
-        category = "flags",
-        help = "Declares this build's target environment. Must be a label reference to an "
-            + "\"environment\" rule. If specified, all top-level targets must be "
-            + "compatible with this environment."
+    @Option(
+      name = "target_environment",
+      converter = LabelConverter.class,
+      allowMultiple = true,
+      defaultValue = "",
+      category = "flags",
+      help =
+          "Declares this build's target environment. Must be a label reference to an "
+              + "\"environment\" rule. If specified, all top-level targets must be "
+              + "compatible with this environment."
     )
     public List<Label> targetEnvironments;
 
@@ -941,27 +1032,30 @@ public final class BuildConfiguration {
       }
     }
 
-    @Option(name = "experimental_dynamic_configs",
-        defaultValue = "notrim_partial",
-        category = "undocumented",
-        converter = DynamicConfigsConverter.class,
-        help = "Dynamically instantiates build configurations instead of using the default "
-            + "static globally defined ones")
+    @Option(
+      name = "experimental_dynamic_configs",
+      defaultValue = "notrim_partial",
+      optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED,
+      converter = DynamicConfigsConverter.class,
+      help =
+          "Dynamically instantiates build configurations instead of using the default "
+              + "static globally defined ones"
+    )
     public DynamicConfigsMode useDynamicConfigurations;
 
     @Option(
-        name = "experimental_enable_runfiles",
-        defaultValue = "auto",
-        category = "undocumented",
-        help = "Enable runfiles; off on Windows, on on other platforms"
+      name = "experimental_enable_runfiles",
+      defaultValue = "auto",
+      optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED,
+      help = "Enable runfiles; off on Windows, on on other platforms"
     )
     public TriState enableRunfiles;
 
     @Option(
-        name = "build_python_zip",
-        defaultValue = "auto",
-        category = "undocumented",
-        help = "Build python executable zip; on on Windows, off on other platforms"
+      name = "build_python_zip",
+      defaultValue = "auto",
+      optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED,
+      help = "Build python executable zip; on on Windows, off on other platforms"
     )
     public TriState buildPythonZip;
 
diff --git a/src/main/java/com/google/devtools/build/lib/bazel/repository/RepositoryOptions.java b/src/main/java/com/google/devtools/build/lib/bazel/repository/RepositoryOptions.java
index 84b1fa251e..3fdf939f4c 100644
--- a/src/main/java/com/google/devtools/build/lib/bazel/repository/RepositoryOptions.java
+++ b/src/main/java/com/google/devtools/build/lib/bazel/repository/RepositoryOptions.java
@@ -18,18 +18,22 @@ import com.google.devtools.build.lib.util.OptionsUtils;
 import com.google.devtools.build.lib.vfs.PathFragment;
 import com.google.devtools.common.options.Option;
 import com.google.devtools.common.options.OptionsBase;
+import com.google.devtools.common.options.OptionsParser.OptionUsageRestrictions;
 
 /**
  * Command-line options for repositories.
  */
 public class RepositoryOptions extends OptionsBase {
 
-  @Option(name = "experimental_repository_cache",
-          defaultValue = "null",
-          category = "hidden",
-          converter = OptionsUtils.PathFragmentConverter.class,
-          help = "Specifies the cache location of the downloaded values obtained "
-              + "during the fetching of external repositories.")
+  @Option(
+    name = "experimental_repository_cache",
+    defaultValue = "null",
+    optionUsageRestrictions = OptionUsageRestrictions.HIDDEN,
+    converter = OptionsUtils.PathFragmentConverter.class,
+    help =
+        "Specifies the cache location of the downloaded values obtained "
+            + "during the fetching of external repositories."
+  )
   public PathFragment experimentalRepositoryCache;
 
 }
\ No newline at end of file
diff --git a/src/main/java/com/google/devtools/build/lib/bazel/rules/python/BazelPythonConfiguration.java b/src/main/java/com/google/devtools/build/lib/bazel/rules/python/BazelPythonConfiguration.java
index 6c1a124d88..37298bf810 100644
--- a/src/main/java/com/google/devtools/build/lib/bazel/rules/python/BazelPythonConfiguration.java
+++ b/src/main/java/com/google/devtools/build/lib/bazel/rules/python/BazelPythonConfiguration.java
@@ -26,6 +26,7 @@ import com.google.devtools.build.lib.concurrent.ThreadSafety.Immutable;
 import com.google.devtools.build.lib.util.OS;
 import com.google.devtools.common.options.Converter;
 import com.google.devtools.common.options.Option;
+import com.google.devtools.common.options.OptionsParser.OptionUsageRestrictions;
 import javax.annotation.Nullable;
 
 /**
@@ -71,10 +72,12 @@ public class BazelPythonConfiguration extends BuildConfiguration.Fragment {
     )
     public String python3Path;
 
-    @Option(name = "experimental_python_import_all_repositories",
+    @Option(
+      name = "experimental_python_import_all_repositories",
       defaultValue = "true",
-      category = "undocumented",
-      help = "Do not use.")
+      optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED,
+      help = "Do not use."
+    )
     public boolean experimentalPythonImportAllRepositories;
   }
 
diff --git a/src/main/java/com/google/devtools/build/lib/buildeventstream/transports/BuildEventStreamOptions.java b/src/main/java/com/google/devtools/build/lib/buildeventstream/transports/BuildEventStreamOptions.java
index 67618a3fbb..da3805e22a 100644
--- a/src/main/java/com/google/devtools/build/lib/buildeventstream/transports/BuildEventStreamOptions.java
+++ b/src/main/java/com/google/devtools/build/lib/buildeventstream/transports/BuildEventStreamOptions.java
@@ -16,6 +16,7 @@ package com.google.devtools.build.lib.buildeventstream.transports;
 
 import com.google.devtools.common.options.Option;
 import com.google.devtools.common.options.OptionsBase;
+import com.google.devtools.common.options.OptionsParser.OptionUsageRestrictions;
 
 /** Options used to configure BuildEventStreamer and its BuildEventTransports. */
 public class BuildEventStreamOptions extends OptionsBase {
@@ -23,7 +24,7 @@ public class BuildEventStreamOptions extends OptionsBase {
   @Option(
     name = "experimental_build_event_text_file",
     defaultValue = "",
-    category = "hidden",
+    optionUsageRestrictions = OptionUsageRestrictions.HIDDEN,
     help = "If non-empty, write a textual representation of the build event protocol to that file"
   )
   public String buildEventTextFile;
@@ -31,7 +32,7 @@ public class BuildEventStreamOptions extends OptionsBase {
   @Option(
     name = "experimental_build_event_binary_file",
     defaultValue = "",
-    category = "hidden",
+    optionUsageRestrictions = OptionUsageRestrictions.HIDDEN,
     help =
         "If non-empty, write a varint delimited binary representation of representation of the"
             + " build event protocol to that file."
@@ -41,20 +42,22 @@ public class BuildEventStreamOptions extends OptionsBase {
   @Option(
     name = "experimental_build_event_text_file_path_conversion",
     defaultValue = "true",
-    category = "hidden",
-    help = "Convert paths in the text file representation of the build event protocol to more"
-        + " globally valid URIs whenever possible; if disabled, the file:// uri scheme will always"
-        + " be used"
+    optionUsageRestrictions = OptionUsageRestrictions.HIDDEN,
+    help =
+        "Convert paths in the text file representation of the build event protocol to more "
+            + "globally valid URIs whenever possible; if disabled, the file:// uri scheme will "
+            + "always be used"
   )
   public boolean buildEventTextFilePathConversion;
 
   @Option(
     name = "experimental_build_event_binary_file_path_conversion",
     defaultValue = "true",
-    category = "hidden",
-    help = "Convert paths in the binary file representation of the build event protocol to more"
-        + " globally valid URIs whenever possible; if disabled, the file:// uri scheme will always"
-        + " be used"
+    optionUsageRestrictions = OptionUsageRestrictions.HIDDEN,
+    help =
+        "Convert paths in the binary file representation of the build event protocol to more "
+            + "globally valid URIs whenever possible; if disabled, the file:// uri scheme will "
+            + "always be used"
   )
   public boolean buildEventBinaryFilePathConversion;
 
diff --git a/src/main/java/com/google/devtools/build/lib/buildtool/BuildRequest.java b/src/main/java/com/google/devtools/build/lib/buildtool/BuildRequest.java
index 577be35c8a..0f93ccc424 100644
--- a/src/main/java/com/google/devtools/build/lib/buildtool/BuildRequest.java
+++ b/src/main/java/com/google/devtools/build/lib/buildtool/BuildRequest.java
@@ -38,6 +38,7 @@ import com.google.devtools.common.options.Converters.RangeConverter;
 import com.google.devtools.common.options.Option;
 import com.google.devtools.common.options.OptionsBase;
 import com.google.devtools.common.options.OptionsClassProvider;
+import com.google.devtools.common.options.OptionsParser.OptionUsageRestrictions;
 import com.google.devtools.common.options.OptionsParsingException;
 import com.google.devtools.common.options.OptionsProvider;
 import java.util.ArrayList;
@@ -83,193 +84,234 @@ public class BuildRequest implements OptionsClassProvider {
     )
     public int jobs;
 
-    @Option(name = "progress_report_interval",
-            defaultValue = "0",
-            category = "verbosity",
-            converter = ProgressReportIntervalConverter.class,
-            help = "The number of seconds to wait between two reports on"
-                + " still running jobs.  The default value 0 means to use"
-                + " the default 10:30:60 incremental algorithm.")
+    @Option(
+      name = "progress_report_interval",
+      defaultValue = "0",
+      category = "verbosity",
+      converter = ProgressReportIntervalConverter.class,
+      help =
+          "The number of seconds to wait between two reports on still running jobs. The "
+              + "default value 0 means to use the default 10:30:60 incremental algorithm."
+    )
     public int progressReportInterval;
 
-    @Option(name = "explain",
-            defaultValue = "null",
-            category = "verbosity",
-            converter = OptionsUtils.PathFragmentConverter.class,
-            help = "Causes the build system to explain each executed step of the "
-            + "build. The explanation is written to the specified log file.")
+    @Option(
+      name = "explain",
+      defaultValue = "null",
+      category = "verbosity",
+      converter = OptionsUtils.PathFragmentConverter.class,
+      help =
+          "Causes the build system to explain each executed step of the "
+              + "build. The explanation is written to the specified log file."
+    )
     public PathFragment explanationPath;
 
-    @Option(name = "verbose_explanations",
-            defaultValue = "false",
-            category = "verbosity",
-            help = "Increases the verbosity of the explanations issued if --explain is enabled. "
-            + "Has no effect if --explain is not enabled.")
+    @Option(
+      name = "verbose_explanations",
+      defaultValue = "false",
+      category = "verbosity",
+      help =
+          "Increases the verbosity of the explanations issued if --explain is enabled. "
+              + "Has no effect if --explain is not enabled."
+    )
     public boolean verboseExplanations;
 
-    @Option(name = "output_filter",
-        converter = Converters.RegexPatternConverter.class,
-        defaultValue = "null",
-        category = "flags",
-        help = "Only shows warnings for rules with a name matching the provided regular "
-            + "expression.")
+    @Option(
+      name = "output_filter",
+      converter = Converters.RegexPatternConverter.class,
+      defaultValue = "null",
+      category = "flags",
+      help = "Only shows warnings for rules with a name matching the provided regular expression."
+    )
     public Pattern outputFilter;
 
     @Deprecated
-    @Option(name = "dump_makefile",
-            defaultValue = "false",
-            category = "undocumented",
-            help = "this flag has no effect.")
+    @Option(
+      name = "dump_makefile",
+      defaultValue = "false",
+      optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED,
+      help = "this flag has no effect."
+    )
     public boolean dumpMakefile;
 
     @Deprecated
-    @Option(name = "dump_action_graph",
-        defaultValue = "false",
-        category = "undocumented",
-        help = "this flag has no effect.")
-
+    @Option(
+      name = "dump_action_graph",
+      defaultValue = "false",
+      optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED,
+      help = "this flag has no effect."
+    )
     public boolean dumpActionGraph;
 
     @Deprecated
-    @Option(name = "dump_action_graph_for_package",
-        allowMultiple = true,
-        defaultValue = "",
-        category = "undocumented",
-        help = "this flag has no effect.")
+    @Option(
+      name = "dump_action_graph_for_package",
+      allowMultiple = true,
+      defaultValue = "",
+      optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED,
+      help = "this flag has no effect."
+    )
     public List<String> dumpActionGraphForPackage = new ArrayList<>();
 
     @Deprecated
-    @Option(name = "dump_action_graph_with_middlemen",
-        defaultValue = "true",
-        category = "undocumented",
-        help = "this flag has no effect.")
+    @Option(
+      name = "dump_action_graph_with_middlemen",
+      defaultValue = "true",
+      optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED,
+      help = "this flag has no effect."
+    )
     public boolean dumpActionGraphWithMiddlemen;
 
     @Deprecated
-    @Option(name = "dump_providers",
-        defaultValue = "false",
-        category = "undocumented",
-        help = "This is a no-op.")
+    @Option(
+      name = "dump_providers",
+      defaultValue = "false",
+      optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED,
+      help = "This is a no-op."
+    )
     public boolean dumpProviders;
 
     @Deprecated
-    @Option(name = "dump_targets",
-            defaultValue = "null",
-            category = "undocumented",
-        help = "this flag has no effect.")
+    @Option(
+      name = "dump_targets",
+      defaultValue = "null",
+      optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED,
+      help = "this flag has no effect."
+    )
     public String dumpTargets;
 
     @Deprecated
-    @Option(name = "dump_host_deps",
-        defaultValue = "true",
-        category = "undocumented",
-        help = "Deprecated")
+    @Option(
+      name = "dump_host_deps",
+      defaultValue = "true",
+      optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED,
+      help = "Deprecated"
+    )
     public boolean dumpHostDeps;
 
     @Deprecated
-    @Option(name = "dump_to_stdout",
-        defaultValue = "false",
-        category = "undocumented",
-        help = "Deprecated")
+    @Option(
+      name = "dump_to_stdout",
+      defaultValue = "false",
+      optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED,
+      help = "Deprecated"
+    )
     public boolean dumpToStdout;
 
-    @Option(name = "analyze",
-            defaultValue = "true",
-            category = "undocumented",
-            help = "Execute the analysis phase; this is the usual behaviour. "
-                + "Specifying --noanalyze causes the build to stop before starting the "
-                + "analysis phase, returning zero iff the package loading completed "
-                + "successfully; this mode is useful for testing.")
+    @Option(
+      name = "analyze",
+      defaultValue = "true",
+      optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED,
+      help =
+          "Execute the analysis phase; this is the usual behaviour. Specifying --noanalyze causes "
+              + "the build to stop before starting the analysis phase, returning zero iff the "
+              + "package loading completed successfully; this mode is useful for testing."
+    )
     public boolean performAnalysisPhase;
 
-    @Option(name = "build",
-            defaultValue = "true",
-            category = "what",
-            help = "Execute the build; this is the usual behaviour. "
-            + "Specifying --nobuild causes the build to stop before executing the "
-            + "build actions, returning zero iff the package loading and analysis "
-            + "phases completed successfully; this mode is useful for testing "
-            + "those phases.")
+    @Option(
+      name = "build",
+      defaultValue = "true",
+      category = "what",
+      help =
+          "Execute the build; this is the usual behaviour. "
+              + "Specifying --nobuild causes the build to stop before executing the build "
+              + "actions, returning zero iff the package loading and analysis phases completed "
+              + "successfully; this mode is useful for testing those phases."
+    )
     public boolean performExecutionPhase;
 
-    @Option(name = "output_groups",
-        converter = Converters.CommaSeparatedOptionListConverter.class,
-        allowMultiple = true,
-        defaultValue = "",
-        category = "undocumented",
-        help = "Specifies which output groups of the top-level targets to build. "
-            + "If omitted, a default set of output groups are built."
-            + "When specified the default set is overridden."
-            + "However you may use --output_groups=+<output_group> "
-            + "or --output_groups=-<output_group> "
-            + "to instead modify the set of output groups.")
+    @Option(
+      name = "output_groups",
+      converter = Converters.CommaSeparatedOptionListConverter.class,
+      allowMultiple = true,
+      defaultValue = "",
+      optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED,
+      help =
+          "Specifies which output groups of the top-level targets to build. If omitted, a default "
+              + "set of output groups are built. When specified the default set is overridden."
+              + "However you may use --output_groups=+<output_group> or "
+              + "--output_groups=-<output_group> to instead modify the set of output groups."
+    )
     public List<String> outputGroups;
 
-    @Option(name = "show_result",
-            defaultValue = "1",
-            category = "verbosity",
-            help = "Show the results of the build.  For each "
-            + "target, state whether or not it was brought up-to-date, and if "
-            + "so, a list of output files that were built.  The printed files "
-            + "are convenient strings for copy+pasting to the shell, to "
-            + "execute them.\n"
-            + "This option requires an integer argument, which "
-            + "is the threshold number of targets above which result "
-            + "information is not printed. "
-            + "Thus zero causes suppression of the message and MAX_INT "
-            + "causes printing of the result to occur always.  The default is one.")
+    @Option(
+      name = "show_result",
+      defaultValue = "1",
+      category = "verbosity",
+      help =
+          "Show the results of the build.  For each target, state whether or not it was brought "
+              + "up-to-date, and if so, a list of output files that were built.  The printed files "
+              + "are convenient strings for copy+pasting to the shell, to execute them.\n"
+              + "This option requires an integer argument, which is the threshold number of "
+              + "targets above which result information is not printed. Thus zero causes "
+              + "suppression of the message and MAX_INT causes printing of the result to occur "
+              + "always.  The default is one."
+    )
     public int maxResultTargets;
 
-    @Option(name = "experimental_show_artifacts",
-        defaultValue = "false",
-        category = "undocumented",
-        help = "Output a list of all top level artifacts produced by this build."
-            + "Use output format suitable for tool consumption. "
-            + "This flag is temporary and intended to facilitate Android Studio integration. "
-            + "This output format will likely change in the future or disappear completely."
+    @Option(
+      name = "experimental_show_artifacts",
+      defaultValue = "false",
+      optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED,
+      help =
+          "Output a list of all top level artifacts produced by this build."
+              + "Use output format suitable for tool consumption. "
+              + "This flag is temporary and intended to facilitate Android Studio integration. "
+              + "This output format will likely change in the future or disappear completely."
     )
     public boolean showArtifacts;
 
-    @Option(name = "announce",
-            defaultValue = "false",
-            category = "verbosity",
-            help = "Deprecated. No-op.",
-            deprecationWarning = "This option is now deprecated and is a no-op")
+    @Option(
+      name = "announce",
+      defaultValue = "false",
+      category = "verbosity",
+      help = "Deprecated. No-op.",
+      deprecationWarning = "This option is now deprecated and is a no-op"
+    )
     public boolean announce;
 
-    @Option(name = "symlink_prefix",
-        defaultValue = "null",
-        category = "misc",
-        help = "The prefix that is prepended to any of the convenience symlinks that are created "
-            + "after a build. If '/' is passed, then no symlinks are created and no warning is "
-            + "emitted. If omitted, the default value is the name of the build tool."
-        )
+    @Option(
+      name = "symlink_prefix",
+      defaultValue = "null",
+      category = "misc",
+      help =
+          "The prefix that is prepended to any of the convenience symlinks that are created "
+              + "after a build. If '/' is passed, then no symlinks are created and no warning is "
+              + "emitted. If omitted, the default value is the name of the build tool."
+    )
     public String symlinkPrefix;
 
-    @Option(name = "experimental_multi_cpu",
-            converter = Converters.CommaSeparatedOptionListConverter.class,
-            allowMultiple = true,
-            defaultValue = "",
-            category = "semantics",
-            help = "This flag allows specifying multiple target CPUs. If this is specified, "
-                + "the --cpu option is ignored.")
+    @Option(
+      name = "experimental_multi_cpu",
+      converter = Converters.CommaSeparatedOptionListConverter.class,
+      allowMultiple = true,
+      defaultValue = "",
+      category = "semantics",
+      help =
+          "This flag allows specifying multiple target CPUs. If this is specified, "
+              + "the --cpu option is ignored."
+    )
     public List<String> multiCpus;
 
-    @Option(name = "output_tree_tracking",
-            oldName =  "experimental_output_tree_tracking",
-            defaultValue = "true",
-            category = "undocumented",
-            help = "If set, tell the output service (if any) to track when files in the output "
-                + "tree have been modified externally (not by the build system). "
-                + "This should improve incremental build speed when an appropriate output service "
-                + "is enabled.")
+    @Option(
+      name = "output_tree_tracking",
+      oldName = "experimental_output_tree_tracking",
+      defaultValue = "true",
+      optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED,
+      help =
+          "If set, tell the output service (if any) to track when files in the output "
+              + "tree have been modified externally (not by the build system). "
+              + "This should improve incremental build speed when an appropriate output service "
+              + "is enabled."
+    )
     public boolean finalizeActions;
 
     @Option(
       name = "aspects",
       converter = Converters.CommaSeparatedOptionListConverter.class,
       defaultValue = "",
-      category = "undocumented", // for now
+      optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED, // for now
       help = "List of top-level aspects"
     )
     public List<String> aspects;
@@ -281,7 +323,7 @@ public class BuildRequest implements OptionsClassProvider {
     @Option(
       name = "use_action_cache",
       defaultValue = "true",
-      category = "undocumented",
+      optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED,
       help = "Whether to use the action cache"
     )
     public boolean useActionCache;
diff --git a/src/main/java/com/google/devtools/build/lib/exec/ExecutionOptions.java b/src/main/java/com/google/devtools/build/lib/exec/ExecutionOptions.java
index c2b40c0859..1b0bb10c5e 100644
--- a/src/main/java/com/google/devtools/build/lib/exec/ExecutionOptions.java
+++ b/src/main/java/com/google/devtools/build/lib/exec/ExecutionOptions.java
@@ -22,6 +22,7 @@ import com.google.devtools.build.lib.vfs.PathFragment;
 import com.google.devtools.common.options.Option;
 import com.google.devtools.common.options.Options;
 import com.google.devtools.common.options.OptionsBase;
+import com.google.devtools.common.options.OptionsParser.OptionUsageRestrictions;
 import java.util.Map;
 
 /**
@@ -44,153 +45,189 @@ public class ExecutionOptions extends OptionsBase {
 
   public static final ExecutionOptions DEFAULTS = Options.getDefaults(ExecutionOptions.class);
 
-  @Option(name = "verbose_failures",
-          defaultValue = "false",
-          category = "verbosity",
-          help = "If a command fails, print out the full command line.")
+  @Option(
+    name = "verbose_failures",
+    defaultValue = "false",
+    category = "verbosity",
+    help = "If a command fails, print out the full command line."
+  )
   public boolean verboseFailures;
 
-  @Option(name = "subcommands",
-      abbrev = 's',
-      defaultValue = "false",
-      category = "verbosity",
-      help = "Display the subcommands executed during a build.")
+  @Option(
+    name = "subcommands",
+    abbrev = 's',
+    defaultValue = "false",
+    category = "verbosity",
+    help = "Display the subcommands executed during a build."
+  )
   public boolean showSubcommands;
 
-  @Option(name = "check_up_to_date",
-          defaultValue = "false",
-          category = "what",
-          help = "Don't perform the build, just check if it is up-to-date.  If all targets are "
-          + "up-to-date, the build completes successfully.  If any step needs to be executed "
-          + "an error is reported and the build fails.")
+  @Option(
+    name = "check_up_to_date",
+    defaultValue = "false",
+    category = "what",
+    help =
+        "Don't perform the build, just check if it is up-to-date.  If all targets are "
+            + "up-to-date, the build completes successfully.  If any step needs to be executed "
+            + "an error is reported and the build fails."
+  )
   public boolean checkUpToDate;
 
-  @Option(name = "check_tests_up_to_date",
-          defaultValue = "false",
-          category = "testing",
-          implicitRequirements = { "--check_up_to_date" },
-          help = "Don't run tests, just check if they are up-to-date.  If all tests results are "
-          + "up-to-date, the testing completes successfully.  If any test needs to be built or "
-          + "executed, an error is reported and the testing fails.  This option implies "
-          + "--check_up_to_date behavior."
-          )
+  @Option(
+    name = "check_tests_up_to_date",
+    defaultValue = "false",
+    category = "testing",
+    implicitRequirements = {"--check_up_to_date"},
+    help =
+        "Don't run tests, just check if they are up-to-date.  If all tests results are "
+            + "up-to-date, the testing completes successfully.  If any test needs to be built or "
+            + "executed, an error is reported and the testing fails.  This option implies "
+            + "--check_up_to_date behavior."
+  )
   public boolean testCheckUpToDate;
 
-  @Option(name = "test_strategy",
-      defaultValue = "",
-      category = "testing",
-      help = "Specifies which strategy to use when running tests.")
+  @Option(
+    name = "test_strategy",
+    defaultValue = "",
+    category = "testing",
+    help = "Specifies which strategy to use when running tests."
+  )
   public String testStrategy;
 
-  @Option(name = "test_keep_going",
-      defaultValue = "true",
-      category = "testing",
-      help = "When disabled, any non-passing test will cause the entire build to stop. By default "
-           + "all tests are run, even if some do not pass.")
+  @Option(
+    name = "test_keep_going",
+    defaultValue = "true",
+    category = "testing",
+    help =
+        "When disabled, any non-passing test will cause the entire build to stop. By default "
+            + "all tests are run, even if some do not pass."
+  )
   public boolean testKeepGoing;
 
-  @Option(name = "runs_per_test_detects_flakes",
-      defaultValue = "false",
-      category = "testing",
-      help = "If true, any shard in which at least one run/attempt passes and at least one "
-           + "run/attempt fails gets a FLAKY status.")
+  @Option(
+    name = "runs_per_test_detects_flakes",
+    defaultValue = "false",
+    category = "testing",
+    help =
+        "If true, any shard in which at least one run/attempt passes and at least one "
+            + "run/attempt fails gets a FLAKY status."
+  )
   public boolean runsPerTestDetectsFlakes;
 
-  @Option(name = "flaky_test_attempts",
-      defaultValue = "default",
-      category = "testing",
-      converter = TestStrategy.TestAttemptsConverter.class,
-      help = "Each test will be retried up to the specified number of times in case of any test "
-          + "failure. Tests that required more than one attempt to pass would be marked as "
-          + "'FLAKY' in the test summary. If this option is set, it should specify an int N or the "
-          + "string 'default'. If it's an int, then all tests will be run up to N times. If it is "
-          + "not specified or its value is 'default', then only a single test attempt will be made "
-          + "for regular tests and three for tests marked explicitly as flaky by their rule "
-          + "(flaky=1 attribute).")
+  @Option(
+    name = "flaky_test_attempts",
+    defaultValue = "default",
+    category = "testing",
+    converter = TestStrategy.TestAttemptsConverter.class,
+    help =
+        "Each test will be retried up to the specified number of times in case of any test "
+            + "failure. Tests that required more than one attempt to pass would be marked as "
+            + "'FLAKY' in the test summary. If this option is set, it should specify an int N or "
+            + "the string 'default'. If it's an int, then all tests will be run up to N times. "
+            + "If it is not specified or its value is 'default', then only a single test attempt "
+            + "will be made for regular tests and three for tests marked explicitly as flaky by "
+            + "their rule (flaky=1 attribute)."
+  )
   public int testAttempts;
 
-  @Option(name = "test_tmpdir",
-      defaultValue = "null",
-      category = "testing",
-      converter = OptionsUtils.PathFragmentConverter.class,
-      help = "Specifies the base temporary directory for 'blaze test' to use.")
+  @Option(
+    name = "test_tmpdir",
+    defaultValue = "null",
+    category = "testing",
+    converter = OptionsUtils.PathFragmentConverter.class,
+    help = "Specifies the base temporary directory for 'blaze test' to use."
+  )
   public PathFragment testTmpDir;
 
-  @Option(name = "test_output",
-      defaultValue = "summary",
-      category = "testing",
-      converter = TestStrategy.TestOutputFormat.Converter.class,
-      help = "Specifies desired output mode. Valid values are 'summary' to "
-          + "output only test status summary, 'errors' to also print test logs "
-          + "for failed tests, 'all' to print logs for all tests and 'streamed' "
-          + "to output logs for all tests in real time (this will force tests "
-          + "to be executed locally one at a time regardless of --test_strategy "
-          + "value).")
+  @Option(
+    name = "test_output",
+    defaultValue = "summary",
+    category = "testing",
+    converter = TestStrategy.TestOutputFormat.Converter.class,
+    help =
+        "Specifies desired output mode. Valid values are 'summary' to output only test status "
+            + "summary, 'errors' to also print test logs for failed tests, 'all' to print logs "
+            + "for all tests and 'streamed' to output logs for all tests in real time "
+            + "(this will force tests to be executed locally one at a time regardless of "
+            + "--test_strategy value)."
+  )
   public TestOutputFormat testOutput;
 
-  @Option(name = "test_summary",
-      defaultValue = "short",
-      category = "testing",
-      converter = TestStrategy.TestSummaryFormat.Converter.class,
-      help = "Specifies the desired format ot the test summary. Valid values "
-          + "are 'short' to print information only about tests executed, "
-          + "'terse', to print information only about unsuccessful tests,"
-          + "'detailed' to print detailed information about failed test cases, "
-          + "and 'none' to omit the summary.")
+  @Option(
+    name = "test_summary",
+    defaultValue = "short",
+    category = "testing",
+    converter = TestStrategy.TestSummaryFormat.Converter.class,
+    help =
+        "Specifies the desired format ot the test summary. Valid values are 'short' to print "
+            + "information only about tests executed, 'terse', to print information only about "
+            + "unsuccessful tests, 'detailed' to print detailed information about failed "
+            + "test cases, and 'none' to omit the summary."
+  )
   public TestSummaryFormat testSummary;
 
-  @Option(name = "test_timeout",
-      defaultValue = "-1",
-      category = "testing",
-      converter = TestTimeout.TestTimeoutConverter.class,
-      help = "Override the default test timeout values for test timeouts (in secs). If a single "
-        + "positive integer value is specified it will override all categories.  If 4 comma-"
-        + "separated integers are specified, they will override the timeouts for short, "
-        + "moderate, long and eternal (in that order). In either form, a value of -1 tells blaze "
-        + "to use its default timeouts for that category.")
+  @Option(
+    name = "test_timeout",
+    defaultValue = "-1",
+    category = "testing",
+    converter = TestTimeout.TestTimeoutConverter.class,
+    help =
+        "Override the default test timeout values for test timeouts (in secs). If a single "
+            + "positive integer value is specified it will override all categories.  If 4 "
+            + "comma-separated integers are specified, they will override the timeouts for short, "
+            + "moderate, long and eternal (in that order). In either form, a value of -1 tells "
+            + "blaze to use its default timeouts for that category."
+  )
   public Map<TestTimeout, Integer> testTimeout;
 
-  @Option(name = "resource_autosense",
-      defaultValue = "false",
-      category = "strategy",
-      help = "This flag has no effect, and is deprecated")
+  @Option(
+    name = "resource_autosense",
+    defaultValue = "false",
+    category = "strategy",
+    help = "This flag has no effect, and is deprecated"
+  )
   public boolean useResourceAutoSense;
 
-  @Option(name = "ram_utilization_factor",
-      defaultValue = "67",
-      category = "strategy",
-      help = "Specify what percentage of the system's RAM Blaze should try to use for its "
-      + "subprocesses. "
-      + "This option affects how many processes Blaze will try to run in parallel. "
-      + "If you run several Blaze builds in parallel, using a lower value for "
-      + "this option may avoid thrashing and thus improve overall throughput. "
-      + "Using a value higher than the default is NOT recommended. "
-      + "Note that Blaze's estimates are very coarse, so the actual RAM usage may be much "
-      + "higher or much lower than specified. "
-      + "Note also that this option does not affect the amount of memory that the Blaze "
-      + "server itself will use. "
-      )
+  @Option(
+    name = "ram_utilization_factor",
+    defaultValue = "67",
+    category = "strategy",
+    help =
+        "Specify what percentage of the system's RAM Blaze should try to use for its subprocesses. "
+            + "This option affects how many processes Blaze will try to run in parallel. "
+            + "If you run several Blaze builds in parallel, using a lower value for "
+            + "this option may avoid thrashing and thus improve overall throughput. "
+            + "Using a value higher than the default is NOT recommended. "
+            + "Note that Blaze's estimates are very coarse, so the actual RAM usage may be much "
+            + "higher or much lower than specified. "
+            + "Note also that this option does not affect the amount of memory that the Blaze "
+            + "server itself will use. "
+  )
   public int ramUtilizationPercentage;
 
-  @Option(name = "local_resources",
-      defaultValue = "null",
-      category = "strategy",
-      help = "Explicitly set amount of local resources available to Blaze. "
-      + "By default, Blaze will query system configuration to estimate amount of RAM (in MB) "
-      + "and number of CPU cores available for the locally executed build actions. It would also "
-      + "assume default I/O capabilities of the local workstation (1.0). This options allows to "
-      + "explicitly set all 3 values. Note, that if this option is used, Blaze will ignore "
-      + "--ram_utilization_factor.",
-      converter = ResourceSet.ResourceSetConverter.class
-      )
+  @Option(
+    name = "local_resources",
+    defaultValue = "null",
+    category = "strategy",
+    help =
+        "Explicitly set amount of local resources available to Blaze. "
+            + "By default, Blaze will query system configuration to estimate amount of RAM (in MB) "
+            + "and number of CPU cores available for the locally executed build actions. It would "
+            + "also assume default I/O capabilities of the local workstation (1.0). This options "
+            + "allows to explicitly set all 3 values. Note, that if this option is used, Blaze "
+            + "will ignore --ram_utilization_factor.",
+    converter = ResourceSet.ResourceSetConverter.class
+  )
   public ResourceSet availableResources;
 
-  @Option(name = "local_test_jobs",
-      defaultValue = "0",
-      category = "testing",
-      help = "The max number of local test jobs to run concurrently. "
-          + "0 means local resources will limit the number of local test jobs to run "
-          + "concurrently instead. Setting this greater than the value for --jobs is ineffectual."
+  @Option(
+    name = "local_test_jobs",
+    defaultValue = "0",
+    category = "testing",
+    help =
+        "The max number of local test jobs to run concurrently. "
+            + "0 means local resources will limit the number of local test jobs to run "
+            + "concurrently instead. Setting this greater than the value for --jobs is ineffectual."
   )
   public int localTestJobs;
 
@@ -201,7 +238,7 @@ public class ExecutionOptions extends OptionsBase {
   @Option(
     name = "debug_print_action_contexts",
     defaultValue = "false",
-    category = "undocumented",
+    optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED,
     help = "Print the contents of the SpawnActionContext and ContextProviders maps."
   )
   public boolean debugPrintActionContexts;
@@ -209,7 +246,7 @@ public class ExecutionOptions extends OptionsBase {
   @Option(
     name = "cache_computed_file_digests",
     defaultValue = "50000",
-    category = "undocumented",
+    optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED,
     help =
         "If greater than 0, configures Blaze to cache file digests in memory based on their "
             + "metadata instead of recomputing the digests from disk every time they are needed. "
@@ -219,11 +256,10 @@ public class ExecutionOptions extends OptionsBase {
   )
   public long cacheSizeForComputedFileDigests;
 
-
   @Option(
     name = "experimental_enable_critical_path_profiling",
     defaultValue = "true",
-    category = "undocumented",
+    optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED,
     help =
         "If set (the default), critical path profiling is enabled for the execution phase. "
             + "This has a slight overhead in RAM and CPU, and may prevent Bazel from making certain"
diff --git a/src/main/java/com/google/devtools/build/lib/exec/local/LocalExecutionOptions.java b/src/main/java/com/google/devtools/build/lib/exec/local/LocalExecutionOptions.java
index e36136b0d9..14fe8b1fdc 100644
--- a/src/main/java/com/google/devtools/build/lib/exec/local/LocalExecutionOptions.java
+++ b/src/main/java/com/google/devtools/build/lib/exec/local/LocalExecutionOptions.java
@@ -16,6 +16,7 @@ package com.google.devtools.build.lib.exec.local;
 import com.google.devtools.common.options.Converters;
 import com.google.devtools.common.options.Option;
 import com.google.devtools.common.options.OptionsBase;
+import com.google.devtools.common.options.OptionsParser.OptionUsageRestrictions;
 import java.util.regex.Pattern;
 
 /**
@@ -23,19 +24,25 @@ import java.util.regex.Pattern;
  */
 public class LocalExecutionOptions extends OptionsBase {
 
-  @Option(name = "local_termination_grace_seconds",
-      oldName = "local_sigkill_grace_seconds",
-      category = "remote execution",
-      defaultValue = "15",
-      help = "Time to wait between terminating a local process due to timeout and forcefully "
-          + "shutting it down.")
+  @Option(
+    name = "local_termination_grace_seconds",
+    oldName = "local_sigkill_grace_seconds",
+    category = "remote execution",
+    defaultValue = "15",
+    help =
+        "Time to wait between terminating a local process due to timeout and forcefully "
+            + "shutting it down."
+  )
   public double localSigkillGraceSeconds;
 
-  @Option(name = "allowed_local_actions_regex",
-      category = "undocumented",
-      converter = Converters.RegexPatternConverter.class,
-      defaultValue = "null",
-      help = "A regex whitelist for action types which may be run locally. If unset, "
-             + "all actions are allowed to execute locally")
+  @Option(
+    name = "allowed_local_actions_regex",
+    optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED,
+    converter = Converters.RegexPatternConverter.class,
+    defaultValue = "null",
+    help =
+        "A regex whitelist for action types which may be run locally. If unset, "
+            + "all actions are allowed to execute locally"
+  )
   public Pattern allowedLocalAction;
 }
diff --git a/src/main/java/com/google/devtools/build/lib/pkgcache/LoadingOptions.java b/src/main/java/com/google/devtools/build/lib/pkgcache/LoadingOptions.java
index b67eceea1e..4906aec484 100644
--- a/src/main/java/com/google/devtools/build/lib/pkgcache/LoadingOptions.java
+++ b/src/main/java/com/google/devtools/build/lib/pkgcache/LoadingOptions.java
@@ -18,6 +18,7 @@ import com.google.devtools.build.lib.packages.TestTimeout;
 import com.google.devtools.common.options.Converters.CommaSeparatedOptionListConverter;
 import com.google.devtools.common.options.Option;
 import com.google.devtools.common.options.OptionsBase;
+import com.google.devtools.common.options.OptionsParser.OptionUsageRestrictions;
 import java.util.List;
 import java.util.Set;
 
@@ -25,92 +26,107 @@ import java.util.Set;
  * Options that affect how command-line target patterns are resolved to individual targets.
  */
 public class LoadingOptions extends OptionsBase {
-  @Option(name = "build_tests_only",
-      defaultValue = "false",
-      category = "what",
-      help = "If specified, only *_test and test_suite rules will be built "
-        + "and other targets specified on the command line will be ignored. "
-        + "By default everything that was requested will be built.")
+  @Option(
+    name = "build_tests_only",
+    defaultValue = "false",
+    category = "what",
+    help =
+        "If specified, only *_test and test_suite rules will be built and other targets specified "
+            + "on the command line will be ignored. By default everything that was requested "
+            + "will be built."
+  )
   public boolean buildTestsOnly;
 
-  @Option(name = "compile_one_dependency",
-          defaultValue = "false",
-          category = "what",
-          help = "Compile a single dependency of the argument files.  "
-          + "This is useful for syntax checking source files in IDEs, "
-          + "for example, by rebuilding a single target that depends on "
-          + "the source file to detect errors as early as possible in the "
-          + "edit/build/test cycle.  This argument affects the way all "
-          + "non-flag arguments are interpreted; instead of being targets "
-          + "to build they are source filenames.  For each source filename "
-          + "an arbitrary target that depends on it will be built.")
+  @Option(
+    name = "compile_one_dependency",
+    defaultValue = "false",
+    category = "what",
+    help =
+        "Compile a single dependency of the argument files. This is useful for syntax checking "
+            + "source files in IDEs, for example, by rebuilding a single target that depends on "
+            + "the source file to detect errors as early as possible in the edit/build/test cycle. "
+            + "This argument affects the way all non-flag arguments are interpreted; instead of "
+            + "being targets to build they are source filenames.  For each source filename "
+            + "an arbitrary target that depends on it will be built."
+  )
   public boolean compileOneDependency;
 
-  @Option(name = "build_tag_filters",
-      converter = CommaSeparatedOptionListConverter.class,
-      defaultValue = "",
-      category = "what",
-      help = "Specifies a comma-separated list of tags. Each tag can be optionally "
-          + "preceded with '-' to specify excluded tags. Only those targets will be built that "
-          + "contain at least one included tag and do not contain any excluded tags. This option "
-          + "does not affect the set of tests executed with the 'test' command; those are be "
-          + "governed by the test filtering options, for example '--test_tag_filters'"
-      )
+  @Option(
+    name = "build_tag_filters",
+    converter = CommaSeparatedOptionListConverter.class,
+    defaultValue = "",
+    category = "what",
+    help =
+        "Specifies a comma-separated list of tags. Each tag can be optionally "
+            + "preceded with '-' to specify excluded tags. Only those targets will be built that "
+            + "contain at least one included tag and do not contain any excluded tags. This option "
+            + "does not affect the set of tests executed with the 'test' command; those are be "
+            + "governed by the test filtering options, for example '--test_tag_filters'"
+  )
   public List<String> buildTagFilterList;
 
-  @Option(name = "test_tag_filters",
-      converter = CommaSeparatedOptionListConverter.class,
-      defaultValue = "",
-      category = "what",
-      help = "Specifies a comma-separated list of test tags. Each tag can be optionally " +
-             "preceded with '-' to specify excluded tags. Only those test targets will be " +
-             "found that contain at least one included tag and do not contain any excluded " +
-             "tags. This option affects --build_tests_only behavior and the test command."
-      )
+  @Option(
+    name = "test_tag_filters",
+    converter = CommaSeparatedOptionListConverter.class,
+    defaultValue = "",
+    category = "what",
+    help =
+        "Specifies a comma-separated list of test tags. Each tag can be optionally "
+            + "preceded with '-' to specify excluded tags. Only those test targets will be "
+            + "found that contain at least one included tag and do not contain any excluded "
+            + "tags. This option affects --build_tests_only behavior and the test command."
+  )
   public List<String> testTagFilterList;
 
-  @Option(name = "test_size_filters",
-      converter = TestSize.TestSizeFilterConverter.class,
-      defaultValue = "",
-      category = "what",
-      help = "Specifies a comma-separated list of test sizes. Each size can be optionally " +
-             "preceded with '-' to specify excluded sizes. Only those test targets will be " +
-             "found that contain at least one included size and do not contain any excluded " +
-             "sizes. This option affects --build_tests_only behavior and the test command."
-      )
+  @Option(
+    name = "test_size_filters",
+    converter = TestSize.TestSizeFilterConverter.class,
+    defaultValue = "",
+    category = "what",
+    help =
+        "Specifies a comma-separated list of test sizes. Each size can be optionally "
+            + "preceded with '-' to specify excluded sizes. Only those test targets will be "
+            + "found that contain at least one included size and do not contain any excluded "
+            + "sizes. This option affects --build_tests_only behavior and the test command."
+  )
   public Set<TestSize> testSizeFilterSet;
 
-  @Option(name = "test_timeout_filters",
-      converter = TestTimeout.TestTimeoutFilterConverter.class,
-      defaultValue = "",
-      category = "what",
-      help = "Specifies a comma-separated list of test timeouts. Each timeout can be " +
-             "optionally preceded with '-' to specify excluded timeouts. Only those test " +
-             "targets will be found that contain at least one included timeout and do not " +
-             "contain any excluded timeouts. This option affects --build_tests_only behavior " +
-             "and the test command."
-      )
+  @Option(
+    name = "test_timeout_filters",
+    converter = TestTimeout.TestTimeoutFilterConverter.class,
+    defaultValue = "",
+    category = "what",
+    help =
+        "Specifies a comma-separated list of test timeouts. Each timeout can be "
+            + "optionally preceded with '-' to specify excluded timeouts. Only those test "
+            + "targets will be found that contain at least one included timeout and do not "
+            + "contain any excluded timeouts. This option affects --build_tests_only behavior "
+            + "and the test command."
+  )
   public Set<TestTimeout> testTimeoutFilterSet;
 
-  @Option(name = "test_lang_filters",
-      converter = CommaSeparatedOptionListConverter.class,
-      defaultValue = "",
-      category = "what",
-      help = "Specifies a comma-separated list of test languages. Each language can be " +
-             "optionally preceded with '-' to specify excluded languages. Only those " +
-             "test targets will be found that are written in the specified languages. " +
-             "The name used for each language should be the same as the language prefix in the " +
-             "*_test rule, e.g. one of 'cc', 'java', 'py', etc." +
-             "This option affects --build_tests_only behavior and the test command."
-      )
+  @Option(
+    name = "test_lang_filters",
+    converter = CommaSeparatedOptionListConverter.class,
+    defaultValue = "",
+    category = "what",
+    help =
+        "Specifies a comma-separated list of test languages. Each language can be "
+            + "optionally preceded with '-' to specify excluded languages. Only those "
+            + "test targets will be found that are written in the specified languages. "
+            + "The name used for each language should be the same as the language prefix in the "
+            + "*_test rule, e.g. one of 'cc', 'java', 'py', etc."
+            + "This option affects --build_tests_only behavior and the test command."
+  )
   public List<String> testLangFilterList;
 
-  @Option(name = "build_manual_tests",
-      defaultValue = "false",
-      category = "what",
-      help = "Forces test targets tagged 'manual' to be built. "
-             + "'manual' tests are excluded from processing. This option forces "
-             + "them to be built (but not executed)."
+  @Option(
+    name = "build_manual_tests",
+    defaultValue = "false",
+    category = "what",
+    help =
+        "Forces test targets tagged 'manual' to be built. 'manual' tests are excluded from "
+            + "processing. This option forces them to be built (but not executed)."
   )
   public boolean buildManualTests;
 
@@ -119,10 +135,13 @@ public class LoadingOptions extends OptionsBase {
   // the loading phase at all, and therefore can't currently support the other flag. If we roll this
   // out soonish, then we're never going to implement the legacy code path in the new
   // implementation, making it a moot point.
-  @Option(name = "experimental_skyframe_target_pattern_evaluator",
-      defaultValue = "false",
-      category = "hidden",
-      help = "Use the Skyframe-based target pattern evaluator; implies "
-          + "--experimental_interleave_loading_and_analysis.")
+  @Option(
+    name = "experimental_skyframe_target_pattern_evaluator",
+    defaultValue = "false",
+    optionUsageRestrictions = OptionUsageRestrictions.HIDDEN,
+    help =
+        "Use the Skyframe-based target pattern evaluator; implies "
+            + "--experimental_interleave_loading_and_analysis."
+  )
   public boolean useSkyframeTargetPatternEvaluator;
 }
diff --git a/src/main/java/com/google/devtools/build/lib/pkgcache/PackageCacheOptions.java b/src/main/java/com/google/devtools/build/lib/pkgcache/PackageCacheOptions.java
index 8237e8408f..626d76faa3 100644
--- a/src/main/java/com/google/devtools/build/lib/pkgcache/PackageCacheOptions.java
+++ b/src/main/java/com/google/devtools/build/lib/pkgcache/PackageCacheOptions.java
@@ -26,6 +26,7 @@ import com.google.devtools.common.options.Converter;
 import com.google.devtools.common.options.Converters;
 import com.google.devtools.common.options.Option;
 import com.google.devtools.common.options.OptionsBase;
+import com.google.devtools.common.options.OptionsParser.OptionUsageRestrictions;
 import com.google.devtools.common.options.OptionsParsingException;
 import java.util.List;
 
@@ -56,64 +57,78 @@ public class PackageCacheOptions extends OptionsBase {
     }
   }
 
-  @Option(name = "package_path",
-          defaultValue = "%workspace%",
-          category = "package loading",
-          converter = Converters.ColonSeparatedOptionListConverter.class,
-          help = "A colon-separated list of where to look for packages. "
-          +  "Elements beginning with '%workspace%' are relative to the enclosing "
-          +  "workspace. If omitted or empty, the default is the output of "
-          +  "'blaze info default-package-path'.")
+  @Option(
+    name = "package_path",
+    defaultValue = "%workspace%",
+    category = "package loading",
+    converter = Converters.ColonSeparatedOptionListConverter.class,
+    help =
+        "A colon-separated list of where to look for packages. "
+            + "Elements beginning with '%workspace%' are relative to the enclosing "
+            + "workspace. If omitted or empty, the default is the output of "
+            + "'blaze info default-package-path'."
+  )
   public List<String> packagePath;
 
-  @Option(name = "show_package_location",
-          defaultValue = "false",
-          category = "verbosity",
-          deprecationWarning = "This flag is no longer supported and will go away soon.",
-          help = "If enabled, causes Blaze to print the location on the --package_path "
-          + "from which each package was loaded.")
+  @Option(
+    name = "show_package_location",
+    defaultValue = "false",
+    category = "verbosity",
+    deprecationWarning = "This flag is no longer supported and will go away soon.",
+    help =
+        "If enabled, causes Blaze to print the location on the --package_path "
+            + "from which each package was loaded."
+  )
   public boolean showPackageLocation;
 
-  @Option(name = "show_loading_progress",
-          defaultValue = "true",
-          category = "verbosity",
-          help = "If enabled, causes Blaze to print \"Loading package:\" messages.")
+  @Option(
+    name = "show_loading_progress",
+    defaultValue = "true",
+    category = "verbosity",
+    help = "If enabled, causes Blaze to print \"Loading package:\" messages."
+  )
   public boolean showLoadingProgress;
 
-  @Option(name = "deleted_packages",
-          defaultValue = "",
-          category = "package loading",
-          converter = CommaSeparatedPackageNameListConverter.class,
-          help = "A comma-separated list of names of packages which the "
-          + "build system will consider non-existent, even if they are "
-          + "visible somewhere on the package path."
-          + "\n"
-          + "Use this option when deleting a subpackage 'x/y' of an "
-          + "existing package 'x'.  For example, after deleting x/y/BUILD "
-          + "in your client, the build system may complain if it "
-          + "encounters a label '//x:y/z' if that is still provided by another "
-          + "package_path entry.  Specifying --deleted_packages x/y avoids this "
-          + "problem.")
+  @Option(
+    name = "deleted_packages",
+    defaultValue = "",
+    category = "package loading",
+    converter = CommaSeparatedPackageNameListConverter.class,
+    help =
+        "A comma-separated list of names of packages which the "
+            + "build system will consider non-existent, even if they are "
+            + "visible somewhere on the package path.\n"
+            + "Use this option when deleting a subpackage 'x/y' of an "
+            + "existing package 'x'.  For example, after deleting x/y/BUILD "
+            + "in your client, the build system may complain if it "
+            + "encounters a label '//x:y/z' if that is still provided by another "
+            + "package_path entry.  Specifying --deleted_packages x/y avoids this "
+            + "problem."
+  )
   public List<PackageIdentifier> deletedPackages;
 
-  @Option(name = "default_visibility",
-      defaultValue = "private",
-      category = "undocumented",
-      converter = DefaultVisibilityConverter.class,
-      help = "Default visibility for packages that don't set it explicitly ('public' or "
-          + "'private').")
+  @Option(
+    name = "default_visibility",
+    defaultValue = "private",
+    optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED,
+    converter = DefaultVisibilityConverter.class,
+    help =
+        "Default visibility for packages that don't set it explicitly ('public' or " + "'private')."
+  )
   public RuleVisibility defaultVisibility;
 
-  @Option(name = "legacy_globbing_threads",
-      defaultValue = "100",
-      category = "undocumented",
-      help = "Number of threads to use for glob evaluation.")
+  @Option(
+    name = "legacy_globbing_threads",
+    defaultValue = "100",
+    optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED,
+    help = "Number of threads to use for glob evaluation."
+  )
   public int globbingThreads;
 
   @Option(
     name = "experimental_max_directories_to_eagerly_visit_in_globbing",
     defaultValue = "-1",
-    category = "undocumented",
+    optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED,
     help =
         "If non-negative, the first time a glob is evaluated in a package, the subdirectories of "
             + "the package will be traversed in order to warm filesystem caches and compensate for "
@@ -121,17 +136,22 @@ public class PackageCacheOptions extends OptionsBase {
   )
   public int maxDirectoriesToEagerlyVisitInGlobbing;
 
-  @Option(name = "fetch",
-      defaultValue = "true",
-      category = "undocumented",
-      help = "Allows the command to fetch external dependencies")
+  @Option(
+    name = "fetch",
+    defaultValue = "true",
+    optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED,
+    help = "Allows the command to fetch external dependencies"
+  )
   public boolean fetch;
 
-  @Option(name = "experimental_check_output_files",
-        defaultValue = "true",
-        category = "undocumented",
-        help = "Check for modifications made to the output files of a build. Consider setting "
-            + "this flag to false to see the effect on incremental build times.")
+  @Option(
+    name = "experimental_check_output_files",
+    defaultValue = "true",
+    optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED,
+    help =
+        "Check for modifications made to the output files of a build. Consider setting "
+            + "this flag to false to see the effect on incremental build times."
+  )
   public boolean checkOutputFiles;
 
   /**
diff --git a/src/main/java/com/google/devtools/build/lib/query2/output/QueryOptions.java b/src/main/java/com/google/devtools/build/lib/query2/output/QueryOptions.java
index e17fa48a90..34ba0d40f9 100644
--- a/src/main/java/com/google/devtools/build/lib/query2/output/QueryOptions.java
+++ b/src/main/java/com/google/devtools/build/lib/query2/output/QueryOptions.java
@@ -18,6 +18,7 @@ import com.google.devtools.common.options.Converters;
 import com.google.devtools.common.options.EnumConverter;
 import com.google.devtools.common.options.Option;
 import com.google.devtools.common.options.OptionsBase;
+import com.google.devtools.common.options.OptionsParser.OptionUsageRestrictions;
 import java.util.EnumSet;
 import java.util.List;
 import java.util.Set;
@@ -40,12 +41,14 @@ public class QueryOptions extends OptionsBase {
     }
   }
 
-  @Option(name = "output",
-      defaultValue = "label",
-      category = "query",
-      help = "The format in which the query results should be printed."
-          + " Allowed values are: label, label_kind, minrank, maxrank, package, location, graph,"
-          + " xml, proto, record.")
+  @Option(
+    name = "output",
+    defaultValue = "label",
+    category = "query",
+    help =
+        "The format in which the query results should be printed. Allowed values are: "
+            + "label, label_kind, minrank, maxrank, package, location, graph, xml, proto, record."
+  )
   public String outputFormat;
 
   @Option(
@@ -114,121 +117,154 @@ public class QueryOptions extends OptionsBase {
   )
   public OrderOutput orderOutput;
 
-  @Option(name = "keep_going",
-      abbrev = 'k',
-      defaultValue = "false",
-      category = "strategy",
-      help = "Continue as much as possible after an error.  While the "
-          + "target that failed, and those that depend on it, cannot be "
-          + "analyzed, other prerequisites of these "
-          + "targets can be.")
+  @Option(
+    name = "keep_going",
+    abbrev = 'k',
+    defaultValue = "false",
+    category = "strategy",
+    help =
+        "Continue as much as possible after an error. While the target that failed, and those "
+            + "that depend on it, cannot be analyzed, other prerequisites of these targets can be."
+  )
   public boolean keepGoing;
 
-  @Option(name = "loading_phase_threads",
-      defaultValue = "200",
-      category = "undocumented",
-      help = "Number of parallel threads to use for the loading phase.")
+  @Option(
+    name = "loading_phase_threads",
+    defaultValue = "200",
+    optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED,
+    help = "Number of parallel threads to use for the loading phase."
+  )
   public int loadingPhaseThreads;
 
-  @Option(name = "host_deps",
-      defaultValue = "true",
-      category = "query",
-          help = "If enabled, dependencies on 'host configuration' targets will be included in "
-          + "the dependency graph over which the query operates.  A 'host configuration' "
-          + "dependency edge, such as the one from any 'proto_library' rule to the Protocol "
-          + "Compiler, usually points to a tool executed during the build (on the host machine) "
-          + "rather than a part of the same 'target' program.  Queries whose purpose is to "
-          + "discover the set of things needed during a build will typically enable this option; "
-          + "queries aimed at revealing the structure of a single program will typically  disable "
-          + "this option.")
+  @Option(
+    name = "host_deps",
+    defaultValue = "true",
+    category = "query",
+    help =
+        "If enabled, dependencies on 'host configuration' targets will be included in the "
+            + "dependency graph over which the query operates.  A 'host configuration' dependency "
+            + "edge, such as the one from any 'proto_library' rule to the Protocol Compiler, "
+            + "usually points to a tool executed during the build (on the host machine) rather "
+            + "than a part of the same 'target' program.  Queries whose purpose is to discover "
+            + "the set of things needed during a build will typically enable this option; queries "
+            + "aimed at revealing the structure of a single program will typically disable this "
+            + "option."
+  )
   public boolean includeHostDeps;
 
-  @Option(name = "implicit_deps",
-      defaultValue = "true",
-      category = "query",
-      help = "If enabled, implicit dependencies will be included in the dependency graph over "
-          + "which the query operates. An implicit dependency is one that is not explicitly "
-          + "specified in the BUILD file but added by blaze.")
+  @Option(
+    name = "implicit_deps",
+    defaultValue = "true",
+    category = "query",
+    help =
+        "If enabled, implicit dependencies will be included in the dependency graph over "
+            + "which the query operates. An implicit dependency is one that is not explicitly "
+            + "specified in the BUILD file but added by blaze."
+  )
   public boolean includeImplicitDeps;
 
-  @Option(name = "graph:node_limit",
-      defaultValue = "512",
-      category = "query",
-      help = "The maximum length of the label string for a graph node in the output.  Longer labels"
-           + " will be truncated; -1 means no truncation.  This option is only applicable to"
-           + " --output=graph.")
+  @Option(
+    name = "graph:node_limit",
+    defaultValue = "512",
+    category = "query",
+    help =
+        "The maximum length of the label string for a graph node in the output.  Longer labels"
+            + " will be truncated; -1 means no truncation.  This option is only applicable to"
+            + " --output=graph."
+  )
   public int graphNodeStringLimit;
 
-  @Option(name = "graph:factored",
-      defaultValue = "true",
-      category = "query",
-      help = "If true, then the graph will be emitted 'factored', i.e. "
-          + "topologically-equivalent nodes will be merged together and their "
-          + "labels concatenated.    This option is only applicable to "
-          + "--output=graph.")
+  @Option(
+    name = "graph:factored",
+    defaultValue = "true",
+    category = "query",
+    help =
+        "If true, then the graph will be emitted 'factored', i.e. topologically-equivalent nodes "
+            + "will be merged together and their labels concatenated. This option is only "
+            + "applicable to --output=graph."
+  )
   public boolean graphFactored;
 
-  @Option(name = "proto:default_values",
-      defaultValue = "true",
-      category = "query",
-      help = "If true, attributes whose value is not explicitly specified "
-          + "in the BUILD file are included; otherwise they are omitted. "
-          + "This option is applicable to --output=proto")
+  @Option(
+    name = "proto:default_values",
+    defaultValue = "true",
+    category = "query",
+    help =
+        "If true, attributes whose value is not explicitly specified in the BUILD file are "
+            + "included; otherwise they are omitted. This option is applicable to --output=proto"
+  )
   public boolean protoIncludeDefaultValues;
 
-  @Option(name = "xml:line_numbers",
-      defaultValue = "true",
-      category = "query",
-      help = "If true, XML output contains line numbers.  Disabling this option "
-          + "may make diffs easier to read.  This option is only applicable to "
-          + "--output=xml.")
+  @Option(
+    name = "xml:line_numbers",
+    defaultValue = "true",
+    category = "query",
+    help =
+        "If true, XML output contains line numbers. Disabling this option may make diffs easier "
+            + "to read.  This option is only applicable to --output=xml."
+  )
   public boolean xmlLineNumbers;
 
-  @Option(name = "xml:default_values",
-      defaultValue = "false",
-      category = "query",
-      help = "If true, rule attributes whose value is not explicitly specified "
-          + "in the BUILD file are printed; otherwise they are omitted.")
+  @Option(
+    name = "xml:default_values",
+    defaultValue = "false",
+    category = "query",
+    help =
+        "If true, rule attributes whose value is not explicitly specified in the BUILD file are "
+            + "printed; otherwise they are omitted."
+  )
   public boolean xmlShowDefaultValues;
 
-  @Option(name = "strict_test_suite",
-      defaultValue = "false",
-      category = "query",
-      help = "If true, the tests() expression gives an error if it encounters a test_suite "
-          + "containing non-test targets.")
+  @Option(
+    name = "strict_test_suite",
+    defaultValue = "false",
+    category = "query",
+    help =
+        "If true, the tests() expression gives an error if it encounters a test_suite containing "
+            + "non-test targets."
+  )
   public boolean strictTestSuite;
 
-  @Option(name = "universe_scope",
-      converter = Converters.CommaSeparatedOptionListConverter.class,
-      defaultValue = "",
-      category = "query",
-      help = "A comma-separated set of target patterns (additive and subtractive). The query may "
-          + "be performed in the universe defined by the transitive closure of the specified "
-          + "targets.")
+  @Option(
+    name = "universe_scope",
+    converter = Converters.CommaSeparatedOptionListConverter.class,
+    defaultValue = "",
+    category = "query",
+    help =
+        "A comma-separated set of target patterns (additive and subtractive). The query may "
+            + "be performed in the universe defined by the transitive closure of the specified "
+            + "targets."
+  )
   public List<String> universeScope;
 
-  @Option(name = "relative_locations",
-      defaultValue = "false",
-      category = "query",
-      help = "If true, the location of BUILD files in xml and proto outputs will be relative. "
-        + "By default, the location output is an absolute path and will not be consistent "
-        + "across machines. You can set this option to true to have a consistent result "
-        + "across machines.")
+  @Option(
+    name = "relative_locations",
+    defaultValue = "false",
+    category = "query",
+    help =
+        "If true, the location of BUILD files in xml and proto outputs will be relative. "
+            + "By default, the location output is an absolute path and will not be consistent "
+            + "across machines. You can set this option to true to have a consistent result "
+            + "across machines."
+  )
   public boolean relativeLocations;
 
-  @Option(name = "aspect_deps",
-      converter = AspectResolutionModeConverter.class,
-      defaultValue = "conservative",
-      category = "query",
-      help = "How to resolve aspect dependencies when the output format is one of "
-          + "{xml,proto,record}. 'off' means no aspect dependencies are resolved, 'conservative' "
-          + "(the default) means all declared aspect dependencies are added regardless of whether "
-          + "they are viable given the rule class of direct dependencies, 'precise' means that "
-          + "only those aspects are added that are possibly active given the rule class of the "
-          + "direct dependencies. Note that precise mode requires loading other packages to "
-          + "evaluate a single target thus making it slower than the other modes. Also note that "
-          + "even precise mode is not completely precise: the decision whether to compute an "
-          + "aspect is decided in the analysis phase, which is not run during 'blaze query'.")
+  @Option(
+    name = "aspect_deps",
+    converter = AspectResolutionModeConverter.class,
+    defaultValue = "conservative",
+    category = "query",
+    help =
+        "How to resolve aspect dependencies when the output format is one of {xml,proto,record}. "
+            + "'off' means no aspect dependencies are resolved, 'conservative' (the default) means "
+            + "all declared aspect dependencies are added regardless of whether they are viable "
+            + "given the rule class of direct dependencies, 'precise' means that only those "
+            + "aspects are added that are possibly active given the rule class of the direct "
+            + "dependencies. Note that precise mode requires loading other packages to evaluate "
+            + "a single target thus making it slower than the other modes. Also note that even "
+            + "precise mode is not completely precise: the decision whether to compute an aspect "
+            + "is decided in the analysis phase, which is not run during 'blaze query'."
+  )
   public AspectResolver.Mode aspectDeps;
 
   @Option(
@@ -236,8 +272,8 @@ public class QueryOptions extends OptionsBase {
     defaultValue = "",
     category = "query",
     help =
-        "If set, query will read the query from the file named here, rather than on the "
-            + "command line. It is an error to specify a file here as well as a command-line query."
+        "If set, query will read the query from the file named here, rather than on the command "
+            + "line. It is an error to specify a file here as well as a command-line query."
   )
   public String queryFile;
   
diff --git a/src/main/java/com/google/devtools/build/lib/rules/android/AndroidConfiguration.java b/src/main/java/com/google/devtools/build/lib/rules/android/AndroidConfiguration.java
index b7e543e83a..3cfa842f9f 100644
--- a/src/main/java/com/google/devtools/build/lib/rules/android/AndroidConfiguration.java
+++ b/src/main/java/com/google/devtools/build/lib/rules/android/AndroidConfiguration.java
@@ -36,6 +36,7 @@ import com.google.devtools.common.options.Converter;
 import com.google.devtools.common.options.Converters;
 import com.google.devtools.common.options.EnumConverter;
 import com.google.devtools.common.options.Option;
+import com.google.devtools.common.options.OptionsParser.OptionUsageRestrictions;
 import com.google.devtools.common.options.OptionsParsingException;
 import java.util.List;
 import java.util.Set;
@@ -189,35 +190,41 @@ public class AndroidConfiguration extends BuildConfiguration.Fragment {
     }
   }
 
-  /**
-   * Android configuration options.
-   */
+  /** Android configuration options. */
   public static class Options extends FragmentOptions {
-    @Option(name = "Android configuration distinguisher",
-        defaultValue = "MAIN",
-        converter = ConfigurationDistinguisherConverter.class,
-        category = "internal")
+    @Option(
+      name = "Android configuration distinguisher",
+      defaultValue = "MAIN",
+      converter = ConfigurationDistinguisherConverter.class,
+      optionUsageRestrictions = OptionUsageRestrictions.INTERNAL
+    )
     public ConfigurationDistinguisher configurationDistinguisher;
 
     // For deploying incremental installation of native libraries. Do not use on the command line.
     // The idea is that once this option works, we'll flip the default value in a config file, then
     // once it is proven that it works, remove it from Bazel and said config file.
-    @Option(name = "android_incremental_native_libs",
-        defaultValue = "false",
-        category = "undocumented")
+    @Option(
+      name = "android_incremental_native_libs",
+      defaultValue = "false",
+      optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED
+    )
     public boolean incrementalNativeLibs;
 
-    @Option(name = "android_crosstool_top",
-        defaultValue = "//external:android/crosstool",
-        category = "semantics",
-        converter = EmptyToNullLabelConverter.class,
-        help = "The location of the C++ compiler used for Android builds.")
+    @Option(
+      name = "android_crosstool_top",
+      defaultValue = "//external:android/crosstool",
+      category = "semantics",
+      converter = EmptyToNullLabelConverter.class,
+      help = "The location of the C++ compiler used for Android builds."
+    )
     public Label androidCrosstoolTop;
 
-    @Option(name = "android_cpu",
-        defaultValue = "armeabi",
-        category = "semantics",
-        help = "The Android target CPU.")
+    @Option(
+      name = "android_cpu",
+      defaultValue = "armeabi",
+      category = "semantics",
+      help = "The Android target CPU."
+    )
     public String cpu;
 
     @Option(
@@ -232,79 +239,94 @@ public class AndroidConfiguration extends BuildConfiguration.Fragment {
       name = "android_dynamic_mode",
       defaultValue = "off",
       converter = DynamicModeConverter.class,
-      category = "undocumented",
+      optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED,
       help =
-        "Determines whether C++ deps of Android rules will be linked dynamically when a cc_binary "
-            + "does not explicitly create a shared library. 'default' means blaze will choose "
-            + "whether to link dynamically.  'fully' means all libraries will be linked "
-            + "dynamically. 'off' means that all libraries will be linked in mostly static mode."
+          "Determines whether C++ deps of Android rules will be linked dynamically when a "
+              + "cc_binary does not explicitly create a shared library. "
+              + "'default' means blaze will choose whether to link dynamically.  "
+              + "'fully' means all libraries will be linked dynamically. "
+              + "'off' means that all libraries will be linked in mostly static mode."
     )
     public DynamicMode dynamicMode;
 
     // Label of filegroup combining all Android tools used as implicit dependencies of
     // android_* rules
-    @Option(name = "android_sdk",
-            defaultValue = "@bazel_tools//tools/android:sdk",
-            category = "version",
-            converter = LabelConverter.class,
-            help = "Specifies Android SDK/platform that is used to build Android applications.")
+    @Option(
+      name = "android_sdk",
+      defaultValue = "@bazel_tools//tools/android:sdk",
+      category = "version",
+      converter = LabelConverter.class,
+      help = "Specifies Android SDK/platform that is used to build Android applications."
+    )
     public Label sdk;
 
     // TODO(bazel-team): Maybe merge this with --android_cpu above.
-    @Option(name = "fat_apk_cpu",
-            converter = Converters.CommaSeparatedOptionListConverter.class,
-            defaultValue = "armeabi-v7a",
-            category = "semantics",
-            help = "Setting this option enables fat APKs, which contain native binaries for all "
-                + "specified target architectures, e.g., --fat_apk_cpu=x86,armeabi-v7a. If this "
-                + "flag is specified, then --android_cpu is ignored for dependencies of "
-                + "android_binary rules.")
+    @Option(
+      name = "fat_apk_cpu",
+      converter = Converters.CommaSeparatedOptionListConverter.class,
+      defaultValue = "armeabi-v7a",
+      category = "semantics",
+      help =
+          "Setting this option enables fat APKs, which contain native binaries for all "
+              + "specified target architectures, e.g., --fat_apk_cpu=x86,armeabi-v7a. If this "
+              + "flag is specified, then --android_cpu is ignored for dependencies of "
+              + "android_binary rules."
+    )
     public List<String> fatApkCpus;
 
     // For desugaring lambdas when compiling Java 8 sources. Do not use on the command line.
     // The idea is that once this option works, we'll flip the default value in a config file, then
     // once it is proven that it works, remove it from Bazel and said config file.
-    @Option(name = "experimental_desugar_for_android",
-        defaultValue = "false",
-        category = "undocumented",
-        help = "Whether to desugar Java 8 bytecode before dexing.")
+    @Option(
+      name = "experimental_desugar_for_android",
+      defaultValue = "false",
+      optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED,
+      help = "Whether to desugar Java 8 bytecode before dexing."
+    )
     public boolean desugarJava8;
 
-    @Option(name = "incremental_dexing",
-        defaultValue = "false",
-        category = "semantics",
-        help = "Does most of the work for dexing separately for each Jar file.")
+    @Option(
+      name = "incremental_dexing",
+      defaultValue = "false",
+      category = "semantics",
+      help = "Does most of the work for dexing separately for each Jar file."
+    )
     public boolean incrementalDexing;
 
     // TODO(b/31711689): remove this flag from config files and here
-    @Option(name = "host_incremental_dexing",
-        defaultValue = "false",
-        category = "hidden",
-        help = "This flag is deprecated in favor of applying --incremental_dexing to both host "
-            + "and target configuration.  This flag will be removed in a future release.")
+    @Option(
+      name = "host_incremental_dexing",
+      defaultValue = "false",
+      optionUsageRestrictions = OptionUsageRestrictions.HIDDEN,
+      help =
+          "This flag is deprecated in favor of applying --incremental_dexing to both host "
+              + "and target configuration.  This flag will be removed in a future release."
+    )
     public boolean hostIncrementalDexing;
 
     // Do not use on the command line.
     // The idea is that this option lets us gradually turn on incremental dexing for different
     // binaries.  Users should rely on --noincremental_dexing to turn it off.
     // TODO(b/31711689): remove this flag from config files and here
-    @Option(name = "incremental_dexing_binary_types",
-        defaultValue = "all",
-        category = "undocumented",
-        converter = AndroidBinaryTypesConverter.class,
-        implicitRequirements = "--incremental_dexing",
-        help = "Kinds of binaries to incrementally dex if --incremental_dexing is true.")
+    @Option(
+      name = "incremental_dexing_binary_types",
+      defaultValue = "all",
+      optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED,
+      converter = AndroidBinaryTypesConverter.class,
+      implicitRequirements = "--incremental_dexing",
+      help = "Kinds of binaries to incrementally dex if --incremental_dexing is true."
+    )
     public Set<AndroidBinaryType> incrementalDexingBinaries;
 
-    /**
-     * Whether to look for incrementally dex protos built with java_lite_proto_library.
-     */
+    /** Whether to look for incrementally dex protos built with java_lite_proto_library. */
     // TODO(b/31711689): remove this flag from config files and here
     @Option(
       name = "experimental_incremental_dexing_for_lite_protos",
       defaultValue = "true",
       category = "experimental",
-      help = "Do not use.")
+      optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED,
+      help = "Do not use."
+    )
     public boolean incrementalDexingForLiteProtos;
 
     /**
@@ -315,142 +337,181 @@ public class AndroidConfiguration extends BuildConfiguration.Fragment {
       name = "experimental_incremental_dexing_error_on_missed_jars",
       defaultValue = "true",
       category = "experimental",
-      help = "Do not use.")
+      optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED,
+      help = "Do not use."
+    )
     public boolean incrementalDexingErrorOnMissedJars;
 
     // Do not use on the command line.
     // This flag is intended to be updated as we add supported flags to the incremental dexing tools
-    @Option(name = "non_incremental_per_target_dexopts",
-        converter = Converters.CommaSeparatedOptionListConverter.class,
-        defaultValue = "--positions",
-        category = "semantics",
-        help = "dx flags that that prevent incremental dexing for binary targets that list any of "
-            + "the flags listed here in their 'dexopts' attribute, which are ignored with "
-            + "incremental dexing (superseding --dexopts_supported_in_incremental_dexing).  "
-            + "Defaults to --no-locals for safety but can in general be used "
-            + "to make sure the listed dx flags are honored, with additional build latency.  "
-            + "Please notify us if you find yourself needing this flag.")
+    @Option(
+      name = "non_incremental_per_target_dexopts",
+      converter = Converters.CommaSeparatedOptionListConverter.class,
+      defaultValue = "--positions",
+      category = "semantics",
+      optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED,
+      help =
+          "dx flags that that prevent incremental dexing for binary targets that list any of "
+              + "the flags listed here in their 'dexopts' attribute, which are ignored with "
+              + "incremental dexing (superseding --dexopts_supported_in_incremental_dexing).  "
+              + "Defaults to --no-locals for safety but can in general be used "
+              + "to make sure the listed dx flags are honored, with additional build latency.  "
+              + "Please notify us if you find yourself needing this flag."
+    )
     public List<String> nonIncrementalPerTargetDexopts;
 
     // Do not use on the command line.
     // This flag is intended to be updated as we add supported flags to the incremental dexing tools
-    @Option(name = "dexopts_supported_in_incremental_dexing",
-        converter = Converters.CommaSeparatedOptionListConverter.class,
-        defaultValue = "--no-optimize,--no-locals",
-        category = "hidden",
-        help = "dx flags supported when converting Jars to dex archives incrementally.")
+    @Option(
+      name = "dexopts_supported_in_incremental_dexing",
+      converter = Converters.CommaSeparatedOptionListConverter.class,
+      defaultValue = "--no-optimize,--no-locals",
+      optionUsageRestrictions = OptionUsageRestrictions.HIDDEN,
+      help = "dx flags supported when converting Jars to dex archives incrementally."
+    )
     public List<String> dexoptsSupportedInIncrementalDexing;
 
     // Do not use on the command line.
     // This flag is intended to be updated as we add supported flags to the incremental dexing tools
     // TODO(b/31711689): remove --no-optimize and --no-locals as DexFileMerger no longer needs them
-    @Option(name = "dexopts_supported_in_dexmerger",
-        converter = Converters.CommaSeparatedOptionListConverter.class,
-        defaultValue = "--no-optimize,--no-locals,--minimal-main-dex,--set-max-idx-number",
-        category = "hidden",
-        help = "dx flags supported in tool that merges dex archives into final classes.dex files.")
+    @Option(
+      name = "dexopts_supported_in_dexmerger",
+      converter = Converters.CommaSeparatedOptionListConverter.class,
+      defaultValue = "--no-optimize,--no-locals,--minimal-main-dex,--set-max-idx-number",
+      optionUsageRestrictions = OptionUsageRestrictions.HIDDEN,
+      help = "dx flags supported in tool that merges dex archives into final classes.dex files."
+    )
     public List<String> dexoptsSupportedInDexMerger;
 
     @Option(
       name = "experimental_android_rewrite_dexes_with_rex",
       defaultValue = "false",
-      category = "undocumented",
+      optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED,
       help = "use rex tool to rewrite dex files"
     )
     public boolean useRexToCompressDexFiles;
 
-    @Option(name = "experimental_allow_android_library_deps_without_srcs",
-        defaultValue = "true",
-        category = "undocumented",
-        help = "Flag to help transition from allowing to disallowing srcs-less android_library"
-            + " rules with deps. The depot needs to be cleaned up to roll this out by default.")
+    @Option(
+      name = "experimental_allow_android_library_deps_without_srcs",
+      defaultValue = "true",
+      optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED,
+      help =
+          "Flag to help transition from allowing to disallowing srcs-less android_library"
+              + " rules with deps. The depot needs to be cleaned up to roll this out by default."
+    )
     public boolean allowAndroidLibraryDepsWithoutSrcs;
 
-    @Option(name = "experimental_android_resource_shrinking",
-        defaultValue = "false",
-        category = "undocumented",
-        help = "Enables resource shrinking for android_binary APKs that use ProGuard.")
+    @Option(
+      name = "experimental_android_resource_shrinking",
+      defaultValue = "false",
+      optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED,
+      help = "Enables resource shrinking for android_binary APKs that use ProGuard."
+    )
     public boolean useExperimentalAndroidResourceShrinking;
 
-    @Option(name = "android_resource_shrinking",
-        defaultValue = "false",
-        category = "semantics",
-        help = "Enables resource shrinking for android_binary APKs that use ProGuard.")
+    @Option(
+      name = "android_resource_shrinking",
+      defaultValue = "false",
+      category = "semantics",
+      help = "Enables resource shrinking for android_binary APKs that use ProGuard."
+    )
     public boolean useAndroidResourceShrinking;
 
-    @Option(name = "android_manifest_merger",
-        defaultValue = "android",
-        category = "semantics",
-        converter = AndroidManifestMergerConverter.class,
-        help = "Selects the manifest merger to use for android_binary rules. Flag to help the"
-            + "transition to the Android manifest merger from the legacy merger.")
+    @Option(
+      name = "android_manifest_merger",
+      defaultValue = "android",
+      category = "semantics",
+      converter = AndroidManifestMergerConverter.class,
+      help =
+          "Selects the manifest merger to use for android_binary rules. Flag to help the"
+              + "transition to the Android manifest merger from the legacy merger."
+    )
     public AndroidManifestMerger manifestMerger;
 
     // Do not use on the command line.
-    @Option(name = "experimental_use_parallel_android_resource_processing",
+    @Option(
+      name = "experimental_use_parallel_android_resource_processing",
       defaultValue = "true",
-      category = "undocumented",
-      help = "Process android_library resources with higher parallelism. Generates library "
-              + "R classes from a merge action, separately from aapt.")
+      optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED,
+      help =
+          "Process android_library resources with higher parallelism. Generates library "
+              + "R classes from a merge action, separately from aapt."
+    )
     public boolean useParallelResourceProcessing;
 
-    @Option(name = "apk_signing_method",
-        converter = ApkSigningMethodConverter.class,
-        defaultValue = "v1_v2",
-        category = "undocumented",
-        help = "Implementation to use to sign APKs")
+    @Option(
+      name = "apk_signing_method",
+      converter = ApkSigningMethodConverter.class,
+      defaultValue = "v1_v2",
+      optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED,
+      help = "Implementation to use to sign APKs"
+    )
     public ApkSigningMethod apkSigningMethod;
 
-    @Option(name = "use_singlejar_apkbuilder",
-        defaultValue = "true",
-        category = "undocumented",
-        help = "Build Android APKs with SingleJar.")
+    @Option(
+      name = "use_singlejar_apkbuilder",
+      defaultValue = "true",
+      optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED,
+      help = "Build Android APKs with SingleJar."
+    )
     public boolean useSingleJarApkBuilder;
 
-    @Option(name = "experimental_android_use_singlejar_for_multidex",
-        defaultValue = "true",
-        category = "undocumented",
-        help = "Use SingleJar for multidex dex extraction.")
+    @Option(
+      name = "experimental_android_use_singlejar_for_multidex",
+      defaultValue = "true",
+      optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED,
+      help = "Use SingleJar for multidex dex extraction."
+    )
     public boolean useSingleJarForMultidex;
 
-    @Option(name = "experimental_android_resource_filtering_method",
+    @Option(
+      name = "experimental_android_resource_filtering_method",
       converter = ResourceFilter.Converter.class,
       defaultValue = "filter_in_execution",
-      category = "undocumented",
-      help = "Determines when resource filtering attributes, such as the android_binary "
-          + "'resource_configuration_filters' and 'densities' attributes, are applied. By default, "
-          + "bazel will 'filter_in_execution'. The experimental 'filter_in_analysis' option "
-          + "instead applies these filters earlier in the build process, with corresponding gains "
-          + "in speed. The experimental 'filter_in_analysis_with_dynamic_configuration' option "
-          + "also passes these options to the android_binary's dependencies, which also filter "
-          + "their internal resources in analysis, possibly making the build even faster "
-          + "(especially in systems that do not cache the results of those dependencies)."
+      optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED,
+      help =
+          "Determines when resource filtering attributes, such as the android_binary "
+              + "'resource_configuration_filters' and 'densities' attributes, are applied. "
+              + "By default, bazel will 'filter_in_execution'. The experimental "
+              + "'filter_in_analysis' option instead applies these filters earlier in the build "
+              + "process, with corresponding gains in speed. The experimental "
+              + "'filter_in_analysis_with_dynamic_configuration' option also passes these options "
+              + "to the android_binary's dependencies, which also filter their internal resources "
+              + "in analysis, possibly making the build even faster (especially in systems that "
+              + "do not cache the results of those dependencies)."
     )
     // The ResourceFilter object holds the filtering behavior as well as settings for which
     // resources should be filtered. The filtering behavior is set from the command line, but the
     // other settings default to empty and are set or modified via dynamic configuration.
     public ResourceFilter resourceFilter;
 
-    @Option(name = "use_singlejar_for_proguard_libraryjars",
-        defaultValue = "false",
-        category = "undocumented",
-        help = "Use SingleJar to combine all ProGuard library jars.")
+    @Option(
+      name = "use_singlejar_for_proguard_libraryjars",
+      defaultValue = "false",
+      optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED,
+      help = "Use SingleJar to combine all ProGuard library jars."
+    )
     public boolean useSingleJarForProguardLibraryJars;
 
-    @Option(name = "experimental_android_compress_java_resources",
-        defaultValue = "false",
-        category = "undocumented",
-        implicitRequirements = "--use_singlejar_apkbuilder",
-        help = "Compress Java resources in APKs")
+    @Option(
+      name = "experimental_android_compress_java_resources",
+      defaultValue = "false",
+      optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED,
+      implicitRequirements = "--use_singlejar_apkbuilder",
+      help = "Compress Java resources in APKs"
+    )
     public boolean compressJavaResources;
 
-    @Option(name = "experimental_android_include_library_resource_jars",
-        defaultValue = "true",
-        category = "undocumented",
-        help = "Specifies whether resource JAR files for android_library targets should be included"
-            + " as runtime dependencies. Defaults to the old behavior, including them. These JARs"
-            + " are not nessecary for normal use as all required resources are included in the"
-            + " top-level android_binary resource JAR.")
+    @Option(
+      name = "experimental_android_include_library_resource_jars",
+      defaultValue = "true",
+      optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED,
+      help =
+          "Specifies whether resource JAR files for android_library targets should be included"
+              + " as runtime dependencies. Defaults to the old behavior, including them. These JARs"
+              + " are not nessecary for normal use as all required resources are included in the"
+              + " top-level android_binary resource JAR."
+    )
     public boolean includeLibraryResourceJars;
 
     @Override
diff --git a/src/main/java/com/google/devtools/build/lib/rules/apple/AppleCommandLineOptions.java b/src/main/java/com/google/devtools/build/lib/rules/apple/AppleCommandLineOptions.java
index f588ff50e6..23977e16b0 100644
--- a/src/main/java/com/google/devtools/build/lib/rules/apple/AppleCommandLineOptions.java
+++ b/src/main/java/com/google/devtools/build/lib/rules/apple/AppleCommandLineOptions.java
@@ -30,6 +30,7 @@ import com.google.devtools.build.lib.skylarkinterface.SkylarkModuleCategory;
 import com.google.devtools.common.options.Converters.CommaSeparatedOptionListConverter;
 import com.google.devtools.common.options.EnumConverter;
 import com.google.devtools.common.options.Option;
+import com.google.devtools.common.options.OptionsParser.OptionUsageRestrictions;
 import java.util.List;
 
 /**
@@ -91,38 +92,38 @@ public class AppleCommandLineOptions extends FragmentOptions {
   public DottedVersion macOsSdkVersion;
 
   @Option(
-      name = "ios_minimum_os",
-      defaultValue = DEFAULT_MINIMUM_IOS,
-      category = "flags",
-      converter = DottedVersionConverter.class,
-      help = "Minimum compatible iOS version for target simulators and devices."
+    name = "ios_minimum_os",
+    defaultValue = DEFAULT_MINIMUM_IOS,
+    category = "flags",
+    converter = DottedVersionConverter.class,
+    help = "Minimum compatible iOS version for target simulators and devices."
   )
   public DottedVersion iosMinimumOs;
 
   @Option(
-      name = "watchos_minimum_os",
-      defaultValue = "null",
-      category = "flags",
-      converter = DottedVersionConverter.class,
-      help = "Minimum compatible watchOS version for target simulators and devices."
+    name = "watchos_minimum_os",
+    defaultValue = "null",
+    category = "flags",
+    converter = DottedVersionConverter.class,
+    help = "Minimum compatible watchOS version for target simulators and devices."
   )
   public DottedVersion watchosMinimumOs;
 
   @Option(
-      name = "tvos_minimum_os",
-      defaultValue = "null",
-      category = "flags",
-      converter = DottedVersionConverter.class,
-      help = "Minimum compatible tvOS version for target simulators and devices."
+    name = "tvos_minimum_os",
+    defaultValue = "null",
+    category = "flags",
+    converter = DottedVersionConverter.class,
+    help = "Minimum compatible tvOS version for target simulators and devices."
   )
   public DottedVersion tvosMinimumOs;
 
   @Option(
-      name = "macos_minimum_os",
-      defaultValue = DEFAULT_MINIMUM_MACOS,
-      category = "flags",
-      converter = DottedVersionConverter.class,
-      help = "Minimum compatible macOS version for targets."
+    name = "macos_minimum_os",
+    defaultValue = DEFAULT_MINIMUM_MACOS,
+    category = "flags",
+    converter = DottedVersionConverter.class,
+    help = "Minimum compatible macOS version for targets."
   )
   public DottedVersion macosMinimumOs;
 
@@ -147,37 +148,44 @@ public class AppleCommandLineOptions extends FragmentOptions {
    */
   public static final String DEFAULT_MACOS_CPU = "x86_64";
 
-  @Option(name = "ios_cpu",
-      defaultValue = DEFAULT_IOS_CPU,
-      category = "build",
-      help = "Specifies to target CPU of iOS compilation.")
+  @Option(
+    name = "ios_cpu",
+    defaultValue = DEFAULT_IOS_CPU,
+    category = "build",
+    help = "Specifies to target CPU of iOS compilation."
+  )
   public String iosCpu;
 
   @Option(
-      name = "apple_crosstool_top",
-      defaultValue = "@bazel_tools//tools/cpp:toolchain",
-      category = "version",
-      converter = LabelConverter.class,
-      help = "The label of the crosstool package to be used in Apple and Objc rules and their"
+    name = "apple_crosstool_top",
+    defaultValue = "@bazel_tools//tools/cpp:toolchain",
+    category = "version",
+    converter = LabelConverter.class,
+    help =
+        "The label of the crosstool package to be used in Apple and Objc rules and their"
             + " dependencies."
-    )
-  public Label appleCrosstoolTop;  
-
-  @Option(name = "apple_platform_type",
-      defaultValue = "IOS",
-      category = "undocumented",
-      converter = PlatformTypeConverter.class,
-      help =
-          "Don't set this value from the command line - it is derived from other flags and "
-          + "configuration transitions derived from rule attributes")
+  )
+  public Label appleCrosstoolTop;
+
+  @Option(
+    name = "apple_platform_type",
+    defaultValue = "IOS",
+    optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED,
+    converter = PlatformTypeConverter.class,
+    help =
+        "Don't set this value from the command line - it is derived from other flags and "
+            + "configuration transitions derived from rule attributes"
+  )
   public PlatformType applePlatformType;
 
-  @Option(name = "apple_split_cpu",
-      defaultValue = "",
-      category = "undocumented",
-      help =
-          "Don't set this value from the command line - it is derived from other flags and "
-          + "configuration transitions derived from rule attributes")
+  @Option(
+    name = "apple_split_cpu",
+    defaultValue = "",
+    optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED,
+    help =
+        "Don't set this value from the command line - it is derived from other flags and "
+            + "configuration transitions derived from rule attributes"
+  )
   public String appleSplitCpu;
 
   // This option exists because two configurations are not allowed to have the same cache key
@@ -186,51 +194,64 @@ public class AppleCommandLineOptions extends FragmentOptions {
   // This option must only be set by those transitions for this purpose.
   // TODO(bazel-team): Remove this once we have dynamic configurations but make sure that different
   // configurations (e.g. by min os version) always use different output paths.
-  @Option(name = "apple configuration distinguisher",
-      defaultValue = "UNKNOWN",
-      converter = ConfigurationDistinguisherConverter.class,
-      category = "internal")
+  @Option(
+    name = "apple configuration distinguisher",
+    defaultValue = "UNKNOWN",
+    converter = ConfigurationDistinguisherConverter.class,
+    optionUsageRestrictions = OptionUsageRestrictions.INTERNAL
+  )
   public ConfigurationDistinguisher configurationDistinguisher;
 
-  @Option(name = "ios_multi_cpus",
-      converter = CommaSeparatedOptionListConverter.class,
-      defaultValue = "",
-      category = "flags",
-      help = "Comma-separated list of architectures to build an ios_application with. The result "
-          + "is a universal binary containing all specified architectures.")
+  @Option(
+    name = "ios_multi_cpus",
+    converter = CommaSeparatedOptionListConverter.class,
+    defaultValue = "",
+    category = "flags",
+    help =
+        "Comma-separated list of architectures to build an ios_application with. The result "
+            + "is a universal binary containing all specified architectures."
+  )
   public List<String> iosMultiCpus;
 
-  @Option(name = "watchos_cpus",
-      converter = CommaSeparatedOptionListConverter.class,
-      defaultValue = DEFAULT_WATCHOS_CPU,
-      category = "flags",
-      help = "Comma-separated list of architectures for which to build Apple watchOS binaries.")
+  @Option(
+    name = "watchos_cpus",
+    converter = CommaSeparatedOptionListConverter.class,
+    defaultValue = DEFAULT_WATCHOS_CPU,
+    category = "flags",
+    help = "Comma-separated list of architectures for which to build Apple watchOS binaries."
+  )
   public List<String> watchosCpus;
 
-  @Option(name = "tvos_cpus",
-      converter = CommaSeparatedOptionListConverter.class,
-      defaultValue = DEFAULT_TVOS_CPU,
-      category = "flags",
-      help = "Comma-separated list of architectures for which to build Apple tvOS binaries.")
+  @Option(
+    name = "tvos_cpus",
+    converter = CommaSeparatedOptionListConverter.class,
+    defaultValue = DEFAULT_TVOS_CPU,
+    category = "flags",
+    help = "Comma-separated list of architectures for which to build Apple tvOS binaries."
+  )
   public List<String> tvosCpus;
 
-  @Option(name = "macos_cpus",
-      converter = CommaSeparatedOptionListConverter.class,
-      defaultValue = DEFAULT_MACOS_CPU,
-      category = "flags",
-      help = "Comma-separated list of architectures for which to build Apple macOS binaries.")
+  @Option(
+    name = "macos_cpus",
+    converter = CommaSeparatedOptionListConverter.class,
+    defaultValue = DEFAULT_MACOS_CPU,
+    category = "flags",
+    help = "Comma-separated list of architectures for which to build Apple macOS binaries."
+  )
   public List<String> macosCpus;
 
-  @Option(name = "default_ios_provisioning_profile",
-      defaultValue = "",
-      category = "undocumented",
-      converter = DefaultProvisioningProfileConverter.class)
+  @Option(
+    name = "default_ios_provisioning_profile",
+    defaultValue = "",
+    optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED,
+    converter = DefaultProvisioningProfileConverter.class
+  )
   public Label defaultProvisioningProfile;
 
   @Option(
     name = "xcode_version_config",
     defaultValue = "@local_config_xcode//:host_xcodes",
-    category = "undocumented",
+    optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED,
     converter = LabelConverter.class,
     help =
         "The label of the xcode_config rule to be used for selecting the Xcode version "
@@ -256,26 +277,30 @@ public class AppleCommandLineOptions extends FragmentOptions {
     name = "xcode_toolchain",
     defaultValue = "null",
     category = "flags",
-    help = "The identifier of an Xcode toolchain to use for builds. Currently only the toolchains "
-           + "that ship with Xcode are supported. For example, in addition to the default toolchain"
-           + " Xcode 8 has 'com.apple.dt.toolchain.Swift_2_3' which can be used for building legacy"
-           + " Swift code."
+    help =
+        "The identifier of an Xcode toolchain to use for builds. Currently only the toolchains "
+            + "that ship with Xcode are supported. For example, in addition to the default "
+            + "toolchain Xcode 8 has 'com.apple.dt.toolchain.Swift_2_3' which can be used for "
+            + "building legacy Swift code."
   )
   public String xcodeToolchain;
 
-  @Option(name = "apple_bitcode",
-      converter = AppleBitcodeMode.Converter.class,
-      // TODO(blaze-team): Default to embedded_markers when fully implemented.
-      defaultValue = "none",
-      category = "flags",
-      help = "Specify the Apple bitcode mode for compile steps. "
-             + "Values: 'none', 'embedded_markers', 'embedded'.")
+  @Option(
+    name = "apple_bitcode",
+    converter = AppleBitcodeMode.Converter.class,
+    // TODO(blaze-team): Default to embedded_markers when fully implemented.
+    defaultValue = "none",
+    category = "flags",
+    help =
+        "Specify the Apple bitcode mode for compile steps. "
+            + "Values: 'none', 'embedded_markers', 'embedded'."
+  )
   public AppleBitcodeMode appleBitcodeMode;
 
   @Option(
     name = "apple_crosstool_transition",
     defaultValue = "false",
-    category = "undocumented",
+    optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED,
     help = "If true, the apple crosstool is used for all apple rules."
   )
   public boolean enableAppleCrosstoolTransition;
@@ -283,7 +308,7 @@ public class AppleCommandLineOptions extends FragmentOptions {
   @Option(
     name = "target_uses_apple_crosstool",
     defaultValue = "false",
-    category = "undocumented",
+    optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED,
     help = "If true, this target uses the apple crosstool.  Do not set this flag manually."
   )
   public boolean targetUsesAppleCrosstool;
diff --git a/src/main/java/com/google/devtools/build/lib/rules/config/ConfigFeatureFlagConfiguration.java b/src/main/java/com/google/devtools/build/lib/rules/config/ConfigFeatureFlagConfiguration.java
index 3d751c1721..dbb913d626 100644
--- a/src/main/java/com/google/devtools/build/lib/rules/config/ConfigFeatureFlagConfiguration.java
+++ b/src/main/java/com/google/devtools/build/lib/rules/config/ConfigFeatureFlagConfiguration.java
@@ -28,6 +28,7 @@ import com.google.devtools.build.lib.analysis.config.FragmentOptions;
 import com.google.devtools.build.lib.cmdline.Label;
 import com.google.devtools.common.options.Converter;
 import com.google.devtools.common.options.Option;
+import com.google.devtools.common.options.OptionsParser.OptionUsageRestrictions;
 import java.util.Map;
 import java.util.SortedMap;
 import javax.annotation.Nullable;
@@ -56,10 +57,11 @@ public final class ConfigFeatureFlagConfiguration extends BuildConfiguration.Fra
   public static final class Options extends FragmentOptions {
     /** The mapping from config_feature_flag rules to their values. */
     @Option(
-        name = "config_feature_flag values (private)",
-        category = "internal",
-        converter = EmptyImmutableSortedMapConverter.class,
-        defaultValue = "{}")
+      name = "config_feature_flag values (private)",
+      optionUsageRestrictions = OptionUsageRestrictions.INTERNAL,
+      converter = EmptyImmutableSortedMapConverter.class,
+      defaultValue = "{}"
+    )
     public ImmutableSortedMap<Label, String> flagValues = ImmutableSortedMap.of();
 
     /** Retrieves the set of flag-value pairs. */
diff --git a/src/main/java/com/google/devtools/build/lib/rules/cpp/CppOptions.java b/src/main/java/com/google/devtools/build/lib/rules/cpp/CppOptions.java
index 19af5fd0b8..baa5bfe613 100644
--- a/src/main/java/com/google/devtools/build/lib/rules/cpp/CppOptions.java
+++ b/src/main/java/com/google/devtools/build/lib/rules/cpp/CppOptions.java
@@ -33,6 +33,7 @@ import com.google.devtools.build.lib.view.config.crosstool.CrosstoolConfig.LipoM
 import com.google.devtools.common.options.Converter;
 import com.google.devtools.common.options.EnumConverter;
 import com.google.devtools.common.options.Option;
+import com.google.devtools.common.options.OptionsParser.OptionUsageRestrictions;
 import com.google.devtools.common.options.OptionsParsingException;
 import java.util.LinkedHashSet;
 import java.util.List;
@@ -129,7 +130,7 @@ public class CppOptions extends FragmentOptions {
   @Option(
     name = "lipo input collector",
     defaultValue = "false",
-    category = "internal",
+    optionUsageRestrictions = OptionUsageRestrictions.INTERNAL,
     help = "Internal flag, only used to create configurations with the LIPO-collector flag set."
   )
   public boolean lipoCollector;
@@ -603,7 +604,7 @@ public class CppOptions extends FragmentOptions {
     category = "strategy",
     help =
         "If true, headers found through system include paths (-isystem) are also required to be "
-        + "declared."
+            + "declared."
   )
   public boolean strictSystemIncludes;
 
diff --git a/src/main/java/com/google/devtools/build/lib/rules/java/JavaOptions.java b/src/main/java/com/google/devtools/build/lib/rules/java/JavaOptions.java
index 1fa3fbf228..f64373d5c5 100644
--- a/src/main/java/com/google/devtools/build/lib/rules/java/JavaOptions.java
+++ b/src/main/java/com/google/devtools/build/lib/rules/java/JavaOptions.java
@@ -29,6 +29,7 @@ import com.google.devtools.build.lib.rules.java.JavaConfiguration.JavaClasspathM
 import com.google.devtools.build.lib.rules.java.JavaConfiguration.JavaOptimizationMode;
 import com.google.devtools.common.options.EnumConverter;
 import com.google.devtools.common.options.Option;
+import com.google.devtools.common.options.OptionsParser.OptionUsageRestrictions;
 import com.google.devtools.common.options.TriState;
 import java.util.HashMap;
 import java.util.LinkedHashSet;
@@ -57,19 +58,24 @@ public class JavaOptions extends FragmentOptions {
     }
   }
 
-  @Option(name = "javabase",
-      defaultValue = "@bazel_tools//tools/jdk:jdk",
-      category = "version",
-      help = "JAVABASE used for the JDK invoked by Blaze. This is the "
-          + "JAVABASE which will be used to execute external Java "
-          + "commands.")
+  @Option(
+    name = "javabase",
+    defaultValue = "@bazel_tools//tools/jdk:jdk",
+    category = "version",
+    help =
+        "JAVABASE used for the JDK invoked by Blaze. This is the "
+            + "JAVABASE which will be used to execute external Java "
+            + "commands."
+  )
   public String javaBase;
 
-  @Option(name = "java_toolchain",
-      defaultValue = "@bazel_tools//tools/jdk:toolchain",
-      category = "version",
-      converter = LabelConverter.class,
-      help = "The name of the toolchain rule for Java.")
+  @Option(
+    name = "java_toolchain",
+    defaultValue = "@bazel_tools//tools/jdk:toolchain",
+    category = "version",
+    converter = LabelConverter.class,
+    help = "The name of the toolchain rule for Java."
+  )
   public Label javaToolchain;
 
   @Option(
@@ -81,41 +87,54 @@ public class JavaOptions extends FragmentOptions {
   )
   public Label hostJavaToolchain;
 
-  @Option(name = "host_javabase",
-      defaultValue = "@bazel_tools//tools/jdk:jdk",
-      category = "version",
-      help = "JAVABASE used for the host JDK. This is the JAVABASE which is used to execute "
-           + " tools during a build.")
+  @Option(
+    name = "host_javabase",
+    defaultValue = "@bazel_tools//tools/jdk:jdk",
+    category = "version",
+    help =
+        "JAVABASE used for the host JDK. This is the JAVABASE which is used to execute "
+            + " tools during a build."
+  )
   public String hostJavaBase;
 
-  @Option(name = "javacopt",
-      allowMultiple = true,
-      defaultValue = "",
-      category = "flags",
-      help = "Additional options to pass to javac.")
+  @Option(
+    name = "javacopt",
+    allowMultiple = true,
+    defaultValue = "",
+    category = "flags",
+    help = "Additional options to pass to javac."
+  )
   public List<String> javacOpts;
 
-  @Option(name = "jvmopt",
-      allowMultiple = true,
-      defaultValue = "",
-      category = "flags",
-      help = "Additional options to pass to the Java VM. These options will get added to the "
-          + "VM startup options of each java_binary target.")
+  @Option(
+    name = "jvmopt",
+    allowMultiple = true,
+    defaultValue = "",
+    category = "flags",
+    help =
+        "Additional options to pass to the Java VM. These options will get added to the "
+            + "VM startup options of each java_binary target."
+  )
   public List<String> jvmOpts;
 
-  @Option(name = "use_ijars",
-      defaultValue = "true",
-      category = "strategy",
-      help = "If enabled, this option causes Java compilation to use interface jars. "
-          + "This will result in faster incremental compilation, "
-          + "but error messages can be different.")
+  @Option(
+    name = "use_ijars",
+    defaultValue = "true",
+    category = "strategy",
+    help =
+        "If enabled, this option causes Java compilation to use interface jars. "
+            + "This will result in faster incremental compilation, "
+            + "but error messages can be different."
+  )
   public boolean useIjars;
 
   @Deprecated
-  @Option(name = "use_src_ijars",
-      defaultValue = "false",
-      category = "undocumented",
-      help = "No-op. Kept here for backwards compatibility.")
+  @Option(
+    name = "use_src_ijars",
+    defaultValue = "false",
+    optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED,
+    help = "No-op. Kept here for backwards compatibility."
+  )
   public boolean useSourceIjars;
 
   @Option(
@@ -132,15 +151,17 @@ public class JavaOptions extends FragmentOptions {
   @Option(
     name = "experimental_optimize_header_compilation_annotation_processing",
     defaultValue = "false",
-    category = "undocumented",
+    optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED,
     help = "This flag is a noop and scheduled for removal."
   )
   public boolean optimizeHeaderCompilationAnnotationProcessing;
 
-  @Option(name = "java_deps",
-      defaultValue = "true",
-      category = "strategy",
-      help = "Generate dependency information (for now, compile-time classpath) per Java target.")
+  @Option(
+    name = "java_deps",
+    defaultValue = "true",
+    category = "strategy",
+    help = "Generate dependency information (for now, compile-time classpath) per Java target."
+  )
   public boolean javaDeps;
 
   @Option(
@@ -154,15 +175,22 @@ public class JavaOptions extends FragmentOptions {
   )
   public JavaClasspathMode javaClasspath;
 
-  @Option(name = "java_debug",
-      defaultValue = "null",
-      category = "testing",
-      expansion = {"--test_arg=--wrapper_script_flag=--debug", "--test_output=streamed",
-                   "--test_strategy=exclusive", "--test_timeout=9999", "--nocache_test_results"},
-      help = "Causes the Java virtual machine of a java test to wait for a connection from a "
-      + "JDWP-compliant debugger (such as jdb) before starting the test. Implies "
-      + "-test_output=streamed."
-      )
+  @Option(
+    name = "java_debug",
+    defaultValue = "null",
+    category = "testing",
+    expansion = {
+      "--test_arg=--wrapper_script_flag=--debug",
+      "--test_output=streamed",
+      "--test_strategy=exclusive",
+      "--test_timeout=9999",
+      "--nocache_test_results"
+    },
+    help =
+        "Causes the Java virtual machine of a java test to wait for a connection from a "
+            + "JDWP-compliant debugger (such as jdb) before starting the test. Implies "
+            + "-test_output=streamed."
+  )
   public Void javaTestDebug;
 
   @Option(
@@ -181,25 +209,31 @@ public class JavaOptions extends FragmentOptions {
   // TODO(bazel-team): This flag should ideally default to true (and eventually removed). We have
   // been accidentally supplying JUnit and Hamcrest deps to java_test targets indirectly via the
   // BazelTestRunner, and setting this flag to true fixes that behaviour.
-  @Option(name = "explicit_java_test_deps",
-      defaultValue = "false",
-      category = "semantics",
-      help = "Explicitly specify a dependency to JUnit or Hamcrest in a java_test instead of "
-          + " accidentally obtaining from the TestRunner's deps. Only works for bazel right now.")
+  @Option(
+    name = "explicit_java_test_deps",
+    defaultValue = "false",
+    category = "semantics",
+    help =
+        "Explicitly specify a dependency to JUnit or Hamcrest in a java_test instead of "
+            + " accidentally obtaining from the TestRunner's deps. Only works for bazel right now."
+  )
   public boolean explicitJavaTestDeps;
 
-  @Option(name = "experimental_testrunner",
-      defaultValue = "false",
-      category = "undocumented",
-      help = "Use the experimental test runner in bazel which runs the tests under a separate "
-          + "classloader. We must set the --explicit_java_test_deps flag with this to ensure "
-          + "the test targets have their dependencies right.")
+  @Option(
+    name = "experimental_testrunner",
+    defaultValue = "false",
+    optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED,
+    help =
+        "Use the experimental test runner in bazel which runs the tests under a separate "
+            + "classloader. We must set the --explicit_java_test_deps flag with this to ensure "
+            + "the test targets have their dependencies right."
+  )
   public boolean experimentalTestRunner;
 
   @Option(
     name = "javabuilder_top",
     defaultValue = "null",
-    category = "undocumented",
+    optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED,
     help = "No-op. Kept here for backwards compatibility."
   )
   public String javaBuilderTop;
@@ -207,7 +241,7 @@ public class JavaOptions extends FragmentOptions {
   @Option(
     name = "singlejar_top",
     defaultValue = "null",
-    category = "undocumented",
+    optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED,
     help = "No-op. Kept here for backwards compatibility."
   )
   public String singleJarTop;
@@ -215,7 +249,7 @@ public class JavaOptions extends FragmentOptions {
   @Option(
     name = "genclass_top",
     defaultValue = "null",
-    category = "undocumented",
+    optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED,
     help = "No-op. Kept here for backwards compatibility."
   )
   public String genClassTop;
@@ -223,7 +257,7 @@ public class JavaOptions extends FragmentOptions {
   @Option(
     name = "ijar_top",
     defaultValue = "null",
-    category = "undocumented",
+    optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED,
     help = "No-op. Kept here for backwards compatibility."
   )
   public String iJarTop;
@@ -231,7 +265,7 @@ public class JavaOptions extends FragmentOptions {
   @Option(
     name = "java_langtools",
     defaultValue = "null",
-    category = "undocumented",
+    optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED,
     help = "No-op. Kept here for backwards compatibility."
   )
   public String javaLangtoolsJar;
@@ -239,7 +273,7 @@ public class JavaOptions extends FragmentOptions {
   @Option(
     name = "javac_bootclasspath",
     defaultValue = "null",
-    category = "undocumented",
+    optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED,
     help = "No-op. Kept here for backwards compatibility."
   )
   public String javacBootclasspath;
@@ -247,7 +281,7 @@ public class JavaOptions extends FragmentOptions {
   @Option(
     name = "javac_extdir",
     defaultValue = "null",
-    category = "undocumented",
+    optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED,
     help = "No-op. Kept here for backwards compatibility."
   )
   public String javacExtdir;
@@ -272,79 +306,99 @@ public class JavaOptions extends FragmentOptions {
   )
   public Label javaLauncher;
 
-  @Option(name = "proguard_top",
-      defaultValue = "null",
-      category = "version",
-      converter = LabelConverter.class,
-      help = "Specifies which version of ProGuard to use for code removal when building a Java "
-          + "binary.")
+  @Option(
+    name = "proguard_top",
+    defaultValue = "null",
+    category = "version",
+    converter = LabelConverter.class,
+    help =
+        "Specifies which version of ProGuard to use for code removal when building a Java "
+            + "binary."
+  )
   public Label proguard;
 
-  @Option(name = "extra_proguard_specs",
-      allowMultiple = true,
-      defaultValue = "", // Ignored
-      converter = LabelConverter.class,
-      category = "undocumented",
-      help = "Additional Proguard specs that will be used for all Proguard invocations.  Note that "
-          + "using this option only has an effect when Proguard is used anyway.")
+  @Option(
+    name = "extra_proguard_specs",
+    allowMultiple = true,
+    defaultValue = "", // Ignored
+    converter = LabelConverter.class,
+    optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED,
+    help =
+        "Additional Proguard specs that will be used for all Proguard invocations.  Note that "
+            + "using this option only has an effect when Proguard is used anyway."
+  )
   public List<Label> extraProguardSpecs;
 
   /**
    * Comma-separated list of Mnemonic=label pairs of optimizers to run in the given order, treating
-   * {@code Proguard} specially by substituting in the relevant Proguard binary automatically.
-   * All optimizers must understand the same flags as Proguard.
+   * {@code Proguard} specially by substituting in the relevant Proguard binary automatically. All
+   * optimizers must understand the same flags as Proguard.
    */
-  @Option(name = "experimental_bytecode_optimizers",
-      defaultValue = "Proguard",
-      converter = LabelMapConverter.class,
-      category = "undocumented",
-      help = "Do not use.")
+  @Option(
+    name = "experimental_bytecode_optimizers",
+    defaultValue = "Proguard",
+    converter = LabelMapConverter.class,
+    optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED,
+    help = "Do not use."
+  )
   public Map<String, Label> bytecodeOptimizers;
 
-  @Option(name = "translations",
-      defaultValue = "auto",
-      category = "semantics",
-      help = "Translate Java messages; bundle all translations into the jar "
-          + "for each affected rule.")
+  @Option(
+    name = "translations",
+    defaultValue = "auto",
+    category = "semantics",
+    help =
+        "Translate Java messages; bundle all translations into the jar " + "for each affected rule."
+  )
   public TriState bundleTranslations;
 
-  @Option(name = "message_translations",
-      defaultValue = "",
-      category = "semantics",
-      allowMultiple = true,
-      help = "The message translations used for translating messages in Java targets.")
+  @Option(
+    name = "message_translations",
+    defaultValue = "",
+    category = "semantics",
+    allowMultiple = true,
+    help = "The message translations used for translating messages in Java targets."
+  )
   public List<String> translationTargets;
 
-  @Option(name = "check_constraint",
-      allowMultiple = true,
-      defaultValue = "",
-      category = "checking",
-      help = "Check the listed constraint.")
+  @Option(
+    name = "check_constraint",
+    allowMultiple = true,
+    defaultValue = "",
+    category = "checking",
+    help = "Check the listed constraint."
+  )
   public List<String> checkedConstraints;
 
-  @Option(name = "experimental_disable_jvm",
-      defaultValue = "false",
-      category = "undocumented",
-      help = "Disables the Jvm configuration entirely.")
+  @Option(
+    name = "experimental_disable_jvm",
+    defaultValue = "false",
+    optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED,
+    help = "Disables the Jvm configuration entirely."
+  )
   public boolean disableJvm;
 
-  @Option(name = "java_optimization_mode",
-      defaultValue = "legacy",
-      converter = JavaOptimizationModeConverter.class,
-      category = "undocumented",
-      help = "Applies desired link-time optimizations to Java binaries and tests.")
+  @Option(
+    name = "java_optimization_mode",
+    defaultValue = "legacy",
+    converter = JavaOptimizationModeConverter.class,
+    optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED,
+    help = "Applies desired link-time optimizations to Java binaries and tests."
+  )
   public JavaOptimizationMode javaOptimizationMode;
 
-  @Option(name = "legacy_bazel_java_test",
-      defaultValue = "false",
-      category = "undocumented",
-      help = "Use the legacy mode of Bazel for java_test.")
+  @Option(
+    name = "legacy_bazel_java_test",
+    defaultValue = "false",
+    optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED,
+    help = "Use the legacy mode of Bazel for java_test."
+  )
   public boolean legacyBazelJavaTest;
 
   @Option(
     name = "strict_deps_java_protos",
     defaultValue = "false",
-    category = "undocumented",
+    optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED,
     help =
         "When 'strict-deps' is on, .java files that depend on classes not declared in their rule's "
             + "'deps' fail to build. In other words, it's forbidden to depend on classes obtained "
@@ -356,7 +410,7 @@ public class JavaOptions extends FragmentOptions {
   @Option(
     name = "experimental_java_header_compilation_direct_classpath",
     defaultValue = "false",
-    category = "undocumented",
+    optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED,
     help = "Experimental option to limit the header compilation classpath to direct deps."
   )
   public boolean headerCompilationDirectClasspath;
@@ -364,7 +418,7 @@ public class JavaOptions extends FragmentOptions {
   @Option(
     name = "experimental_java_header_compilation_direct_classpath_fallback_error",
     defaultValue = "false",
-    category = "undocumented",
+    optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED,
     help =
         "If --experimental_java_header_compilation_direct_classpath is set, transitive classpath"
             + " fallback is an error"
@@ -374,7 +428,7 @@ public class JavaOptions extends FragmentOptions {
   @Option(
     name = "experimental_one_version_enforcement",
     defaultValue = "false",
-    category = "undocumented",
+    optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED,
     help =
         "When enabled, enforce that a java_binary rule can't contain more than one version "
             + "of the same class file on the classpath"
diff --git a/src/main/java/com/google/devtools/build/lib/rules/objc/J2ObjcCommandLineOptions.java b/src/main/java/com/google/devtools/build/lib/rules/objc/J2ObjcCommandLineOptions.java
index 14d513627b..8ccf0308af 100644
--- a/src/main/java/com/google/devtools/build/lib/rules/objc/J2ObjcCommandLineOptions.java
+++ b/src/main/java/com/google/devtools/build/lib/rules/objc/J2ObjcCommandLineOptions.java
@@ -20,6 +20,7 @@ import com.google.devtools.build.lib.analysis.config.FragmentOptions;
 import com.google.devtools.build.lib.cmdline.Label;
 import com.google.devtools.common.options.Converters;
 import com.google.devtools.common.options.Option;
+import com.google.devtools.common.options.OptionsParser.OptionUsageRestrictions;
 import java.util.List;
 
 /**
@@ -28,44 +29,51 @@ import java.util.List;
  * (specifically, J2ObjCAspects thereof).
  */
 public class J2ObjcCommandLineOptions extends FragmentOptions {
-  @Option(name = "j2objc_translation_flags",
-      converter = Converters.CommaSeparatedOptionListConverter.class,
-      allowMultiple = true,
-      defaultValue = "",
-      category = "flags",
-      help = "Additional options to pass to the J2ObjC tool."
-      )
+  @Option(
+    name = "j2objc_translation_flags",
+    converter = Converters.CommaSeparatedOptionListConverter.class,
+    allowMultiple = true,
+    defaultValue = "",
+    category = "flags",
+    help = "Additional options to pass to the J2ObjC tool."
+  )
   public List<String> translationFlags;
 
-  @Option(name = "j2objc_dead_code_removal",
-      defaultValue = "false",
-      category = "undocumented",
-      help = "Whether to perform J2ObjC dead code removal to strip unused code from the final app "
-          + "bundle."
-      )
+  @Option(
+    name = "j2objc_dead_code_removal",
+    defaultValue = "false",
+    optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED,
+    help =
+        "Whether to perform J2ObjC dead code removal to strip unused code from the final app "
+            + "bundle."
+  )
   public boolean removeDeadCode;
 
-  @Option(name = "j2objc_dead_code_report",
-      defaultValue = "null",
-      category = "undocumented",
-      converter = LabelConverter.class,
-      help = "Allows J2ObjC to strip dead code reported by ProGuard. Takes a label that can "
-          + "generate a dead code report as argument."
+  @Option(
+    name = "j2objc_dead_code_report",
+    defaultValue = "null",
+    optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED,
+    converter = LabelConverter.class,
+    help =
+        "Allows J2ObjC to strip dead code reported by ProGuard. Takes a label that can "
+            + "generate a dead code report as argument."
   )
   public Label deadCodeReport;
 
-  @Option(name = "explicit_jre_deps",
-      defaultValue = "true",
-      category = "flags",
-      help = "Requires JRE dependencies to be declared in j2objc_library's jre_deps attribute."
-      )
+  @Option(
+    name = "explicit_jre_deps",
+    defaultValue = "true",
+    category = "flags",
+    help = "Requires JRE dependencies to be declared in j2objc_library's jre_deps attribute."
+  )
   public boolean explicitJreDeps;
 
-  @Option(name = "experimental_j2objc_header_map",
-      defaultValue = "false",
-      category = "flags",
-      help = "Whether to generate J2ObjC header map in parallel of J2ObjC transpilation."
-      )
+  @Option(
+    name = "experimental_j2objc_header_map",
+    defaultValue = "false",
+    category = "flags",
+    help = "Whether to generate J2ObjC header map in parallel of J2ObjC transpilation."
+  )
   public boolean experimentalJ2ObjcHeaderMap;
 
   @Override
diff --git a/src/main/java/com/google/devtools/build/lib/rules/objc/ObjcCommandLineOptions.java b/src/main/java/com/google/devtools/build/lib/rules/objc/ObjcCommandLineOptions.java
index 514e2a0c9c..1e45d7b829 100644
--- a/src/main/java/com/google/devtools/build/lib/rules/objc/ObjcCommandLineOptions.java
+++ b/src/main/java/com/google/devtools/build/lib/rules/objc/ObjcCommandLineOptions.java
@@ -22,7 +22,7 @@ import com.google.devtools.build.lib.rules.apple.DottedVersionConverter;
 import com.google.devtools.common.options.Converters.CommaSeparatedOptionListConverter;
 import com.google.devtools.common.options.EnumConverter;
 import com.google.devtools.common.options.Option;
-
+import com.google.devtools.common.options.OptionsParser.OptionUsageRestrictions;
 import java.util.List;
 
 /**
@@ -40,85 +40,105 @@ public class ObjcCommandLineOptions extends FragmentOptions {
   )
   public DottedVersion iosSimulatorVersion;
 
-  @Option(name = "ios_simulator_device",
-      defaultValue = "iPhone 5s",
-      category = "run",
-      help = "The device to simulate when running an iOS application in the simulator, e.g. "
-          + "'iPhone 6'. You can get a list of devices by running 'xcrun simctl list devicetypes' "
-          + "on the machine the simulator will be run on.")
+  @Option(
+    name = "ios_simulator_device",
+    defaultValue = "iPhone 5s",
+    category = "run",
+    help =
+        "The device to simulate when running an iOS application in the simulator, e.g. "
+            + "'iPhone 6'. You can get a list of devices by running 'xcrun simctl list "
+            + "devicetypes' on the machine the simulator will be run on."
+  )
   public String iosSimulatorDevice;
 
   @Option(
-      name = "watchos_simulator_version",
-      defaultValue = "2.0",
-      category = "run",
-      converter = DottedVersionConverter.class,
-      help = "The version of watchOS to run on the simulator when running or testing."
+    name = "watchos_simulator_version",
+    defaultValue = "2.0",
+    category = "run",
+    converter = DottedVersionConverter.class,
+    help = "The version of watchOS to run on the simulator when running or testing."
   )
   public DottedVersion watchosSimulatorVersion;
 
-  @Option(name = "watchos_simulator_device",
-      defaultValue = "Apple Watch - 38mm",
-      category = "run",
-      help = "The device to simulate when running an watchOS application in the simulator, e.g. "
-          + "'Apple Watch - 38mm'. You can get a list of devices by running 'xcrun simctl list "
-          + "devicetypes' on the machine the simulator will be run on.")
+  @Option(
+    name = "watchos_simulator_device",
+    defaultValue = "Apple Watch - 38mm",
+    category = "run",
+    help =
+        "The device to simulate when running an watchOS application in the simulator, e.g. "
+            + "'Apple Watch - 38mm'. You can get a list of devices by running 'xcrun simctl list "
+            + "devicetypes' on the machine the simulator will be run on."
+  )
   public String watchosSimulatorDevice;
 
   @Option(
-      name = "tvos_simulator_version",
-      defaultValue = "9.0",
-      category = "run",
-      converter = DottedVersionConverter.class,
-      help = "The version of tvOS to run on the simulator when running or testing."
+    name = "tvos_simulator_version",
+    defaultValue = "9.0",
+    category = "run",
+    converter = DottedVersionConverter.class,
+    help = "The version of tvOS to run on the simulator when running or testing."
   )
   public DottedVersion tvosSimulatorVersion;
 
-  @Option(name = "tvos_simulator_device",
-      defaultValue = "Apple TV 1080p",
-      category = "run",
-      help = "The device to simulate when running an tvOS application in the simulator, e.g. "
-          + "'Apple TV 1080p'. You can get a list of devices by running 'xcrun simctl list "
-          + "devicetypes' on the machine the simulator will be run on.")
+  @Option(
+    name = "tvos_simulator_device",
+    defaultValue = "Apple TV 1080p",
+    category = "run",
+    help =
+        "The device to simulate when running an tvOS application in the simulator, e.g. "
+            + "'Apple TV 1080p'. You can get a list of devices by running 'xcrun simctl list "
+            + "devicetypes' on the machine the simulator will be run on."
+  )
   public String tvosSimulatorDevice;
 
-  @Option(name = "objc_generate_linkmap",
-      defaultValue = "false",
-      category = "flags",
-      help = "Specifies whether to generate a linkmap file.")
+  @Option(
+    name = "objc_generate_linkmap",
+    defaultValue = "false",
+    category = "flags",
+    help = "Specifies whether to generate a linkmap file."
+  )
   public boolean generateLinkmap;
 
-  @Option(name = "objccopt",
-      allowMultiple = true,
-      defaultValue = "",
-      category = "flags",
-      help = "Additional options to pass to Objective C compilation.")
+  @Option(
+    name = "objccopt",
+    allowMultiple = true,
+    defaultValue = "",
+    category = "flags",
+    help = "Additional options to pass to Objective C compilation."
+  )
   public List<String> copts;
 
-  @Option(name = "ios_memleaks",
-      defaultValue =  "false",
-      category = "misc",
-      help = "Enable checking for memory leaks in ios_test targets.")
+  @Option(
+    name = "ios_memleaks",
+    defaultValue = "false",
+    category = "misc",
+    help = "Enable checking for memory leaks in ios_test targets."
+  )
   public boolean runMemleaks;
 
-  @Option(name = "experimental_enable_objc_cc_deps",
-      defaultValue = "false",
-      category = "undocumented",
-      help = "Allows objc_* rules to depend on cc_library and causes any objc dependencies to be "
-          + "built with --cpu set to \"ios_<--ios_cpu>\" for any values in --ios_multi_cpu.")
+  @Option(
+    name = "experimental_enable_objc_cc_deps",
+    defaultValue = "false",
+    optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED,
+    help =
+        "Allows objc_* rules to depend on cc_library and causes any objc dependencies to be "
+            + "built with --cpu set to \"ios_<--ios_cpu>\" for any values in --ios_multi_cpu."
+  )
   public boolean enableCcDeps;
 
-  @Option(name = "experimental_objc_fastbuild_options",
-      defaultValue = "-O0,-DDEBUG=1",
-      category = "undocumented",
-      converter = CommaSeparatedOptionListConverter.class,
-      help = "Uses these strings as objc fastbuild compiler options.")
+  @Option(
+    name = "experimental_objc_fastbuild_options",
+    defaultValue = "-O0,-DDEBUG=1",
+    optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED,
+    converter = CommaSeparatedOptionListConverter.class,
+    help = "Uses these strings as objc fastbuild compiler options."
+  )
   public List<String> fastbuildOptions;
 
   @Option(
     name = "experimental_objc_enable_module_maps",
     defaultValue = "false",
-    category = "undocumented",
+    optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED,
     help = "Enables module map generation and interpretation."
   )
   public boolean enableModuleMaps;
@@ -156,7 +176,7 @@ public class ObjcCommandLineOptions extends FragmentOptions {
   @Option(
     name = "experimental_use_absolute_paths_for_actions",
     defaultValue = "false",
-    category = "undocumented",
+    optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED,
     help = "If set, then all actions objc actions will be executed with absolute paths."
   )
   public boolean useAbsolutePathsForActions;
@@ -184,10 +204,10 @@ public class ObjcCommandLineOptions extends FragmentOptions {
   @Option(
     name = "objc_debug_with_GLIBCXX",
     defaultValue = "true",
-    category = "undocumented",
+    optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED,
     help =
-      "If set, and compilation mode is set to 'dbg', define GLIBCXX_DEBUG, "
-        + " GLIBCXX_DEBUG_PEDANTIC and GLIBCPP_CONCEPT_CHECKS."
+        "If set, and compilation mode is set to 'dbg', define GLIBCXX_DEBUG, "
+            + " GLIBCXX_DEBUG_PEDANTIC and GLIBCPP_CONCEPT_CHECKS."
   )
   public boolean debugWithGlibcxx;
 
@@ -213,17 +233,15 @@ public class ObjcCommandLineOptions extends FragmentOptions {
   public boolean deviceDebugEntitlements;
 
   @Option(
-      name = "deprecated_generate_xcode_project",
-      defaultValue = "false",
-      category = "flags",
-      help =
-          "If set, will generate xcode project for targets that support this. Will be removed soon."
+    name = "deprecated_generate_xcode_project",
+    defaultValue = "false",
+    category = "flags",
+    help =
+        "If set, will generate xcode project for targets that support this. Will be removed soon."
   )
   public boolean generateXcodeProject;
 
-  /**
-   * Specifies the circumstances under which a CROSSTOOL is used for objc in this configuration.
-   */
+  /** Specifies the circumstances under which a CROSSTOOL is used for objc in this configuration. */
   public enum ObjcCrosstoolMode {
     /** The CROSSTOOL is used for all objc compile, archive, and link actions. */
     ALL,
@@ -238,9 +256,7 @@ public class ObjcCommandLineOptions extends FragmentOptions {
     OFF
   }
 
-  /**
-   * Converter for {@link ObjcCrosstoolMode}.
-   */
+  /** Converter for {@link ObjcCrosstoolMode}. */
   public static class ObjcCrosstoolUsageConverter extends EnumConverter<ObjcCrosstoolMode> {
     public ObjcCrosstoolUsageConverter() {
       super(ObjcCrosstoolMode.class, "objc crosstool mode");
@@ -248,18 +264,18 @@ public class ObjcCommandLineOptions extends FragmentOptions {
   }
 
   @Option(
-      name = "experimental_objc_crosstool",
-      defaultValue = "off",
-      category = "undocumented",
-      converter = ObjcCrosstoolUsageConverter.class
+    name = "experimental_objc_crosstool",
+    defaultValue = "off",
+    optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED,
+    converter = ObjcCrosstoolUsageConverter.class
   )
   public ObjcCrosstoolMode objcCrosstoolMode;
 
   // TODO(b/34260565): Remove in favor of --experimental_objc_crosstool
   @Option(
-      name = "experimental_objc_library",
-      defaultValue = "false",
-      category = "undocumented"
+    name = "experimental_objc_library",
+    defaultValue = "false",
+    optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED
   )
   public boolean experimentalObjcLibrary;
 
@@ -277,8 +293,7 @@ public class ObjcCommandLineOptions extends FragmentOptions {
     name = "enable_apple_binary_native_protos",
     defaultValue = "true",
     category = "flags",
-    help =
-        "If set, apple_binary will generate and link objc protos into the output binary."
+    help = "If set, apple_binary will generate and link objc protos into the output binary."
   )
   public boolean enableAppleBinaryNativeProtos;
 
@@ -295,7 +310,7 @@ public class ObjcCommandLineOptions extends FragmentOptions {
   @Option(
     name = "objc_header_thinning_partition_size",
     defaultValue = "120",
-    category = "undocumented",
+    optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED,
     help = "The maximum number of source files to process within in each header scanning action."
   )
   public int objcHeaderThinningPartitionSize;
@@ -303,7 +318,7 @@ public class ObjcCommandLineOptions extends FragmentOptions {
   @Option(
     name = "objc_header_scanner_tool",
     defaultValue = "@bazel_tools//tools/objc:header_scanner",
-    category = "undocumented",
+    optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED,
     converter = LabelConverter.class,
     help =
         "Location of tool to scan Objective-C code for inclusions and output a .headers_list "
@@ -314,7 +329,7 @@ public class ObjcCommandLineOptions extends FragmentOptions {
   @Option(
     name = "apple_sdk",
     defaultValue = "null",
-    category = "undocumented",
+    optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED,
     converter = LabelConverter.class,
     help =
         "Location of target that will provide the appropriate Apple SDK for the current build "
diff --git a/src/main/java/com/google/devtools/build/lib/runtime/BlazeCommandEventHandler.java b/src/main/java/com/google/devtools/build/lib/runtime/BlazeCommandEventHandler.java
index 601f37f5fd..f1906fa003 100644
--- a/src/main/java/com/google/devtools/build/lib/runtime/BlazeCommandEventHandler.java
+++ b/src/main/java/com/google/devtools/build/lib/runtime/BlazeCommandEventHandler.java
@@ -21,6 +21,7 @@ import com.google.devtools.build.lib.util.io.OutErr;
 import com.google.devtools.common.options.EnumConverter;
 import com.google.devtools.common.options.Option;
 import com.google.devtools.common.options.OptionsBase;
+import com.google.devtools.common.options.OptionsParser.OptionUsageRestrictions;
 import java.io.IOException;
 import java.io.OutputStream;
 import java.io.PrintStream;
@@ -56,102 +57,130 @@ public class BlazeCommandEventHandler implements EventHandler {
 
   public static class Options extends OptionsBase {
 
-    @Option(name = "show_progress",
-            defaultValue = "true",
-            category = "verbosity",
-            help = "Display progress messages during a build.")
+    @Option(
+      name = "show_progress",
+      defaultValue = "true",
+      category = "verbosity",
+      help = "Display progress messages during a build."
+    )
     public boolean showProgress;
 
-    @Option(name = "show_task_finish",
-            defaultValue = "false",
-            category = "verbosity",
-            help = "Display progress messages when tasks complete, not just when they start.")
+    @Option(
+      name = "show_task_finish",
+      defaultValue = "false",
+      category = "verbosity",
+      help = "Display progress messages when tasks complete, not just when they start."
+    )
     public boolean showTaskFinish;
 
-    @Option(name = "show_progress_rate_limit",
-            defaultValue = "0.03",  // A nice middle ground; snappy but not too spammy in logs.
-            category = "verbosity",
-            help = "Minimum number of seconds between progress messages in the output.")
+    @Option(
+      name = "show_progress_rate_limit",
+      defaultValue = "0.03", // A nice middle ground; snappy but not too spammy in logs.
+      category = "verbosity",
+      help = "Minimum number of seconds between progress messages in the output."
+    )
     public double showProgressRateLimit;
 
-    @Option(name = "color",
-            defaultValue = "auto",
-            converter = UseColorConverter.class,
-            category = "verbosity",
-            help = "Use terminal controls to colorize output.")
+    @Option(
+      name = "color",
+      defaultValue = "auto",
+      converter = UseColorConverter.class,
+      category = "verbosity",
+      help = "Use terminal controls to colorize output."
+    )
     public UseColor useColorEnum;
 
-    @Option(name = "curses",
-            defaultValue = "auto",
-            converter = UseCursesConverter.class,
-            category = "verbosity",
-            help = "Use terminal cursor controls to minimize scrolling output")
+    @Option(
+      name = "curses",
+      defaultValue = "auto",
+      converter = UseCursesConverter.class,
+      category = "verbosity",
+      help = "Use terminal cursor controls to minimize scrolling output"
+    )
     public UseCurses useCursesEnum;
 
-    @Option(name = "terminal_columns",
-            defaultValue = "80",
-            category = "hidden",
-            help = "A system-generated parameter which specifies the terminal "
-               + " width in columns.")
+    @Option(
+      name = "terminal_columns",
+      defaultValue = "80",
+      optionUsageRestrictions = OptionUsageRestrictions.HIDDEN,
+      help = "A system-generated parameter which specifies the terminal width in columns."
+    )
     public int terminalColumns;
 
-    @Option(name = "isatty",
-            defaultValue = "false",
-            category = "hidden",
-            help = "A system-generated parameter which is used to notify the "
-                + "server whether this client is running in a terminal. "
-                + "If this is set to false, then '--color=auto' will be treated as '--color=no'. "
-                + "If this is set to true, then '--color=auto' will be treated as '--color=yes'.")
+    @Option(
+      name = "isatty",
+      defaultValue = "false",
+      optionUsageRestrictions = OptionUsageRestrictions.HIDDEN,
+      help =
+          "A system-generated parameter which is used to notify the "
+              + "server whether this client is running in a terminal. "
+              + "If this is set to false, then '--color=auto' will be treated as '--color=no'. "
+              + "If this is set to true, then '--color=auto' will be treated as '--color=yes'."
+    )
     public boolean isATty;
 
     // This lives here (as opposed to the more logical BuildRequest.Options)
     // because the client passes it to the server *always*.  We don't want the
     // client to have to figure out when it should or shouldn't to send it.
-    @Option(name = "emacs",
-            defaultValue = "false",
-            category = "undocumented",
-            help = "A system-generated parameter which is true iff EMACS=t or INSIDE_EMACS is set "
-               + "in the environment of the client.  This option controls certain display "
-               + "features.")
+    @Option(
+      name = "emacs",
+      defaultValue = "false",
+      optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED,
+      help =
+          "A system-generated parameter which is true iff EMACS=t or INSIDE_EMACS is set "
+              + "in the environment of the client.  This option controls certain display "
+              + "features."
+    )
     public boolean runningInEmacs;
 
-    @Option(name = "show_timestamps",
-        defaultValue = "false",
-        category = "verbosity",
-        help = "Include timestamps in messages")
+    @Option(
+      name = "show_timestamps",
+      defaultValue = "false",
+      category = "verbosity",
+      help = "Include timestamps in messages"
+    )
     public boolean showTimestamp;
 
-    @Option(name = "progress_in_terminal_title",
-        defaultValue = "false",
-        category = "verbosity",
-        help = "Show the command progress in the terminal title. "
-            + "Useful to see what blaze is doing when having multiple terminal tabs.")
+    @Option(
+      name = "progress_in_terminal_title",
+      defaultValue = "false",
+      category = "verbosity",
+      help =
+          "Show the command progress in the terminal title. "
+              + "Useful to see what blaze is doing when having multiple terminal tabs."
+    )
     public boolean progressInTermTitle;
 
-    @Option(name = "experimental_external_repositories",
-        defaultValue = "false",
-        category = "verbosity",
-        help = "Use external repositories for improved stability and speed when available.")
+    @Option(
+      name = "experimental_external_repositories",
+      defaultValue = "false",
+      category = "verbosity",
+      help = "Use external repositories for improved stability and speed when available."
+    )
     public boolean externalRepositories;
 
-    @Option(name = "force_experimental_external_repositories",
-        defaultValue = "false",
-        category = "verbosity",
-        help = "Forces --experimental_external_repositories.")
+    @Option(
+      name = "force_experimental_external_repositories",
+      defaultValue = "false",
+      category = "verbosity",
+      help = "Forces --experimental_external_repositories."
+    )
     public boolean forceExternalRepositories;
 
     @Option(
       name = "experimental_ui",
       defaultValue = "false",
       category = "verbosity",
-      help = "Switches to an alternative progress bar that more explicitly shows progress, such "
-          + "as loaded packages and executed actions.")
+      help =
+          "Switches to an alternative progress bar that more explicitly shows progress, such "
+              + "as loaded packages and executed actions."
+    )
     public boolean experimentalUi;
 
     @Option(
       name = "experimental_ui_debug_all_events",
       defaultValue = "false",
-      category = "hidden",
+      optionUsageRestrictions = OptionUsageRestrictions.HIDDEN,
       help = "Report all events known to the experimental new Bazel UI."
     )
     public boolean experimentalUiDebugAllEvents;
diff --git a/src/main/java/com/google/devtools/build/lib/runtime/BlazeServerStartupOptions.java b/src/main/java/com/google/devtools/build/lib/runtime/BlazeServerStartupOptions.java
index 64a9da783e..f57d9d9671 100644
--- a/src/main/java/com/google/devtools/build/lib/runtime/BlazeServerStartupOptions.java
+++ b/src/main/java/com/google/devtools/build/lib/runtime/BlazeServerStartupOptions.java
@@ -19,6 +19,7 @@ import com.google.devtools.build.lib.vfs.PathFragment;
 import com.google.devtools.common.options.Converter;
 import com.google.devtools.common.options.Option;
 import com.google.devtools.common.options.OptionsBase;
+import com.google.devtools.common.options.OptionsParser.OptionUsageRestrictions;
 import java.util.Map;
 
 /**
@@ -74,21 +75,25 @@ public class BlazeServerStartupOptions extends OptionsBase {
    * responsibility of the client to compute a proper default if
    * necessary.
    */
-  @Option(name = "install_base",
-      defaultValue = "", // NOTE: purely decorative!  See class docstring.
-      category = "hidden",
-      converter = OptionsUtils.PathFragmentConverter.class,
-      help = "This launcher option is intended for use only by tests.")
+  @Option(
+    name = "install_base",
+    defaultValue = "", // NOTE: purely decorative!  See class docstring.
+    optionUsageRestrictions = OptionUsageRestrictions.HIDDEN,
+    converter = OptionsUtils.PathFragmentConverter.class,
+    help = "This launcher option is intended for use only by tests."
+  )
   public PathFragment installBase;
 
   /*
    * The installation MD5 - a content hash of the blaze binary (includes the Blaze deploy JAR and
    * any other embedded binaries - anything that ends up in the install_base).
    */
-  @Option(name = "install_md5",
-      defaultValue = "", // NOTE: purely decorative!  See class docstring.
-      category = "hidden",
-      help = "This launcher option is intended for use only by tests.")
+  @Option(
+    name = "install_md5",
+    defaultValue = "", // NOTE: purely decorative!  See class docstring.
+    optionUsageRestrictions = OptionUsageRestrictions.HIDDEN,
+    help = "This launcher option is intended for use only by tests."
+  )
   public String installMD5;
 
   /* Note: The help string in this option applies to the client code; not
@@ -96,137 +101,177 @@ public class BlazeServerStartupOptions extends OptionsBase {
    * the responsibility of the client to compute a proper default if
    * necessary.
    */
-  @Option(name = "output_base",
-      defaultValue = "null", // NOTE: purely decorative!  See class docstring.
-      category = "server startup",
-      converter = OptionsUtils.PathFragmentConverter.class,
-      valueHelp = "<path>",
-      help = "If set, specifies the output location to which all build output will be written. "
-          + "Otherwise, the location will be "
-          + "${OUTPUT_ROOT}/_blaze_${USER}/${MD5_OF_WORKSPACE_ROOT}. Note: If you specify a "
-          + "different option from one to the next Blaze invocation for this value, you'll likely "
-          + "start up a new, additional Blaze server. Blaze starts exactly one server per "
-          + "specified output base. Typically there is one output base per workspace - however, "
-          + "with this option you may have multiple output bases per workspace and thereby run "
-          + "multiple builds for the same client on the same machine concurrently. See "
-          + "'blaze help shutdown' on how to shutdown a Blaze server.")
+  @Option(
+    name = "output_base",
+    defaultValue = "null", // NOTE: purely decorative!  See class docstring.
+    category = "server startup",
+    converter = OptionsUtils.PathFragmentConverter.class,
+    valueHelp = "<path>",
+    help =
+        "If set, specifies the output location to which all build output will be written. "
+            + "Otherwise, the location will be "
+            + "${OUTPUT_ROOT}/_blaze_${USER}/${MD5_OF_WORKSPACE_ROOT}. Note: If you specify a "
+            + "different option from one to the next Blaze invocation for this value, you'll "
+            + "likely start up a new, additional Blaze server. Blaze starts exactly one server per "
+            + "specified output base. Typically there is one output base per workspace - however, "
+            + "with this option you may have multiple output bases per workspace and thereby run "
+            + "multiple builds for the same client on the same machine concurrently. See "
+            + "'blaze help shutdown' on how to shutdown a Blaze server."
+  )
   public PathFragment outputBase;
 
   /* Note: This option is only used by the C++ client, never by the Java server.
    * It is included here to make sure that the option is documented in the help
    * output, which is auto-generated by Java code.
    */
-  @Option(name = "output_user_root",
-      defaultValue = "null", // NOTE: purely decorative!  See class docstring.
-      category = "server startup",
-      converter = OptionsUtils.PathFragmentConverter.class,
-      valueHelp = "<path>",
-      help = "The user-specific directory beneath which all build outputs are written; "
-          + "by default, this is a function of $USER, but by specifying a constant, build outputs "
-          + "can be shared between collaborating users.")
+  @Option(
+    name = "output_user_root",
+    defaultValue = "null", // NOTE: purely decorative!  See class docstring.
+    category = "server startup",
+    converter = OptionsUtils.PathFragmentConverter.class,
+    valueHelp = "<path>",
+    help =
+        "The user-specific directory beneath which all build outputs are written; by default, "
+            + "this is a function of $USER, but by specifying a constant, build outputs can be "
+            + "shared between collaborating users."
+  )
   public PathFragment outputUserRoot;
 
-  @Option(name = "workspace_directory",
-      defaultValue = "",
-      category = "hidden",
-      converter = OptionsUtils.PathFragmentConverter.class,
-      help = "The root of the workspace, that is, the directory that Blaze uses as the root of the "
-          + "build. This flag is only to be set by the blaze client.")
+  @Option(
+    name = "workspace_directory",
+    defaultValue = "",
+    optionUsageRestrictions = OptionUsageRestrictions.HIDDEN,
+    converter = OptionsUtils.PathFragmentConverter.class,
+    help =
+        "The root of the workspace, that is, the directory that Blaze uses as the root of the "
+            + "build. This flag is only to be set by the blaze client."
+  )
   public PathFragment workspaceDirectory;
 
-  @Option(name = "max_idle_secs",
-      defaultValue = "" + (3 * 3600), // NOTE: purely decorative!  See class docstring.
-      category = "server startup",
-      valueHelp = "<integer>",
-      help = "The number of seconds the build server will wait idling before shutting down. Zero "
-          + "means that the server will never shutdown.")
+  @Option(
+    name = "max_idle_secs",
+    defaultValue = "" + (3 * 3600), // NOTE: purely decorative!  See class docstring.
+    category = "server startup",
+    valueHelp = "<integer>",
+    help =
+        "The number of seconds the build server will wait idling before shutting down. Zero "
+            + "means that the server will never shutdown."
+  )
   public int maxIdleSeconds;
 
-  @Option(name = "batch",
-      defaultValue = "false", // NOTE: purely decorative!  See class docstring.
-      category = "server startup",
-      help = "If set, Blaze will be run in batch mode, instead of the standard client/server mode. "
-          + "Running in batch mode prevents Blaze from caching data in memory, which makes it a "
-          + "lot slower. We recommend against using this flag.")
+  @Option(
+    name = "batch",
+    defaultValue = "false", // NOTE: purely decorative!  See class docstring.
+    category = "server startup",
+    help =
+        "If set, Blaze will be run in batch mode, instead of the standard client/server mode. "
+            + "Running in batch mode prevents Blaze from caching data in memory, which makes it a "
+            + "lot slower. We recommend against using this flag."
+  )
   public boolean batch;
 
-  @Option(name = "deep_execroot",
-      defaultValue = "true", // NOTE: purely decorative!  See class docstring.
-      category = "server startup",
-      help = "If set, the execution root will be under $OUTPUT_BASE/execroot instead of "
-          + "$OUTPUT_BASE.")
+  @Option(
+    name = "deep_execroot",
+    defaultValue = "true", // NOTE: purely decorative!  See class docstring.
+    category = "server startup",
+    help =
+        "If set, the execution root will be under $OUTPUT_BASE/execroot instead of "
+            + "$OUTPUT_BASE."
+  )
   public boolean deepExecRoot;
 
   @Option(
     name = "experimental_oom_more_eagerly",
     defaultValue = "false", // NOTE: purely decorative!  See class docstring.
     category = "server startup",
-    help = "If set, attempt to detect Java heap OOM conditions and exit before thrashing. Only "
-        + "honored when --batch is also passed. In some cases, builds that previously succeeded "
-        + "may OOM if they were close to OOMing before.")
+    help =
+        "If set, attempt to detect Java heap OOM conditions and exit before thrashing. Only "
+            + "honored when --batch is also passed. In some cases, builds that previously "
+            + "succeeded may OOM if they were close to OOMing before."
+  )
   public boolean oomMoreEagerly;
 
   @Option(
     name = "experimental_oom_more_eagerly_threshold",
     defaultValue = "100", // NOTE: purely decorative!  See class docstring.
     category = "server startup",
-    help = "If this flag is set, Blaze will OOM if, after two full GC's, more than this "
-        + "percentage of the (old gen) heap is still occupied.")
+    help =
+        "If this flag is set, Blaze will OOM if, after two full GC's, more than this "
+            + "percentage of the (old gen) heap is still occupied."
+  )
   public int oomMoreEagerlyThreshold;
 
-  @Option(name = "block_for_lock",
-      defaultValue = "true", // NOTE: purely decorative!  See class docstring.
-      category = "server startup",
-      help = "When --noblock_for_lock is passed, Blaze does not wait for a running command to "
-          + "complete, but instead exits immediately.")
+  @Option(
+    name = "block_for_lock",
+    defaultValue = "true", // NOTE: purely decorative!  See class docstring.
+    category = "server startup",
+    help =
+        "When --noblock_for_lock is passed, Blaze does not wait for a running command to "
+            + "complete, but instead exits immediately."
+  )
   public boolean blockForLock;
 
-  @Option(name = "io_nice_level",
-      defaultValue = "-1",  // NOTE: purely decorative!
-      category = "server startup",
-      valueHelp = "{-1,0,1,2,3,4,5,6,7}",
-      help = "Only on Linux; set a level from 0-7 for best-effort IO scheduling using the "
-          + "sys_ioprio_set system call. 0 is highest priority, 7 is lowest. The anticipatory "
-          + "scheduler may only honor up to priority 4. If set to a negative value, then Blaze "
-          + "does not perform a system call.")
+  @Option(
+    name = "io_nice_level",
+    defaultValue = "-1", // NOTE: purely decorative!
+    category = "server startup",
+    valueHelp = "{-1,0,1,2,3,4,5,6,7}",
+    help =
+        "Only on Linux; set a level from 0-7 for best-effort IO scheduling using the "
+            + "sys_ioprio_set system call. 0 is highest priority, 7 is lowest. The anticipatory "
+            + "scheduler may only honor up to priority 4. If set to a negative value, then Blaze "
+            + "does not perform a system call."
+  )
   public int ioNiceLevel;
 
-  @Option(name = "batch_cpu_scheduling",
-      defaultValue = "false",  // NOTE: purely decorative!
-      category = "server startup",
-      help = "Only on Linux; use 'batch' CPU scheduling for Blaze. This policy is useful for "
-          + "workloads that are non-interactive, but do not want to lower their nice value. "
-          + "See 'man 2 sched_setscheduler'. If false, then Blaze does not perform a system call.")
+  @Option(
+    name = "batch_cpu_scheduling",
+    defaultValue = "false", // NOTE: purely decorative!
+    category = "server startup",
+    help =
+        "Only on Linux; use 'batch' CPU scheduling for Blaze. This policy is useful for "
+            + "workloads that are non-interactive, but do not want to lower their nice value. "
+            + "See 'man 2 sched_setscheduler'. If false, then Blaze does not perform a system call."
+  )
   public boolean batchCpuScheduling;
 
-  @Option(name = "blazerc",
-      defaultValue = "null", // NOTE: purely decorative!
-      category = "misc",
-      valueHelp = "<path>",
-      help = "The location of the .%{product}rc file containing default values of "
-          + "Blaze command options. By default, Blaze first checks the current directory, then "
-          + "the user's home directory, and then looks for a file named .$(basename $0)rc "
-          + "(i.e. .%{product}rc). Use /dev/null to disable the search for a %{product}rc file, "
-          + "e.g. in release builds.")
+  @Option(
+    name = "blazerc",
+    defaultValue = "null", // NOTE: purely decorative!
+    category = "misc",
+    valueHelp = "<path>",
+    help =
+        "The location of the .%{product}rc file containing default values of "
+            + "Blaze command options. By default, Blaze first checks the current directory, then "
+            + "the user's home directory, and then looks for a file named .$(basename $0)rc "
+            + "(i.e. .%{product}rc). Use /dev/null to disable the search for a %{product}rc file, "
+            + "e.g. in release builds."
+  )
   public String blazerc;
 
-  @Option(name = "master_blazerc",
-      defaultValue = "true",  // NOTE: purely decorative!
-      category = "misc",
-      help = "If this option is false, the master %{product}rc next to the binary is not read.")
+  @Option(
+    name = "master_blazerc",
+    defaultValue = "true", // NOTE: purely decorative!
+    category = "misc",
+    help = "If this option is false, the master %{product}rc next to the binary is not read."
+  )
   public boolean masterBlazerc;
 
-  @Option(name = "fatal_event_bus_exceptions",
-      defaultValue = "false",  // NOTE: purely decorative!
-      category = "undocumented",
-      help = "Whether or not to exit if an exception is thrown by an internal EventBus handler.")
+  @Option(
+    name = "fatal_event_bus_exceptions",
+    defaultValue = "false", // NOTE: purely decorative!
+    optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED,
+    help = "Whether or not to exit if an exception is thrown by an internal EventBus handler."
+  )
   public boolean fatalEventBusExceptions;
 
-  @Option(name = "option_sources",
-      converter = OptionSourcesConverter.class,
-      defaultValue = "",
-      category = "hidden",
-      help = "")
+  @Option(
+    name = "option_sources",
+    converter = OptionSourcesConverter.class,
+    defaultValue = "",
+    optionUsageRestrictions = OptionUsageRestrictions.HIDDEN,
+    help = ""
+  )
   public Map<String, String> optionSources;
 
   // TODO(bazel-team): In order to make it easier to have local watchers in open source Bazel,
@@ -241,49 +286,65 @@ public class BlazeServerStartupOptions extends OptionsBase {
   )
   public boolean watchFS;
 
-  @Option(name = "invocation_policy",
-      defaultValue = "",
-      category = "undocumented",
-      help = "A base64-encoded-binary-serialized or text-formated "
-          + "invocation_policy.InvocationPolicy proto. Unlike other options, it is an error to "
-          + "specify --invocation_policy multiple times.")
+  @Option(
+    name = "invocation_policy",
+    defaultValue = "",
+    optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED,
+    help =
+        "A base64-encoded-binary-serialized or text-formated "
+            + "invocation_policy.InvocationPolicy proto. Unlike other options, it is an error to "
+            + "specify --invocation_policy multiple times."
+  )
   public String invocationPolicy;
 
-  @Option(name = "command_port",
-      defaultValue = "0",
-      category = "undocumented",
-      help = "Port to start up the gRPC command server on. If 0, let the kernel choose.")
+  @Option(
+    name = "command_port",
+    defaultValue = "0",
+    optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED,
+    help = "Port to start up the gRPC command server on. If 0, let the kernel choose."
+  )
   public int commandPort;
 
-  @Option(name = "product_name",
-      defaultValue = "bazel", // NOTE: purely decorative!
-      category = "hidden",
-      help = "The name of the build system. It is used as part of the name of the generated "
-          + "directories (e.g. productName-bin for binaries) as well as for printing error "
-          + "messages and logging")
+  @Option(
+    name = "product_name",
+    defaultValue = "bazel", // NOTE: purely decorative!
+    optionUsageRestrictions = OptionUsageRestrictions.HIDDEN,
+    help =
+        "The name of the build system. It is used as part of the name of the generated "
+            + "directories (e.g. productName-bin for binaries) as well as for printing error "
+            + "messages and logging"
+  )
   public String productName;
 
-  @Option(name = "exoblaze",
-      defaultValue = "false",
-      category = "server startup",
-      help = "If true, Blaze runs as Exoblaze")
+  @Option(
+    name = "exoblaze",
+    defaultValue = "false",
+    category = "server startup",
+    help = "If true, Blaze runs as Exoblaze"
+  )
   public boolean exoblaze;
 
-  @Option(name = "write_command_log",
-      defaultValue = "true",
-      category = "undocumented",
-      help = "Whether or not to write the command.log file")
+  @Option(
+    name = "write_command_log",
+    defaultValue = "true",
+    optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED,
+    help = "Whether or not to write the command.log file"
+  )
   public boolean writeCommandLog;
 
-  @Option(name = "client_debug",
-      defaultValue = "false", // NOTE: purely decorative!
-      category = "server startup",
-      help = "If true, log debug information from the client to stderr")
+  @Option(
+    name = "client_debug",
+    defaultValue = "false", // NOTE: purely decorative!
+    category = "server startup",
+    help = "If true, log debug information from the client to stderr"
+  )
   public boolean clientDebug;
 
-  @Option(name = "connect_timeout_secs",
-      defaultValue = "10",
-      category = "server startup",
-      help = "The amount of time the client waits for each attempt to connect to the server")
+  @Option(
+    name = "connect_timeout_secs",
+    defaultValue = "10",
+    category = "server startup",
+    help = "The amount of time the client waits for each attempt to connect to the server"
+  )
   public int connectTimeoutSecs;
 }
diff --git a/src/main/java/com/google/devtools/build/lib/runtime/CommonCommandOptions.java b/src/main/java/com/google/devtools/build/lib/runtime/CommonCommandOptions.java
index 8e6cc14b31..76d97151e2 100644
--- a/src/main/java/com/google/devtools/build/lib/runtime/CommonCommandOptions.java
+++ b/src/main/java/com/google/devtools/build/lib/runtime/CommonCommandOptions.java
@@ -19,6 +19,7 @@ import com.google.devtools.common.options.Converter;
 import com.google.devtools.common.options.Converters;
 import com.google.devtools.common.options.Option;
 import com.google.devtools.common.options.OptionsBase;
+import com.google.devtools.common.options.OptionsParser.OptionUsageRestrictions;
 import com.google.devtools.common.options.OptionsParsingException;
 import java.util.List;
 import java.util.Map;
@@ -109,167 +110,206 @@ public class CommonCommandOptions extends OptionsBase {
   )
   public Void allIncompatibleChanges;
 
-  @Option(name = "config",
-          defaultValue = "",
-          category = "misc",
-          allowMultiple = true,
-          help = "Selects additional config sections from the rc files; for every <command>, it "
-              + "also pulls in the options from <command>:<config> if such a section exists; "
-              + "if the section does not exist, this flag is ignored. "
-              + "Note that it is currently only possible to provide these options on the "
-              + "command line, not in the rc files. The config sections and flag combinations "
-              + "they are equivalent to are located in the tools/*.blazerc config files.")
+  @Option(
+    name = "config",
+    defaultValue = "",
+    category = "misc",
+    allowMultiple = true,
+    help =
+        "Selects additional config sections from the rc files; for every <command>, it "
+            + "also pulls in the options from <command>:<config> if such a section exists; "
+            + "if the section does not exist, this flag is ignored. "
+            + "Note that it is currently only possible to provide these options on the "
+            + "command line, not in the rc files. The config sections and flag combinations "
+            + "they are equivalent to are located in the tools/*.blazerc config files."
+  )
   public List<String> configs;
 
-  @Option(name = "logging",
-          defaultValue = "3", // Level.INFO
-          category = "verbosity",
-          converter = Converters.LogLevelConverter.class,
-          help = "The logging level.")
+  @Option(
+    name = "logging",
+    defaultValue = "3", // Level.INFO
+    category = "verbosity",
+    converter = Converters.LogLevelConverter.class,
+    help = "The logging level."
+  )
   public Level verbosity;
 
-  @Option(name = "client_env",
-      defaultValue = "",
-      category = "hidden",
-      converter = Converters.AssignmentConverter.class,
-      allowMultiple = true,
-      help = "A system-generated parameter which specifies the client's environment")
+  @Option(
+    name = "client_env",
+    defaultValue = "",
+    optionUsageRestrictions = OptionUsageRestrictions.HIDDEN,
+    converter = Converters.AssignmentConverter.class,
+    allowMultiple = true,
+    help = "A system-generated parameter which specifies the client's environment"
+  )
   public List<Map.Entry<String, String>> clientEnv;
 
-  @Option(name = "ignore_client_env",
-      defaultValue = "false",
-      category = "hidden",
-      deprecationWarning = "Deprecated, no-op.",
-      help = "Deprecated, no-op."
+  @Option(
+    name = "ignore_client_env",
+    defaultValue = "false",
+    optionUsageRestrictions = OptionUsageRestrictions.HIDDEN,
+    deprecationWarning = "Deprecated, no-op.",
+    help = "Deprecated, no-op."
   )
   // TODO(laszlocsomor, dslomov) 2017-03-07: remove this flag after 2017-06-01 (~3 months from now)
   // and all of its occurrences.
   public boolean ignoreClientEnv;
 
-  @Option(name = "client_cwd",
-      defaultValue = "",
-      category = "hidden",
-      converter = OptionsUtils.PathFragmentConverter.class,
-      help = "A system-generated parameter which specifies the client's working directory")
+  @Option(
+    name = "client_cwd",
+    defaultValue = "",
+    optionUsageRestrictions = OptionUsageRestrictions.HIDDEN,
+    converter = OptionsUtils.PathFragmentConverter.class,
+    help = "A system-generated parameter which specifies the client's working directory"
+  )
   public PathFragment clientCwd;
 
-  @Option(name = "announce_rc",
-      defaultValue = "false",
-      category = "verbosity",
-      help = "Whether to announce rc options.")
+  @Option(
+    name = "announce_rc",
+    defaultValue = "false",
+    category = "verbosity",
+    help = "Whether to announce rc options."
+  )
   public boolean announceRcOptions;
 
   /**
-   * These are the actual default overrides.
-   * Each value is a pair of (command name, value).
+   * These are the actual default overrides. Each value is a pair of (command name, value).
    *
-   * For example: "--default_override=build=--cpu=piii"
+   * <p>For example: "--default_override=build=--cpu=piii"
    */
-  @Option(name = "default_override",
-      defaultValue = "",
-      allowMultiple = true,
-      category = "hidden",
-      converter = OptionOverrideConverter.class,
-      help = "")
+  @Option(
+    name = "default_override",
+    defaultValue = "",
+    allowMultiple = true,
+    optionUsageRestrictions = OptionUsageRestrictions.HIDDEN,
+    converter = OptionOverrideConverter.class,
+    help = ""
+  )
   public List<OptionOverride> optionsOverrides;
 
-  /**
-   * This is the filename that the Blaze client parsed.
-   */
-  @Option(name = "rc_source",
-      defaultValue = "",
-      allowMultiple = true,
-      category = "hidden",
-      help = "")
+  /** This is the filename that the Blaze client parsed. */
+  @Option(
+    name = "rc_source",
+    defaultValue = "",
+    allowMultiple = true,
+    optionUsageRestrictions = OptionUsageRestrictions.HIDDEN,
+    help = ""
+  )
   public List<String> rcSource;
 
-  @Option(name = "always_profile_slow_operations",
-      defaultValue = "true",
-      category = "undocumented",
-      help = "Whether profiling slow operations is always turned on")
+  @Option(
+    name = "always_profile_slow_operations",
+    defaultValue = "true",
+    optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED,
+    help = "Whether profiling slow operations is always turned on"
+  )
   public boolean alwaysProfileSlowOperations;
 
-  @Option(name = "profile",
-      defaultValue = "null",
-      category = "misc",
-      converter = OptionsUtils.PathFragmentConverter.class,
-      help = "If set, profile Blaze and write data to the specified "
-      + "file. Use blaze analyze-profile to analyze the profile.")
+  @Option(
+    name = "profile",
+    defaultValue = "null",
+    category = "misc",
+    converter = OptionsUtils.PathFragmentConverter.class,
+    help =
+        "If set, profile Blaze and write data to the specified "
+            + "file. Use blaze analyze-profile to analyze the profile."
+  )
   public PathFragment profilePath;
 
-  @Option(name = "record_full_profiler_data",
-      defaultValue = "false",
-      category = "undocumented",
-      help = "By default, Blaze profiler will record only aggregated data for fast but numerous "
-          + "events (such as statting the file). If this option is enabled, profiler will record "
-          + "each event - resulting in more precise profiling data but LARGE performance "
-          + "hit. Option only has effect if --profile used as well.")
+  @Option(
+    name = "record_full_profiler_data",
+    defaultValue = "false",
+    optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED,
+    help =
+        "By default, Blaze profiler will record only aggregated data for fast but numerous "
+            + "events (such as statting the file). If this option is enabled, profiler will record "
+            + "each event - resulting in more precise profiling data but LARGE performance "
+            + "hit. Option only has effect if --profile used as well."
+  )
   public boolean recordFullProfilerData;
 
-  @Option(name = "memory_profile",
-      defaultValue = "null",
-      category = "undocumented",
-      converter = OptionsUtils.PathFragmentConverter.class,
-      help = "If set, write memory usage data to the specified "
-          + "file at phase ends.")
+  @Option(
+    name = "memory_profile",
+    defaultValue = "null",
+    optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED,
+    converter = OptionsUtils.PathFragmentConverter.class,
+    help = "If set, write memory usage data to the specified " + "file at phase ends."
+  )
   public PathFragment memoryProfilePath;
 
-  @Option(name = "gc_watchdog",
-      defaultValue = "false",
-      category = "undocumented",
-      deprecationWarning = "Ignoring: this option is no longer supported",
-      help = "Deprecated.")
+  @Option(
+    name = "gc_watchdog",
+    defaultValue = "false",
+    optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED,
+    deprecationWarning = "Ignoring: this option is no longer supported",
+    help = "Deprecated."
+  )
   public boolean gcWatchdog;
 
-  @Option(name = "startup_time",
-      defaultValue = "0",
-      category = "hidden",
-      help = "The time in ms the launcher spends before sending the request to the blaze server.")
+  @Option(
+    name = "startup_time",
+    defaultValue = "0",
+    optionUsageRestrictions = OptionUsageRestrictions.HIDDEN,
+    help = "The time in ms the launcher spends before sending the request to the blaze server."
+  )
   public long startupTime;
 
   @Option(
     name = "extract_data_time",
     defaultValue = "0",
-    category = "hidden",
+    optionUsageRestrictions = OptionUsageRestrictions.HIDDEN,
     help = "The time in ms spent on extracting the new blaze version."
   )
   public long extractDataTime;
 
-  @Option(name = "command_wait_time",
-      defaultValue = "0",
-      category = "hidden",
-      help = "The time in ms a command had to wait on a busy Blaze server process.")
+  @Option(
+    name = "command_wait_time",
+    defaultValue = "0",
+    optionUsageRestrictions = OptionUsageRestrictions.HIDDEN,
+    help = "The time in ms a command had to wait on a busy Blaze server process."
+  )
   public long waitTime;
 
-  @Option(name = "tool_tag",
-      defaultValue = "",
-      category = "misc",
-      help = "A tool name to attribute this Blaze invocation to.")
+  @Option(
+    name = "tool_tag",
+    defaultValue = "",
+    category = "misc",
+    help = "A tool name to attribute this Blaze invocation to."
+  )
   public String toolTag;
 
-  @Option(name = "restart_reason",
-      defaultValue = "no_restart",
-      category = "hidden",
-      help = "The reason for the server restart.")
+  @Option(
+    name = "restart_reason",
+    defaultValue = "no_restart",
+    optionUsageRestrictions = OptionUsageRestrictions.HIDDEN,
+    help = "The reason for the server restart."
+  )
   public String restartReason;
 
-  @Option(name = "binary_path",
-      defaultValue = "",
-      category = "hidden",
-      help = "The absolute path of the blaze binary.")
+  @Option(
+    name = "binary_path",
+    defaultValue = "",
+    optionUsageRestrictions = OptionUsageRestrictions.HIDDEN,
+    help = "The absolute path of the blaze binary."
+  )
   public String binaryPath;
 
-  @Option(name = "experimental_allow_project_files",
-      defaultValue = "false",
-      category = "hidden",
-      help = "Enable processing of +<file> parameters.")
+  @Option(
+    name = "experimental_allow_project_files",
+    defaultValue = "false",
+    optionUsageRestrictions = OptionUsageRestrictions.HIDDEN,
+    help = "Enable processing of +<file> parameters."
+  )
   public boolean allowProjectFiles;
 
-  @Option(name = "block_for_lock",
-      defaultValue = "true",
-      category = "hidden",
-      help = "If set (the default), a command will block if there is another one running. If "
-          + "unset, these commands will immediately return with an error.")
+  @Option(
+    name = "block_for_lock",
+    defaultValue = "true",
+    optionUsageRestrictions = OptionUsageRestrictions.HIDDEN,
+    help =
+        "If set (the default), a command will block if there is another one running. If "
+            + "unset, these commands will immediately return with an error."
+  )
   public boolean blockForLock;
 
 }
diff --git a/src/main/java/com/google/devtools/build/lib/runtime/commands/CanonicalizeCommand.java b/src/main/java/com/google/devtools/build/lib/runtime/commands/CanonicalizeCommand.java
index 01519a54a1..2831e6babe 100644
--- a/src/main/java/com/google/devtools/build/lib/runtime/commands/CanonicalizeCommand.java
+++ b/src/main/java/com/google/devtools/build/lib/runtime/commands/CanonicalizeCommand.java
@@ -29,6 +29,7 @@ import com.google.devtools.build.lib.util.ExitCode;
 import com.google.devtools.common.options.Option;
 import com.google.devtools.common.options.OptionsBase;
 import com.google.devtools.common.options.OptionsParser;
+import com.google.devtools.common.options.OptionsParser.OptionUsageRestrictions;
 import com.google.devtools.common.options.OptionsParsingException;
 import com.google.devtools.common.options.OptionsProvider;
 import java.util.Collection;
@@ -87,13 +88,17 @@ public final class CanonicalizeCommand implements BlazeCommand {
    * are undocumented no-ops, and are not to be used by anything outside of that test.
    */
   public static class FlagClashCanaryOptions extends OptionsBase {
-    @Option(name = "flag_clash_canary", defaultValue = "false", category = "undocumented")
+    @Option(
+      name = "flag_clash_canary",
+      defaultValue = "false",
+      optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED
+    )
     public boolean flagClashCanary;
 
     @Option(
       name = "flag_clash_canary_expander1",
       defaultValue = "null",
-      category = "undocumented",
+      optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED,
       expansion = {"--flag_clash_canary=1"}
     )
     public Void flagClashCanaryExpander1;
@@ -101,7 +106,7 @@ public final class CanonicalizeCommand implements BlazeCommand {
     @Option(
       name = "flag_clash_canary_expander2",
       defaultValue = "null",
-      category = "undocumented",
+      optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED,
       expansion = {"--flag_clash_canary=0"}
     )
     public Void flagClashCanaryExpander2;