Fixing documentation for platforms and toolchains.

Change-Id: I98fd671af858c402b10bb5ef59735d83d4003593
PiperOrigin-RevId: 157863146

5 files changed, 46 insertions, 14 deletions

diff --git a/src/main/java/com/google/devtools/build/docgen/BUILD b/src/main/java/com/google/devtools/build/docgen/BUILD
index 5962c16388..1c7405fdfb 100644
--- a/src/main/java/com/google/devtools/build/docgen/BUILD
+++ b/src/main/java/com/google/devtools/build/docgen/BUILD
@@ -21,6 +21,7 @@ java_library(
         "//src/main/java/com/google/devtools/build/lib/rules/apple/swift",
         "//src/main/java/com/google/devtools/build/lib/rules/cpp",
         "//src/main/java/com/google/devtools/build/lib/rules/objc",
+        "//src/main/java/com/google/devtools/build/lib/rules/platform",
         "//src/main/java/com/google/devtools/common/options",
         "//third_party:apache_velocity",
         "//third_party:guava",
diff --git a/src/main/java/com/google/devtools/build/lib/analysis/platform/ConstraintSettingInfo.java b/src/main/java/com/google/devtools/build/lib/analysis/platform/ConstraintSettingInfo.java
index daab127de5..0e12ba2597 100644
--- a/src/main/java/com/google/devtools/build/lib/analysis/platform/ConstraintSettingInfo.java
+++ b/src/main/java/com/google/devtools/build/lib/analysis/platform/ConstraintSettingInfo.java
@@ -23,6 +23,7 @@ import com.google.devtools.build.lib.packages.ClassObjectConstructor;
 import com.google.devtools.build.lib.packages.NativeClassObjectConstructor;
 import com.google.devtools.build.lib.packages.SkylarkClassObject;
 import com.google.devtools.build.lib.packages.SkylarkProviderIdentifier;
+import com.google.devtools.build.lib.skylarkinterface.SkylarkCallable;
 import com.google.devtools.build.lib.skylarkinterface.SkylarkModule;
 import com.google.devtools.build.lib.skylarkinterface.SkylarkModuleCategory;
 import com.google.devtools.build.lib.syntax.EvalException;
@@ -77,6 +78,11 @@ public class ConstraintSettingInfo extends SkylarkClassObject {
     this.label = label;
   }
 
+  @SkylarkCallable(
+    name = "label",
+    doc = "The label of the target that created this constraint.",
+    structField = true
+  )
   public Label label() {
     return label;
   }
diff --git a/src/main/java/com/google/devtools/build/lib/analysis/platform/ConstraintValueInfo.java b/src/main/java/com/google/devtools/build/lib/analysis/platform/ConstraintValueInfo.java
index ca6ad9b2dd..be11feaba6 100644
--- a/src/main/java/com/google/devtools/build/lib/analysis/platform/ConstraintValueInfo.java
+++ b/src/main/java/com/google/devtools/build/lib/analysis/platform/ConstraintValueInfo.java
@@ -23,6 +23,7 @@ import com.google.devtools.build.lib.packages.ClassObjectConstructor;
 import com.google.devtools.build.lib.packages.NativeClassObjectConstructor;
 import com.google.devtools.build.lib.packages.SkylarkClassObject;
 import com.google.devtools.build.lib.packages.SkylarkProviderIdentifier;
+import com.google.devtools.build.lib.skylarkinterface.SkylarkCallable;
 import com.google.devtools.build.lib.skylarkinterface.SkylarkModule;
 import com.google.devtools.build.lib.skylarkinterface.SkylarkModuleCategory;
 import com.google.devtools.build.lib.syntax.EvalException;
@@ -31,7 +32,7 @@ import com.google.devtools.build.lib.syntax.SkylarkType;
 
 /** Provider for a platform constraint value that fulfills a {@link ConstraintSettingInfo}. */
 @SkylarkModule(
-  name = "ConstraintValueProvider",
+  name = "ConstraintValueInfo",
   doc = "A value for a constraint setting that can be used to define a platform.",
   category = SkylarkModuleCategory.PROVIDER
 )
@@ -87,10 +88,22 @@ public class ConstraintValueInfo extends SkylarkClassObject {
     this.label = label;
   }
 
+  @SkylarkCallable(
+    name = "constraint",
+    doc =
+        "The <a href=\"ConstraintSettingInfo.html\">ConstraintSettingInfo</a> this value can be "
+            + "applied to.",
+    structField = true
+  )
   public ConstraintSettingInfo constraint() {
     return constraint;
   }
 
+  @SkylarkCallable(
+    name = "label",
+    doc = "The label of the target that created this constraint value.",
+    structField = true
+  )
   public Label label() {
     return label;
   }
diff --git a/src/main/java/com/google/devtools/build/lib/analysis/platform/PlatformInfo.java b/src/main/java/com/google/devtools/build/lib/analysis/platform/PlatformInfo.java
index c800415020..f8b44d91a8 100644
--- a/src/main/java/com/google/devtools/build/lib/analysis/platform/PlatformInfo.java
+++ b/src/main/java/com/google/devtools/build/lib/analysis/platform/PlatformInfo.java
@@ -100,6 +100,13 @@ public class PlatformInfo extends SkylarkClassObject {
     this.remoteExecutionProperties = remoteExecutionProperties;
   }
 
+  @SkylarkCallable(
+    name = "constraints",
+    doc =
+        "The <a href=\"ConstraintValueInfo.html\">ConstraintValueInfo</a> instances that define "
+            + "this platform.",
+    structField = true
+  )
   public ImmutableList<ConstraintValueInfo> constraints() {
     return constraints;
   }
diff --git a/src/main/java/com/google/devtools/build/lib/rules/platform/PlatformCommon.java b/src/main/java/com/google/devtools/build/lib/rules/platform/PlatformCommon.java
index 5a4a25924c..5a4bfb82dc 100644
--- a/src/main/java/com/google/devtools/build/lib/rules/platform/PlatformCommon.java
+++ b/src/main/java/com/google/devtools/build/lib/rules/platform/PlatformCommon.java
@@ -29,16 +29,18 @@ import com.google.devtools.build.lib.syntax.BuiltinFunction;
 import com.google.devtools.build.lib.syntax.EvalException;
 import com.google.devtools.build.lib.syntax.SkylarkSignatureProcessor;
 
-/** Skylark namespace used to interact with Blaze's platform APIs. */
+/** Skylark namespace used to interact with the platform APIs. */
 @SkylarkModule(
   name = "platform_common",
-  doc = "Functions for Skylark to interact with Blaze's platform APIs."
+  doc = "Functions for Skylark to interact with the platform APIs."
 )
 public class PlatformCommon {
 
   @SkylarkCallable(
     name = PlatformInfo.SKYLARK_NAME,
-    doc = "The key used to retrieve the provider containing platform_info's value.",
+    doc =
+        "The provider constructor for PlatformInfo. The constructor takes the list of "
+            + "ConstraintValueInfo providers that defines the platform.",
     structField = true
   )
   public ClassObjectConstructor getPlatformInfoConstructor() {
@@ -47,7 +49,9 @@ public class PlatformCommon {
 
   @SkylarkCallable(
     name = ConstraintSettingInfo.SKYLARK_NAME,
-    doc = "The key used to retrieve the provider containing constraint_setting_info's value.",
+    doc =
+        "The provider constructor for ConstraintSettingInfo. The constructor takes the label that "
+            + "uniquely identifies the constraint (and which should always be ctx.label).",
     structField = true
   )
   public ClassObjectConstructor getConstraintSettingInfoConstructor() {
@@ -56,25 +60,27 @@ public class PlatformCommon {
 
   @SkylarkCallable(
     name = ConstraintValueInfo.SKYLARK_NAME,
-    doc = "The key used to retrieve the provider containing constraint_value_info's value.",
+    doc =
+        "The provider constructor for ConstraintValueInfo. The constructor takes the label that "
+            + "uniquely identifies the constraint value (and which should always be ctx.label), "
+            + "and the ConstraintSettingInfo which the value belongs to.",
     structField = true
   )
   public ClassObjectConstructor getConstraintValueInfoConstructor() {
     return ConstraintValueInfo.SKYLARK_CONSTRUCTOR;
   }
 
-  @SkylarkCallable(
-    name = ToolchainInfo.SKYLARK_NAME,
-    doc = "The key used to retrieve the provider containing toolchain data.",
-    structField = true
-  )
+  @SkylarkCallable(name = ToolchainInfo.SKYLARK_NAME, documented = false, structField = true)
   public ClassObjectConstructor getToolchainInfoConstructor() {
     return ToolchainInfo.SKYLARK_CONSTRUCTOR;
   }
 
   @SkylarkSignature(
     name = "toolchain_type",
-    doc = "",
+    doc =
+        "Creates a new ToolchainConstructor instance, which can be used to create new "
+            + "ToolchainInfo instances. The constructor takes a list of execution constraints, a "
+            + "list of target constraints, and then other data which may be used by a rule author.",
     documented = false,
     objectType = PlatformCommon.class,
     returnType = ToolchainConstructor.class,
@@ -86,8 +92,7 @@ public class PlatformCommon {
   private static final BuiltinFunction createToolchainType =
       new BuiltinFunction("toolchain_type") {
         @SuppressWarnings("unchecked")
-        public ToolchainConstructor invoke(PlatformCommon self, Location loc)
-            throws EvalException {
+        public ToolchainConstructor invoke(PlatformCommon self, Location loc) throws EvalException {
           return new SkylarkToolchainConstructor(loc);
         }
       };