Expose platform flags for documentation purposes.

Also remove experimental tag from platform and toolchain flags in docs.

Fixes #4372.

Change-Id: I4e8f29273b52fbaabf9c97d1a7563f817601653f
PiperOrigin-RevId: 180678722

3 files changed, 36 insertions, 21 deletions

diff --git a/site/docs/platforms.md b/site/docs/platforms.md
index d8102c1c52..8cdc3d7e3f 100644
--- a/site/docs/platforms.md
+++ b/site/docs/platforms.md
@@ -124,9 +124,9 @@ In these definitions, the CPU architecture constraint values are pulled from the
 To select a specific host and target platform for a build, use the following
 command-line flags:
 
-*  `--experimental_host_platform` - defaults to `@bazel_tools//platforms:host_platform`
+*  `--host_platform` - defaults to `@bazel_tools//platforms:host_platform`
 
-*  `--experimental_platforms` - defaults to `@bazel_tools//platforms:target_platform`
+*  `--platforms` - defaults to `@bazel_tools//platforms:target_platform`
 
 Platforms can also be used with the `config_setting` rule to define configurable
 attributes. See [config_setting](be/general.html#config_setting) for more
diff --git a/site/docs/toolchains.md b/site/docs/toolchains.md
index f5c910eea2..96f012becf 100644
--- a/site/docs/toolchains.md
+++ b/site/docs/toolchains.md
@@ -31,7 +31,7 @@ When a target requests a toolchain, Bazel checks the list of registered
 toolchains and creates a dependency from the target to the first matching
 toolchain it finds. To find a matching toolchain, Bazel does the following:
 
-1.  Looks through the registered toolchains, first from the `--experimental_extra_toolchains`
+1.  Looks through the registered toolchains, first from the `--extra_toolchains`
     flag, then from the `registered_toolchains` calls in the project's
     `WORKSPACE` file.
 
@@ -147,7 +147,7 @@ toolchain(
 
 Once the toolchain rule and definition exist, register the toolchain to make
 Bazel aware of it. You can register a toolchain either via the project's
-`WORKSPACE` file or specify it in the `--experimental_extra_toolchains` flag.
+`WORKSPACE` file or specify it in the `--extra_toolchains` flag.
 
 Below is an example toolchain registration in a `WORKSPACE` file:
 
diff --git a/src/main/java/com/google/devtools/build/lib/analysis/PlatformOptions.java b/src/main/java/com/google/devtools/build/lib/analysis/PlatformOptions.java
index 9ae6e2d765..a3aa9f7f81 100644
--- a/src/main/java/com/google/devtools/build/lib/analysis/PlatformOptions.java
+++ b/src/main/java/com/google/devtools/build/lib/analysis/PlatformOptions.java
@@ -29,7 +29,6 @@ import com.google.devtools.common.options.Converter;
 import com.google.devtools.common.options.Option;
 import com.google.devtools.common.options.OptionDocumentationCategory;
 import com.google.devtools.common.options.OptionEffectTag;
-import com.google.devtools.common.options.OptionMetadataTag;
 import com.google.devtools.common.options.OptionsParsingException;
 import com.google.protobuf.CodedInputStream;
 import com.google.protobuf.CodedOutputStream;
@@ -46,10 +45,13 @@ public class PlatformOptions extends FragmentOptions {
     oldName = "experimental_host_platform",
     converter = BuildConfiguration.EmptyToNullLabelConverter.class,
     defaultValue = "@bazel_tools//platforms:host_platform",
-    documentationCategory = OptionDocumentationCategory.UNDOCUMENTED,
-    effectTags = {OptionEffectTag.UNKNOWN},
-    metadataTags = {OptionMetadataTag.HIDDEN},
-    help = "Declare the platform the build is started from"
+    documentationCategory = OptionDocumentationCategory.TOOLCHAIN,
+    effectTags = {
+      OptionEffectTag.AFFECTS_OUTPUTS,
+      OptionEffectTag.CHANGES_INPUTS,
+      OptionEffectTag.LOADING_AND_ANALYSIS
+    },
+    help = "The label of a platform rule that describes the host system."
   )
   public Label hostPlatform;
 
@@ -60,10 +62,14 @@ public class PlatformOptions extends FragmentOptions {
     oldName = "experimental_platforms",
     converter = BuildConfiguration.LabelListConverter.class,
     defaultValue = "@bazel_tools//platforms:target_platform",
-    documentationCategory = OptionDocumentationCategory.UNDOCUMENTED,
-    effectTags = {OptionEffectTag.UNKNOWN},
-    metadataTags = {OptionMetadataTag.HIDDEN},
-    help = "Declare the platforms targeted by the current build"
+    documentationCategory = OptionDocumentationCategory.TOOLCHAIN,
+    effectTags = {
+      OptionEffectTag.AFFECTS_OUTPUTS,
+      OptionEffectTag.CHANGES_INPUTS,
+      OptionEffectTag.LOADING_AND_ANALYSIS
+    },
+    help =
+        "The labels of the platform rules describing the target platforms for the current command."
   )
   public List<Label> platforms;
 
@@ -71,10 +77,16 @@ public class PlatformOptions extends FragmentOptions {
     name = "extra_toolchains",
     converter = LabelListConverter.class,
     defaultValue = "",
-    documentationCategory = OptionDocumentationCategory.UNDOCUMENTED,
-    effectTags = {OptionEffectTag.UNKNOWN},
-    metadataTags = {OptionMetadataTag.HIDDEN},
-    help = "Extra toolchains to be considered during toolchain resolution."
+    documentationCategory = OptionDocumentationCategory.TOOLCHAIN,
+    effectTags = {
+      OptionEffectTag.AFFECTS_OUTPUTS,
+      OptionEffectTag.CHANGES_INPUTS,
+      OptionEffectTag.LOADING_AND_ANALYSIS
+    },
+    help =
+        "The labels of toolchain rules to be considered during toolchain resolution. "
+            + "These toolchains will be considered before those declared in the WORKSPACE file by "
+            + "register_toolchains()."
   )
   public List<Label> extraToolchains;
 
@@ -83,9 +95,12 @@ public class PlatformOptions extends FragmentOptions {
     converter = ToolchainResolutionOverrideConverter.class,
     allowMultiple = true,
     defaultValue = "",
-    documentationCategory = OptionDocumentationCategory.UNDOCUMENTED,
-    effectTags = {OptionEffectTag.UNKNOWN},
-    metadataTags = {OptionMetadataTag.HIDDEN},
+    documentationCategory = OptionDocumentationCategory.TOOLCHAIN,
+    effectTags = {
+      OptionEffectTag.AFFECTS_OUTPUTS,
+      OptionEffectTag.CHANGES_INPUTS,
+      OptionEffectTag.LOADING_AND_ANALYSIS
+    },
     help =
         "Override toolchain resolution for a toolchain type with a specific toolchain. "
             + "Example: --toolchain_resolution_override=@io_bazel_rules_go//:toolchain="
@@ -109,7 +124,7 @@ public class PlatformOptions extends FragmentOptions {
     defaultValue = "",
     converter = LabelListConverter.class,
     category = "semantics",
-    documentationCategory = OptionDocumentationCategory.UNCATEGORIZED,
+    documentationCategory = OptionDocumentationCategory.TOOLCHAIN,
     effectTags = {OptionEffectTag.LOADING_AND_ANALYSIS},
     help = "Signals that the given rule categories use platform-based toolchain resolution"
   )