Write a large comment explaining the build info machinery.

RELNOTES: None.
PiperOrigin-RevId: 409904095

src/main/java/com/google/devtools/build/lib/analysis/WorkspaceStatusAction.java

@@ -58,6 +58,9 @@
  * <p>There are two of these files: volatile and stable. Changes in the volatile file do not cause
  * rebuilds if no other file is changed. This is useful for frequently-changing information that
  * does not significantly affect the build, e.g. the current time.
+ *
+ * <p>For more information, see {@link
+ * com.google.devtools.build.lib.analysis.buildinfo.BuildInfoFactory}.
  */
 public abstract class WorkspaceStatusAction extends AbstractAction {
 

src/main/java/com/google/devtools/build/lib/analysis/buildinfo/BuildInfoFactory.java

@@ -19,9 +19,54 @@
 import com.google.devtools.build.lib.vfs.PathFragment;
 
 /**
- * A factory for language-specific build-info files. Use this to translate the build-info into
- * target-independent language-specific files. The generated actions are registered into the action
- * graph on every build, but only executed if anything depends on them.
+ * A factory for language-specific build-info files.
+ *
+ * <p>The goal of the build info system is to "stamp" non-hermetic information into output files,
+ * for example, the time and date of the build that resulted in the output, the hostname it was run
+ * on or the set of sources the output was built from.
+ *
+ * <p>This non-hermetic data gets into the action graph by calling the script specified in the
+ * <code>--workspace_status_command</code> command line argument, which results in a text file which
+ * containts a build info entry in each line, with its name ("key") and value separated by a space.
+ * This script is unconditionally invoked on every build and therefore should be very fast.
+ *
+ * <p>Build info keys come in two kinds: volatile and non-volatile. The difference is that the
+ * former is expected to change very frequently (e.g. current time) and therefore changes to it
+ * should not invalidate downstream actions whereas a rebuild is required if a non-volatile build
+ * info entry changes.
+ *
+ * <p>This is accomplished by splitting the build info file emitted by the workspace status command
+ * into two files, a volatile and a non-volatile. The former kind of artifact is special-cased in
+ * the execution phase machinery so that changes to it never trigger a rebuild. This artifact is
+ * marked by {@link
+ * com.google.devtools.build.lib.actions.Artifact.SpecialArtifactType#CONSTANT_METADATA}.
+ *
+ * <p>The invocation of the workspace status command and splitting its output into two is done in
+ * descendants of {@link com.google.devtools.build.lib.analysis.WorkspaceStatusAction} .
+ *
+ * <p>However, this is not enough because the workspace status files cannot always be ingested by
+ * the actions that need them; for example, if a C++ file wants to incorporate build info, the
+ * compiler cannot process build info text files, therefore the data needs to be transformed into a
+ * format that the compiler likes.
+ *
+ * <p>This is done for each language by an implementation of {@link BuildInfoFactory}: rules can
+ * call {@link com.google.devtools.build.lib.analysis.AnalysisEnvironment#getBuildInfo(boolean,
+ * BuildInfoKey, BuildConfigurationValue)} with the language-specific build info key, which then
+ * invokes {@link com.google.devtools.build.lib.skyframe.BuildInfoCollectionFunction}, which in turn
+ * calls the language-specific implementation of {@link BuildInfoFactory}, which creates the
+ * language-specific actions and artifacts. These are then returned to the caller of {@code
+ * getBuildInfo()} (This could probably be replaced by an implicit dependency on a language-specific
+ * special rule does all this; there are only historical reasons why it works this way)
+ *
+ * <p>{@link com.google.devtools.build.lib.skyframe.BuildInfoCollectionValue} is a thin wrapper
+ * around the data structure {@code BuildInfoFactory} returns (a set of artifacts and actions). Its
+ * purpose is to allow Skyframe to look up the generating actions of build info artifacts. This is
+ * done by implementing {@link com.google.devtools.build.lib.actions.ActionLookupValue}. It is
+ * necessary because actions are usually generated by configured targets or aspects, but not build
+ * info actions which are instead created by the mechanism described above.
+ *
+ * <p>Build info factories are registered in {@link
+ * com.google.devtools.build.lib.analysis.ConfiguredRuleClassProvider}.
  */
 public interface BuildInfoFactory {
   /**

src/main/java/com/google/devtools/build/lib/analysis/buildinfo/BuildInfoKey.java

@@ -16,6 +16,9 @@
 /**
  * Build-info key for lookup from the {@link
  * com.google.devtools.build.lib.analysis.AnalysisEnvironment}.
+ *
+ * <p>For more information, see {@link
+ * com.google.devtools.build.lib.analysis.buildinfo.BuildInfoFactory}.
  */
 public final class BuildInfoKey {
   private final String name;

src/main/java/com/google/devtools/build/lib/skyframe/BuildInfoCollectionFunction.java

@@ -36,6 +36,9 @@
 /**
  * Creates a {@link BuildInfoCollectionValue}. Only depends on the unique {@link
  * WorkspaceStatusValue} and the constant {@link #BUILD_INFO_FACTORIES} injected value.
+ *
+ * <p>For more information, see {@link
+ * com.google.devtools.build.lib.analysis.buildinfo.BuildInfoFactory}.
  */
 public class BuildInfoCollectionFunction implements SkyFunction {