Add an overview comment about how the analysis phase works and some pointers to it.
--
MOS_MIGRATED_REVID=122718503
diff --git a/src/main/java/com/google/devtools/build/lib/analysis/ConfiguredAspect.java b/src/main/java/com/google/devtools/build/lib/analysis/ConfiguredAspect.java
index 7f3db2a..402668a 100644
--- a/src/main/java/com/google/devtools/build/lib/analysis/ConfiguredAspect.java
+++ b/src/main/java/com/google/devtools/build/lib/analysis/ConfiguredAspect.java
@@ -44,6 +44,12 @@
* added.
*
* <p>Aspects are created alongside configured targets on request from dependents.
+ *
+ * <p>For more information about aspects, see
+ * {@link com.google.devtools.build.lib.packages.AspectClass}.
+ *
+ * @see com.google.devtools.build.lib.rules.RuleConfiguredTargetFactory
+ * @see com.google.devtools.build.lib.packages.AspectClass
*/
@Immutable
public final class ConfiguredAspect implements Iterable<TransitiveInfoProvider> {
diff --git a/src/main/java/com/google/devtools/build/lib/analysis/RuleConfiguredTarget.java b/src/main/java/com/google/devtools/build/lib/analysis/RuleConfiguredTarget.java
index f1980ec..fc29d3e 100644
--- a/src/main/java/com/google/devtools/build/lib/analysis/RuleConfiguredTarget.java
+++ b/src/main/java/com/google/devtools/build/lib/analysis/RuleConfiguredTarget.java
@@ -28,8 +28,11 @@
import java.util.Map;
/**
- * A generic implementation of RuleConfiguredTarget. Do not use directly. Use {@link
- * RuleConfiguredTargetBuilder} instead.
+ * A {@link ConfiguredTarget} that is produced by a rule.
+ *
+ * <p>Created by {@link RuleConfiguredTargetBuilder}. There is an instance of this class for every
+ * analyzed rule. For more information about how analysis works, see
+ * {@link com.google.devtools.build.lib.rules.RuleConfiguredTargetFactory}.
*/
public final class RuleConfiguredTarget extends AbstractConfiguredTarget {
/**
diff --git a/src/main/java/com/google/devtools/build/lib/analysis/RuleConfiguredTargetBuilder.java b/src/main/java/com/google/devtools/build/lib/analysis/RuleConfiguredTargetBuilder.java
index b6fd29c..17617e7 100644
--- a/src/main/java/com/google/devtools/build/lib/analysis/RuleConfiguredTargetBuilder.java
+++ b/src/main/java/com/google/devtools/build/lib/analysis/RuleConfiguredTargetBuilder.java
@@ -46,7 +46,13 @@
import java.util.TreeMap;
/**
- * Builder class for analyzed rule instances (i.e., instances of {@link ConfiguredTarget}).
+ * Builder class for analyzed rule instances.
+ *
+ * <p>This is used to tell Bazel which {@link TransitiveInfoProvider}s are produced by the analysis
+ * of a configured target. For more information about analysis, see
+ * {@link com.google.devtools.build.lib.rules.RuleConfiguredTargetFactory}.
+ *
+ * @see com.google.devtools.build.lib.rules.RuleConfiguredTargetFactory
*/
public final class RuleConfiguredTargetBuilder {
private final RuleContext ruleContext;
diff --git a/src/main/java/com/google/devtools/build/lib/analysis/RuleContext.java b/src/main/java/com/google/devtools/build/lib/analysis/RuleContext.java
index eb457d0..20ff73c 100644
--- a/src/main/java/com/google/devtools/build/lib/analysis/RuleContext.java
+++ b/src/main/java/com/google/devtools/build/lib/analysis/RuleContext.java
@@ -89,14 +89,14 @@
import javax.annotation.Nullable;
/**
- * A helper class for rule implementations building and initialization. Objects of this
- * class are intended to be passed to the builder for the configured target, which then creates the
- * configured target.
+ * The totality of data available during the analysis of a rule.
*
* <p>These objects should not outlast the analysis phase. Do not pass them to {@link Action}
* objects or other persistent objects. There are internal tests to ensure that RuleContext objects
* are not persisted that check the name of this class, so update those tests if you change this
* class's name.
+ *
+ * @see com.google.devtools.build.lib.rules.RuleConfiguredTargetFactory
*/
public final class RuleContext extends TargetContext
implements ActionConstructionContext, ActionRegistry, RuleErrorConsumer {
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 42b8297..ab533151 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
@@ -21,57 +21,11 @@
import javax.annotation.Nullable;
/**
- * Objects that implement this interface bundle multiple {@link TransitiveInfoProvider} interfaces.
+ * Multiple {@link TransitiveInfoProvider}s bundled together.
*
- * <p>This interface (together with {@link TransitiveInfoProvider} is the cornerstone of the data
- * model of the analysis phase.
- *
- * <p>The computation a configured target does is allowed to depend on the following things:
- * <ul>
- * <li>The associated Target (which will usually be a Rule)
- * <li>Its own configuration (the configured target does not have access to other configurations,
- * e.g. the host configuration)
- * <li>The transitive info providers and labels of its direct dependencies.
- * </ul>
- *
- * <p>And these are the only inputs. Notably, a configured target is not supposed to access
- * other configured targets, the transitive info collections of configured targets it does not
- * directly depend on, the actions created by anyone else or the contents of any input file. We
- * strive to make it impossible for configured targets to do these things.
- *
- * <p>A configured target is expected to produce the following data during its analysis:
- * <ul>
- * <li>A number of Artifacts and Actions generating them
- * <li>A set of {@link TransitiveInfoProvider}s that it passes on to the targets directly dependent
- * on it
- * </ul>
- *
- * <p>The information that can be passed on to dependent targets by way of
- * {@link TransitiveInfoProvider} is subject to constraints (which are detailed in the
- * documentation of that class).
- *
- * <p>Configured targets are currently allowed to create artifacts at any exec path. It would be
- * better if they could be constrained to a subtree based on the label of the configured target,
- * but this is currently not feasible because multiple rules violate this constraint and the
- * output format is part of its interface.
- *
- * <p>In principle, multiple configured targets should not create actions with conflicting
- * outputs. There are still a few exceptions to this rule that are slated to be eventually
- * removed, we have provisions to handle this case (Action instances that share at least one
- * output file are required to be exactly the same), but this does put some pressure on the design
- * and we are eventually planning to eliminate this option.
- *
- * <p>These restrictions together make it possible to:
- * <ul>
- * <li>Correctly cache the analysis phase; by tightly constraining what a configured target is
- * allowed to access and what it is not, we can know when it needs to invalidate a particular
- * one and when it can reuse an already existing one.
- * <li>Serialize / deserialize individual configured targets at will, making it possible for
- * example to swap out part of the analysis state if there is memory pressure or to move them in
- * persistent storage so that the state can be reconstructed at a different time or in a
- * different process. The stretch goal is to eventually facilitate cross-user caching of this
- * information.
- * </ul>
+ * Represents the information made available by a {@link ConfiguredTarget} to other ones that
+ * depend on it. For more information about the analysis phase, see
+ * {@link com.google.devtools.build.lib.rules.RuleConfiguredTargetFactory}.
*
* <p>Implementations of build rules should <b>not</b> hold on to references to the
* {@link TransitiveInfoCollection}s representing their direct prerequisites in order to reduce
@@ -79,6 +33,7 @@
* dependencies in turn, thereby making the size of the objects reachable from a single instance
* unbounded).
*
+ * @see com.google.devtools.build.lib.rules.RuleConfiguredTargetFactory
* @see TransitiveInfoProvider
*/
@SkylarkModule(name = "Target", doc =
diff --git a/src/main/java/com/google/devtools/build/lib/analysis/TransitiveInfoProvider.java b/src/main/java/com/google/devtools/build/lib/analysis/TransitiveInfoProvider.java
index 37f589d..9967aa8 100644
--- a/src/main/java/com/google/devtools/build/lib/analysis/TransitiveInfoProvider.java
+++ b/src/main/java/com/google/devtools/build/lib/analysis/TransitiveInfoProvider.java
@@ -15,9 +15,10 @@
package com.google.devtools.build.lib.analysis;
/**
- * This marker interface must be extended by every interface that represents
- * rolled-up data about the transitive closure of a configured target.
+ * Contains rolled-up data about the transitive closure of a configured target.
*
+ * For more information about how analysis works, see
+ * {@link com.google.devtools.build.lib.rules.RuleConfiguredTargetFactory}.
* TransitiveInfoProviders need to be serializable, and for that reason they must conform to
* the following restrictions:
*
@@ -49,13 +50,14 @@
* being O(n^2): in a long dependency chain, if every target adds one single artifact, storing the
* transitive closures of every rule would take 1+2+3+...+n-1+n = O(n^2) memory.
*
- * <p>In order to avoid this, we introduce the concept of nested sets, {@link com.google.devtools
- * .build.lib.collect.nestedset.NestedSet}. A nested set is an immutable
+ * <p>In order to avoid this, we introduce the concept of nested sets, {@link
+ * com.google.devtools.build.lib.collect.nestedset.NestedSet}. A nested set is an immutable
* data structure that can contain direct members and other nested sets (recursively). Nested sets
* are iterable and can be flattened into ordered sets, where the order depends on which
* implementation of NestedSet you pick.
*
* @see TransitiveInfoCollection
+ * @see com.google.devtools.build.lib.rules.RuleConfiguredTargetFactory
*/
public interface TransitiveInfoProvider {
}
