Documentation for aspects-on-aspects.

Change-Id: If8f4c75b65d5654703a68fe70277dc597773c85d
PiperOrigin-RevId: 175737062

1 files changed, 14 insertions, 4 deletions

diff --git a/src/main/java/com/google/devtools/build/lib/analysis/skylark/SkylarkRuleClassFunctions.java b/src/main/java/com/google/devtools/build/lib/analysis/skylark/SkylarkRuleClassFunctions.java
index b0f71fa247..03d209e8dc 100644
--- a/src/main/java/com/google/devtools/build/lib/analysis/skylark/SkylarkRuleClassFunctions.java
+++ b/src/main/java/com/google/devtools/build/lib/analysis/skylark/SkylarkRuleClassFunctions.java
@@ -645,15 +645,25 @@ public class SkylarkRuleClassFunctions {
         name = "required_aspect_providers",
         type = SkylarkList.class,
         defaultValue = "[]",
-        // todo(dslomov): Document once it works.
-        doc = "<not available>"
+        doc =
+            "Allow the aspect to inspect other aspects. If the aspect propagates along "
+                + "a dependency, and the underlying rule sends a different aspect along that "
+                + "dependency, and that aspect provides one of the providers listed here, this "
+                + "aspect will see the providers provided by that aspect. "
+                + "<p>The value should be either a list of providers, or a "
+                + "list of lists of providers. This aspect will 'see'  the underlying aspects that "
+                + "provide  ALL providers from at least ONE of these lists. A single list of "
+                + "providers will be automatically converted to a list containing one list of "
+                + "providers."
       ),
       @Param(
         name = "provides",
         type = SkylarkList.class,
         defaultValue = "[]",
-        // todo(dslomov): Document once it works.
-        doc = "<not available>"
+        doc =
+            "A list of providers this aspect is guaranteed to provide. "
+                + "It is an error if a provider is listed here and the aspect "
+                + "implementation function does not return it."
       ),
       @Param(
         name = "fragments",