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 036e747..5d56cf3 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.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 @@
 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 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 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 21d3d38..b02bf3b 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.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 @@
    * 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 c38cfc2..8c733c5 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.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 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 @@
      * 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 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 @@
     @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 @@
       }
     }
 
-    @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 84b1fa2..3fdf939 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.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 6c1a124..37298bf 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.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 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 67618a3..da3805e 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 @@
 
 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 @@
   @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 @@
   @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 @@
   @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 577be35..0f93ccc 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.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 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 @@
     @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 c2b40c0..1b0bb10 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.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 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 @@
   @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 @@
   @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 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 e36136b..14fe8b1 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 @@
 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 @@
  */
 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 b67ecee..4906aec 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.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 @@
  * 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 @@
   // 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 8237e84..626d76f 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.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 @@
     }
   }
 
-  @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 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 e17fa48..34ba0d4 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.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 @@
     }
   }
 
-  @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 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 @@
     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 b7e543e..3cfa842 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.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 @@
     }
   }
 
-  /**
-   * 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 @@
       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 @@
       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 f588ff50..23977e1 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.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 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 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;  
+  )
+  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")
+  @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 @@
   // 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 @@
     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 @@
   @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 3d751c1..dbb913d 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.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 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 19af5fd..baa5bfe 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.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 @@
   @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 @@
     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 1fa3fbf..f64373d 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.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 @@
     }
   }
 
-  @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 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 @@
   @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 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 @@
   // 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 @@
   @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 @@
   @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 @@
   @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 @@
   @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 @@
   @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 @@
   @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 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 @@
   @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 @@
   @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 @@
   @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 14d5136..8ccf030 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.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 @@
  * (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 514e2a0..1e45d7b 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.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 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 @@
   @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 @@
   @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 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 @@
     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 @@
   }
 
   @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 @@
     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 @@
   @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 @@
   @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 @@
   @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 601f37f..f1906fa 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.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 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 64a9da7..f57d9d9 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.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 @@
    * 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 @@
    * 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 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 8e6cc14..76d9715 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.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 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 01519a5..2831e6b 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.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 @@
    * 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 @@
     @Option(
       name = "flag_clash_canary_expander2",
       defaultValue = "null",
-      category = "undocumented",
+      optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED,
       expansion = {"--flag_clash_canary=0"}
     )
     public Void flagClashCanaryExpander2;
diff --git a/src/test/java/com/google/devtools/build/lib/analysis/LateBoundSplitUtil.java b/src/test/java/com/google/devtools/build/lib/analysis/LateBoundSplitUtil.java
index ce01c8f..2e29666 100644
--- a/src/test/java/com/google/devtools/build/lib/analysis/LateBoundSplitUtil.java
+++ b/src/test/java/com/google/devtools/build/lib/analysis/LateBoundSplitUtil.java
@@ -34,7 +34,7 @@
 import com.google.devtools.build.lib.testutil.UnknownRuleConfiguredTarget;
 import com.google.devtools.build.lib.util.FileTypeSet;
 import com.google.devtools.common.options.Option;
-
+import com.google.devtools.common.options.OptionsParser.OptionUsageRestrictions;
 import java.util.List;
 
 /**
@@ -48,7 +48,7 @@
     @Option(
       name = "foo",
       defaultValue = "",
-      category = "undocumented"
+      optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED
     )
     public String fooFlag;
 
diff --git a/src/test/java/com/google/devtools/build/lib/rules/config/ConfigSettingTest.java b/src/test/java/com/google/devtools/build/lib/rules/config/ConfigSettingTest.java
index 33514d3..6aed492 100644
--- a/src/test/java/com/google/devtools/build/lib/rules/config/ConfigSettingTest.java
+++ b/src/test/java/com/google/devtools/build/lib/rules/config/ConfigSettingTest.java
@@ -34,6 +34,7 @@
 import com.google.devtools.build.lib.testutil.TestConstants;
 import com.google.devtools.build.lib.testutil.TestRuleClassProvider;
 import com.google.devtools.common.options.Option;
+import com.google.devtools.common.options.OptionsParser.OptionUsageRestrictions;
 import java.util.Map;
 import org.junit.Test;
 import org.junit.runner.RunWith;
@@ -86,7 +87,11 @@
   public static class InternalTestOptions extends FragmentOptions {
     public InternalTestOptions() {}
 
-    @Option(name = "internal_option", defaultValue = "super secret", category = "internal")
+    @Option(
+      name = "internal_option",
+      defaultValue = "super secret",
+      optionUsageRestrictions = OptionUsageRestrictions.INTERNAL
+    )
     public String optwithDefault;
   }
 
diff --git a/src/tools/android/java/com/google/devtools/build/android/desugar/Desugar.java b/src/tools/android/java/com/google/devtools/build/android/desugar/Desugar.java
index a94570d..797cbc4 100644
--- a/src/tools/android/java/com/google/devtools/build/android/desugar/Desugar.java
+++ b/src/tools/android/java/com/google/devtools/build/android/desugar/Desugar.java
@@ -29,6 +29,7 @@
 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.errorprone.annotations.MustBeClosed;
 import java.io.IOException;
 import java.io.InputStream;
@@ -61,8 +62,8 @@
       converter = ExistingPathConverter.class,
       abbrev = 'i',
       help =
-        "Input Jar or directory with classes to desugar (required, the n-th input is paired with"
-        + "the n-th output)."
+          "Input Jar or directory with classes to desugar (required, the n-th input is paired with"
+              + "the n-th output)."
     )
     public List<Path> inputJars;
 
@@ -74,7 +75,7 @@
       converter = ExistingPathConverter.class,
       help =
           "Ordered classpath (Jar or directory) to resolve symbols in the --input Jar, like "
-          + "javac's -cp flag."
+              + "javac's -cp flag."
     )
     public List<Path> classpath;
 
@@ -84,15 +85,16 @@
       defaultValue = "",
       category = "input",
       converter = ExistingPathConverter.class,
-      help = "Bootclasspath that was used to compile the --input Jar with, like javac's "
-          + "-bootclasspath flag (required)."
+      help =
+          "Bootclasspath that was used to compile the --input Jar with, like javac's "
+              + "-bootclasspath flag (required)."
     )
     public List<Path> bootclasspath;
 
     @Option(
       name = "allow_empty_bootclasspath",
       defaultValue = "false",
-      category = "undocumented"
+      optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED
     )
     public boolean allowEmptyBootclasspath;
 
@@ -101,7 +103,7 @@
       defaultValue = "false",
       help =
           "A temporary flag specifically for android lint, subject to removal anytime (DO NOT USE)",
-      category = "undocumented"
+      optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED
     )
     public boolean onlyDesugarJavac9ForLint;
 
@@ -154,7 +156,7 @@
     @Option(
       name = "core_library",
       defaultValue = "false",
-      category = "undocumented",
+      optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED,
       implicitRequirements = "--allow_empty_bootclasspath",
       help = "Enables rewriting to desugar java.* classes."
     )
diff --git a/src/tools/android/java/com/google/devtools/build/android/dexer/DexBuilder.java b/src/tools/android/java/com/google/devtools/build/android/dexer/DexBuilder.java
index b22b9a6..63f8ec4 100644
--- a/src/tools/android/java/com/google/devtools/build/android/dexer/DexBuilder.java
+++ b/src/tools/android/java/com/google/devtools/build/android/dexer/DexBuilder.java
@@ -32,6 +32,7 @@
 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 java.io.BufferedOutputStream;
 import java.io.ByteArrayOutputStream;
@@ -60,32 +61,40 @@
    * Commandline options.
    */
   public static class Options extends OptionsBase {
-    @Option(name = "input_jar",
-        defaultValue = "null",
-        category = "input",
-        converter = ExistingPathConverter.class,
-        abbrev = 'i',
-        help = "Input file to read classes and jars from.")
+    @Option(
+      name = "input_jar",
+      defaultValue = "null",
+      category = "input",
+      converter = ExistingPathConverter.class,
+      abbrev = 'i',
+      help = "Input file to read classes and jars from."
+    )
     public Path inputJar;
 
-    @Option(name = "output_zip",
-        defaultValue = "null",
-        category = "output",
-        converter = PathConverter.class,
-        abbrev = 'o',
-        help = "Output file to write.")
+    @Option(
+      name = "output_zip",
+      defaultValue = "null",
+      category = "output",
+      converter = PathConverter.class,
+      abbrev = 'o',
+      help = "Output file to write."
+    )
     public Path outputZip;
 
-    @Option(name = "max_threads",
-        defaultValue = "8",
-        category = "misc",
-        help = "How many threads (besides the main thread) to use at most.")
+    @Option(
+      name = "max_threads",
+      defaultValue = "8",
+      category = "misc",
+      help = "How many threads (besides the main thread) to use at most."
+    )
     public int maxThreads;
 
-    @Option(name = "persistent_worker",
-        defaultValue = "false",
-        category = "hidden",
-        help = "Run as a Bazel persistent worker.")
+    @Option(
+      name = "persistent_worker",
+      defaultValue = "false",
+      optionUsageRestrictions = OptionUsageRestrictions.HIDDEN,
+      help = "Run as a Bazel persistent worker."
+    )
     public boolean persistentWorker;
   }
 
