1 files changed, 46 insertions, 8 deletions
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 1a3d52d5c6..6a7d24902e 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,14 +16,54 @@ package com.google.devtools.build.lib.packages;
 
 /**
  *  A class of aspects.
+ *  <p>Aspects might be defined natively, in Java ({@link NativeAspectClass})
+ *  or in Skylark ({@link SkylarkAspectClass}).
  *
- *  <p>This interface serves as a factory for {@code AspectFactory}.
- *  {@code AspectFactory} type argument is a placeholder for
- *  a {@link com.google.devtools.build.lib.analysis.ConfiguredAspectFactory}, which is
- *  an analysis-phase class. All loading-phase code uses {@code AspectClass&lt;?&gt;},
- *  whereas analysis-phase code uses {@code AspectClass&lt;ConfiguredAspectFactory&gt;}.
- *  The latter is what all real implementations of this interface should implement.
+ *  Bazel propagates aspects through a multistage process. The general pipeline is as follows:
  *
+ *  <pre>
+ *  {@link AspectClass}
+ *   |
+ *   V
+ *  {@code AspectDescriptor} <- {@link AspectParameters}
+ *   \
+ *   V
+ *  {@link Aspect} <- {@link AspectDefinition} (might require loading Skylark files)
+ *   |
+ *   V
+ *  {@code ConfiguredAspect}  <- {@code ConfiguredTarget}
+ *  </pre>
+ *
+ *  <ul>
+ *    <li>{@link AspectClass} is a moniker for "user" definition of the aspect, be it
+ *    a native aspect or a Skylark aspect.  It contains either a reference to
+ *    the native class implementing the aspect or the location of the Skylark definition
+ *    of the aspect in the source tree, i.e. label of .bzl file + symbol name.
+ *    </li>
+ *    <li>{@link AspectParameters} is a (key,value) pair list that can be used to
+ *    parameterize aspect classes</li>
+ *    <li>{@link com.google.devtools.build.lib.analysis.AspectDescriptor} is a pair
+ *    of {@code AspectClass} and {@link AspectParameters}. It uniquely identifies
+ *    the aspect and can be used in SkyKeys.
+ *    </li>
+ *    <li>{@link AspectDefinition} is a class encapsulating the aspect definition (what
+ *    attributes aspoect has, and along which dependencies does it propagate.
+ *    </li>
+ *    <li>{@link Aspect} is a fully instantiated instance of an Aspect after it is loaded.
+ *    Getting an {@code Aspect} from {@code AspectDescriptor} for Skylark aspects
+ *    requires adding a Skyframe dependency.
+ *    </li>
+ *    <li>{@link com.google.devtools.build.lib.analysis.ConfiguredAspect} represents a result
+ *    of application of an {@link Aspect} to a given
+ *    {@link com.google.devtools.build.lib.analysis.ConfiguredTarget}.
+ *    </li>
+ *  </ul>
+ *
+ *  {@link com.google.devtools.build.lib.analysis.AspectDescriptor}, or in general, a tuple
+ *  of ({@link AspectClass}, {@link AspectParameters}) is an identifier that should be
+ *  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.
  */
 public interface AspectClass {
 
@@ -31,6 +71,4 @@ public interface AspectClass {
    * Returns an aspect name.
    */
   String getName();
-
-  AspectDefinition getDefinition(AspectParameters aspectParameters);
 }