Document declared providers.

Change-Id: Ifdc1773fb1439c16327bb84961998793a942e666
PiperOrigin-RevId: 154151084

2 files changed, 41 insertions, 21 deletions

diff --git a/src/main/java/com/google/devtools/build/lib/packages/ClassObjectConstructor.java b/src/main/java/com/google/devtools/build/lib/packages/ClassObjectConstructor.java
index e2e0ccf7b0..8275e6a69d 100644
--- a/src/main/java/com/google/devtools/build/lib/packages/ClassObjectConstructor.java
+++ b/src/main/java/com/google/devtools/build/lib/packages/ClassObjectConstructor.java
@@ -27,19 +27,37 @@ import javax.annotation.Nullable;
 /**
  * Declared Provider (a constructor for {@link SkylarkClassObject}).
  *
- * Declared providers can be declared either natively ({@link NativeClassObjectConstructor}
- * or in Skylark {@link SkylarkClassObjectConstructor}.
+ * <p>Declared providers can be declared either natively ({@link NativeClassObjectConstructor} or in
+ * Skylark {@link SkylarkClassObjectConstructor}.
  *
- * {@link ClassObjectConstructor} serves both as "type identifier" for declared provider
+ * <p>{@link ClassObjectConstructor} serves both as "type identifier" for declared provider
  * instances and as a function that can be called to construct a provider.
  *
- * Prefer to use {@link Key} as a serializable identifier of {@link ClassObjectConstructor}.
- * In particular, {@link Key} should be used in all data structures exposed to Skyframe.
+ * <p>Prefer to use {@link Key} as a serializable identifier of {@link ClassObjectConstructor}. In
+ * particular, {@link Key} should be used in all data structures exposed to Skyframe.
  */
-@SkylarkModule(name = "provider",
-    doc = "A constructor for simple value objects. "
-        + "See the global <a href=\"globals.html#provider\">provider</a> function "
-        + "for more details."
+@SkylarkModule(
+  name = "Provider",
+  doc =
+      "A constructor for simple value objects, known as provider instances."
+          + "<br>"
+          + "This value has a dual purpose:"
+          + "  <ul>"
+          + "     <li>It is a function that can be called to construct 'struct'-like values:"
+          + "<pre class=\"language-python\">DataInfo = provider()\n"
+          + "d = DataInfo(x = 2, y = 3)\n"
+          + "print(d.x + d.y) # prints 5</pre>"
+          + "     <i>Some providers, defined internally, do not allow instance creation</i>"
+          + "     </li>"
+          + "     <li>It is a <i>key</i> to access a provider instance on a"
+          + "        <a href=\"lib/Target.html\">Target</a>"
+          + "<pre class=\"language-python\">DataInfo = provider()\n"
+          + "def _rule_impl(ctx)\n"
+          + "  ... ctx.attr.dep[DataInfo]</pre>"
+          + "     </li>"
+          + "  </ul>"
+          + "Create a new <code>Provider</code> using the "
+          + "<a href=\"globals.html#provider\">provider</a> function."
 )
 @Immutable
 public abstract class ClassObjectConstructor extends BaseFunction {
diff --git a/src/main/java/com/google/devtools/build/lib/rules/SkylarkRuleClassFunctions.java b/src/main/java/com/google/devtools/build/lib/rules/SkylarkRuleClassFunctions.java
index 24803c108a..aefdfaf3c9 100644
--- a/src/main/java/com/google/devtools/build/lib/rules/SkylarkRuleClassFunctions.java
+++ b/src/main/java/com/google/devtools/build/lib/rules/SkylarkRuleClassFunctions.java
@@ -194,16 +194,18 @@ public class SkylarkRuleClassFunctions {
   @SkylarkSignature(
     name = "DefaultInfo",
     returnType = ClassObjectConstructor.class,
-    doc = "A provider that is provided by every rule, even if it iss not returned explicitly. "
-        + "A <code>DefaultInfo</code> accepts all special parameters that can be returned "
-        + "from rule implementation function in a struct, which are <code>runfiles</code>, "
-        + "<code>data_runfiles</code>, <code>default_runfiles</code>, "
-        + "<code>output_groups</code>, <code>instrumented_files</code>, and all "
-        + "<a href=\"skylark-provider.html\">providers</a> that are available on built-in rules. "
-        + "Each instance of the default provider contains the following standard fields: "
-        + "<code>data_runfiles</code>, <code>default_runfiles</code>, <code>files</code>, "
-        + "and <code>files_to_run</code>. The values of these fields are equivalent to the "
-        + "values of the corresponding fields of the target the default provider belongs to."
+    doc =
+        "A provider that is provided by every rule, even if it iss not returned explicitly. "
+            + "A <code>DefaultInfo</code> accepts all special parameters that can be returned "
+            + "from rule implementation function in a struct, which are <code>runfiles</code>, "
+            + "<code>data_runfiles</code>, <code>default_runfiles</code>, <code>files</code>, "
+            + "<code>output_groups</code>, <code>instrumented_files</code>, and all "
+            + "<a href=\"skylark-provider.html\">providers</a> that are available on built-in " 
+            + "rules. Each instance of the default provider contains the following standard "
+            + "fields: <code>data_runfiles</code>, <code>default_runfiles</code>, "
+            + "<code>files</code>, and <code>files_to_run</code>. The values of these fields "
+            + "are equivalent to the values of the corresponding fields of the target "
+            + "the default provider belongs to."
   )
   private static final ClassObjectConstructor defaultInfo = DefaultProvider.SKYLARK_CONSTRUCTOR;
 
@@ -226,7 +228,7 @@ public class SkylarkRuleClassFunctions {
   )
   private static final ClassObjectConstructor actions = ActionsProvider.SKYLARK_CONSTRUCTOR;
 
-  @SkylarkSignature(name = "provider", returnType = SkylarkClassObjectConstructor.class, doc =
+  @SkylarkSignature(name = "provider", returnType = ClassObjectConstructor.class, doc =
       "Creates a declared provider 'constructor'. The return value of this"
           + "function can be used to create \"struct-like\" values. Example:<br>"
           + "<pre class=\"language-python\">data = provider()\n"
@@ -236,7 +238,7 @@ public class SkylarkRuleClassFunctions {
   )
   private static final BuiltinFunction provider =
       new BuiltinFunction("provider") {
-        public SkylarkClassObjectConstructor invoke(Location location) {
+        public ClassObjectConstructor invoke(Location location) {
           return new SkylarkClassObjectConstructor(
               "<no name>", // name is set on export.
               location);