Skylark: documentation for targets is added and improved.

--
MOS_MIGRATED_REVID=89032399

3 files changed, 20 insertions, 6 deletions

diff --git a/src/main/java/com/google/devtools/build/docgen/SkylarkDocumentationProcessor.java b/src/main/java/com/google/devtools/build/docgen/SkylarkDocumentationProcessor.java
index 3903f2456d..9918efd9cf 100644
--- a/src/main/java/com/google/devtools/build/docgen/SkylarkDocumentationProcessor.java
+++ b/src/main/java/com/google/devtools/build/docgen/SkylarkDocumentationProcessor.java
@@ -22,6 +22,7 @@ import com.google.common.collect.Iterables;
 import com.google.devtools.build.docgen.SkylarkJavaInterfaceExplorer.SkylarkBuiltinMethod;
 import com.google.devtools.build.docgen.SkylarkJavaInterfaceExplorer.SkylarkJavaMethod;
 import com.google.devtools.build.docgen.SkylarkJavaInterfaceExplorer.SkylarkModuleDoc;
+import com.google.devtools.build.lib.analysis.TransitiveInfoCollection;
 import com.google.devtools.build.lib.packages.MethodLibrary;
 import com.google.devtools.build.lib.rules.SkylarkModules;
 import com.google.devtools.build.lib.rules.SkylarkRuleContext;
@@ -312,6 +313,7 @@ public class SkylarkDocumentationProcessor {
   private Map<SkylarkModule, Class<?>> collectBuiltinJavaObjects() {
     Map<SkylarkModule, Class<?>> modules = new HashMap<>();
     collectBuiltinModule(modules, SkylarkRuleContext.class);
+    collectBuiltinModule(modules, TransitiveInfoCollection.class);
     return modules;
   }
 
diff --git a/src/main/java/com/google/devtools/build/lib/analysis/TransitiveInfoCollection.java b/src/main/java/com/google/devtools/build/lib/analysis/TransitiveInfoCollection.java
index 82396ee310..6788ff4037 100644
--- a/src/main/java/com/google/devtools/build/lib/analysis/TransitiveInfoCollection.java
+++ b/src/main/java/com/google/devtools/build/lib/analysis/TransitiveInfoCollection.java
@@ -82,7 +82,18 @@ import javax.annotation.Nullable;
  *
  * @see TransitiveInfoProvider
  */
-@SkylarkModule(name = "target", doc = "A BUILD target.")
+@SkylarkModule(name = "Target", doc =
+      "A BUILD target. It is essentially a <code>struct</code> with the following fields:"
+    + "<ul>"
+    + "<li><h3>label</h3><code><a class=\"anchor\" href=\"#modules.Label\">Label</a> "
+    + "Target.label</code><br>The identifier of the target.</li>"
+    + "<li><h3>files</h3><code><a class=\"anchor\" href=\"#modules.set\">set</a> Target.files"
+    + "</code><br>The (transitive) set of <a class=\"anchor\" href=\"#modules.File\">File</a>s "
+    + "produced by this target.</li>"
+    + "<li><h3>Extra providers</h3>For rule targets all additional providers provided by this "
+    + "target are accessible as <code>struct</code> fields. These extra providers are defined "
+    + "in the <code>struct</code> returned by the rule implementation function.</li>"
+    + "</ul>")
 public interface TransitiveInfoCollection extends Iterable<TransitiveInfoProvider> {
 
   /**
diff --git a/src/main/java/com/google/devtools/build/lib/rules/SkylarkRuleContext.java b/src/main/java/com/google/devtools/build/lib/rules/SkylarkRuleContext.java
index d8a7fc8f08..b9c44558ba 100644
--- a/src/main/java/com/google/devtools/build/lib/rules/SkylarkRuleContext.java
+++ b/src/main/java/com/google/devtools/build/lib/rules/SkylarkRuleContext.java
@@ -323,8 +323,9 @@ public final class SkylarkRuleContext {
   @SkylarkCallable(name = "target", structField = true,
       doc = "A <code>struct</code> containing prerequisite targets defined in label type "
           + "attributes. The struct fields correspond to the attribute names. The struct value "
-          + "is always a <code>target</code> or <code>None</code>. If an optional attribute "
-          + "is not specified in the rule, the corresponding struct value is <code>None</code>.")
+          + "is always a <a href=\"#modules.Target\"><code>Target</code></a> or <code>None</code>. "
+          + "If an optional attribute is not specified in the rule, the corresponding struct "
+          + "value is <code>None</code>.")
   public SkylarkClassObject getTarget() {
     return targetObject;
   }
@@ -335,12 +336,12 @@ public final class SkylarkRuleContext {
   @SkylarkCallable(name = "targets", structField = true,
       doc = "A <code>struct</code> containing prerequisite targets defined in label or label list "
           + "type attributes. The struct fields correspond to the attribute names. The struct "
-          + "values are <code>list</code> of <code>target</code>s. If an optional attribute is "
-          + "not specified in the rule, an empty list is generated.")
+          + "values are <code>list</code> of <a href=\"#modules.Target\"><code>Target</code></a>s. "
+          + "If an optional attribute is not specified in the rule, an empty list is generated.")
   public SkylarkClassObject getTargets() {
     return targetsObject;
   }
-  
+
   @SkylarkCallable(name = "workspace_name", structField = true,
       doc = "Returns the workspace name as defined in the WORKSPACE file.")
   public String getWorkspaceName() {