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/packages/AspectClass.java b/src/main/java/com/google/devtools/build/lib/packages/AspectClass.java
index 6a7d249..2d615e1 100644
--- a/src/main/java/com/google/devtools/build/lib/packages/AspectClass.java
+++ b/src/main/java/com/google/devtools/build/lib/packages/AspectClass.java
@@ -16,7 +16,37 @@
/**
* A class of aspects.
- * <p>Aspects might be defined natively, in Java ({@link NativeAspectClass})
+ *
+ * <p>An aspect allows a rule to create actions in its dependencies, without their knowledge.
+ * It can be viewed as the ability to attach shadow targets to transitive dependencies or a way
+ * to run visitations of certain parts of the transitive closure of a rule in such a way that can
+ * be cached (even partially) and reused between different configured targets requiring the same
+ * aspect. Some examples where aspects are useful:
+ *
+ * <ul>
+ * <li>Converting the .jar files in the transitive closure of an Android binary to dexes</li>
+ * <li>Emitting Java sources for a <code>proto_library</code> and the messages it depends
+ * on</li>
+ * <li>Collecting all the dependencies of a rule to make sure that it does not contain a
+ * forbidden one</li>
+ * </ul>
+ *
+ * <p>When a configured target requests that an aspect be attached to one of its dependencies,
+ * the {@link com.google.devtools.build.lib.analysis.TransitiveInfoProvider}s generated by that
+ * aspects are merged with those of the actual dependency, that is,
+ * {@link com.google.devtools.build.lib.analysis.RuleContext#getPrerequisite(
+ * String, com.google.devtools.build.lib.analysis.RuleConfiguredTarget.Mode)} will
+ * contain the transitive info providers produced both by the dependency and the aspects that are
+ * attached to it.
+ *
+ * <p>Configured targets can specify which aspects should be attached to some of their dependencies
+ * by specifying this in their {@link com.google.devtools.build.lib.analysis.RuleDefinition}: each
+ * attribute can have a list of aspects to be applied to the rules in that attribute and each
+ * aspect can specify which {@link com.google.devtools.build.lib.analysis.TransitiveInfoProvider}s
+ * it needs on a rule so that it can do meaningful work (for example, dexing only makes sense for
+ * configured targets that produce Java code).
+ *
+ * <p>Aspects can be defined natively, in Java ({@link NativeAspectClass})
* or in Skylark ({@link SkylarkAspectClass}).
*
* Bazel propagates aspects through a multistage process. The general pipeline is as follows:
@@ -64,6 +94,9 @@
* used in SkyKeys or in other contexts that need equality for aspects.
* See also {@link com.google.devtools.build.lib.skyframe.AspectFunction} for details
* on Skyframe treatment of Aspects.
+ *
+ * @see com.google.devtools.build.lib.rules.RuleConfiguredTargetFactory
+ * @see com.google.devtools.build.lib.skyframe.AspectFunction
*/
public interface AspectClass {