diff --git a/src/tools/android/java/com/google/devtools/build/android/dexer/DexFileMerger.java b/src/tools/android/java/com/google/devtools/build/android/dexer/DexFileMerger.java
index 3841ac3..0a68efb 100644
--- a/src/tools/android/java/com/google/devtools/build/android/dexer/DexFileMerger.java
+++ b/src/tools/android/java/com/google/devtools/build/android/dexer/DexFileMerger.java
@@ -33,6 +33,7 @@
 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 java.io.BufferedOutputStream;
 import java.io.IOException;
 import java.io.InputStream;
@@ -61,63 +62,81 @@
    * Commandline options.
    */
   public static class Options extends OptionsBase {
-    @Option(name = "input",
-        defaultValue = "null",
-        category = "input",
-        converter = ExistingPathConverter.class,
-        abbrev = 'i',
-        help = "Input file to read to aggregate.")
+    @Option(
+      name = "input",
+      defaultValue = "null",
+      category = "input",
+      converter = ExistingPathConverter.class,
+      abbrev = 'i',
+      help = "Input file to read to aggregate."
+    )
     public Path inputArchive;
 
-    @Option(name = "output",
-        defaultValue = "classes.dex.jar",
-        category = "output",
-        converter = PathConverter.class,
-        abbrev = 'o',
-        help = "Output archive to write.")
+    @Option(
+      name = "output",
+      defaultValue = "classes.dex.jar",
+      category = "output",
+      converter = PathConverter.class,
+      abbrev = 'o',
+      help = "Output archive to write."
+    )
     public Path outputArchive;
 
-    @Option(name = "multidex",
-        defaultValue = "off",
-        category = "multidex",
-        converter = MultidexStrategyConverter.class,
-        help = "Allow more than one .dex file in the output.")
+    @Option(
+      name = "multidex",
+      defaultValue = "off",
+      category = "multidex",
+      converter = MultidexStrategyConverter.class,
+      help = "Allow more than one .dex file in the output."
+    )
     public MultidexStrategy multidexMode;
 
-    @Option(name = "main-dex-list",
-        defaultValue = "null",
-        category = "multidex",
-        converter = ExistingPathConverter.class,
-        implicitRequirements = "--multidex=minimal",
-        help = "List of classes to be placed into \"main\" classes.dex file.")
+    @Option(
+      name = "main-dex-list",
+      defaultValue = "null",
+      category = "multidex",
+      converter = ExistingPathConverter.class,
+      implicitRequirements = "--multidex=minimal",
+      help = "List of classes to be placed into \"main\" classes.dex file."
+    )
     public Path mainDexListFile;
 
-    @Option(name = "minimal-main-dex",
-        defaultValue = "false",
-        category = "multidex",
-        implicitRequirements = "--multidex=minimal",
-        help = "If true, *only* classes listed in --main_dex_list file are placed into \"main\" "
-            + "classes.dex file.")
+    @Option(
+      name = "minimal-main-dex",
+      defaultValue = "false",
+      category = "multidex",
+      implicitRequirements = "--multidex=minimal",
+      help =
+          "If true, *only* classes listed in --main_dex_list file are placed into \"main\" "
+              + "classes.dex file."
+    )
     public boolean minimalMainDex;
 
-    @Option(name = "verbose",
-        defaultValue = "false",
-        category = "misc",
-        help = "If true, print information about the merged files and resulting files to stdout.")
+    @Option(
+      name = "verbose",
+      defaultValue = "false",
+      category = "misc",
+      help = "If true, print information about the merged files and resulting files to stdout."
+    )
     public boolean verbose;
 
-    @Option(name = "max-bytes-wasted-per-file",
-        defaultValue = "0",
-        category = "misc",
-        help = "Limit on conservatively allocated but unused bytes per dex file, which can enable "
-            + "faster merging.")
+    @Option(
+      name = "max-bytes-wasted-per-file",
+      defaultValue = "0",
+      category = "misc",
+      help =
+          "Limit on conservatively allocated but unused bytes per dex file, which can enable "
+              + "faster merging."
+    )
     public int wasteThresholdPerDex;
 
     // Undocumented dx option for testing multidex logic
-    @Option(name = "set-max-idx-number",
-        defaultValue = "" + (DexFormat.MAX_MEMBER_IDX + 1),
-        category = "undocumented",
-        help = "Limit on fields and methods in a single dex file.")
+    @Option(
+      name = "set-max-idx-number",
+      defaultValue = "" + (DexFormat.MAX_MEMBER_IDX + 1),
+      optionUsageRestrictions = OptionUsageRestrictions.UNDOCUMENTED,
+      help = "Limit on fields and methods in a single dex file."
+    )
     public int maxNumberOfIdxPerDex;
   }