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/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 =
