Document AndroidLibrary.java for readability.

RELNOTES: None.
PiperOrigin-RevId: 206393574

1 files changed, 26 insertions, 2 deletions

diff --git a/src/main/java/com/google/devtools/build/lib/rules/android/AndroidLibrary.java b/src/main/java/com/google/devtools/build/lib/rules/android/AndroidLibrary.java
index 50d69dc9ab..bd59fbd0f5 100644
--- a/src/main/java/com/google/devtools/build/lib/rules/android/AndroidLibrary.java
+++ b/src/main/java/com/google/devtools/build/lib/rules/android/AndroidLibrary.java
@@ -115,18 +115,26 @@ public abstract class AndroidLibrary implements RuleConfiguredTargetFactory {
   public ConfiguredTarget create(RuleContext ruleContext)
       throws InterruptedException, RuleErrorException, ActionConflictException {
     validateRuleContext(ruleContext);
+
+    // Create semantics objects, which are different between Blaze and Bazel.
     JavaSemantics javaSemantics = createJavaSemantics();
     AndroidSemantics androidSemantics = createAndroidSemantics();
     androidSemantics.validateAndroidLibraryRuleContext(ruleContext);
     createAndroidMigrationSemantics().validateRuleContext(ruleContext);
+
     AndroidSdkProvider.verifyPresence(ruleContext);
 
+    // Create wrappers for the ProGuard configuration files.
     NestedSetBuilder<Artifact> proguardConfigsbuilder = NestedSetBuilder.stableOrder();
     ProguardLibrary proguardLibrary = new ProguardLibrary(ruleContext);
     proguardConfigsbuilder.addTransitive(proguardLibrary.collectProguardSpecs());
+
+    // If there are idl srcs, we'll need the transitive proguard configurations too.
     AndroidIdlHelper.maybeAddSupportLibProguardConfigs(ruleContext, proguardConfigsbuilder);
     NestedSet<Artifact> transitiveProguardConfigs = proguardConfigsbuilder.build();
 
+    // JavaCommon and AndroidCommon contain shared helper classes between java_* and android_*
+    // rules respectively.
     JavaCommon javaCommon =
         AndroidCommon.createJavaCommonWithAndroidDataBinding(ruleContext, javaSemantics, true);
     javaSemantics.checkRule(ruleContext, javaCommon);
@@ -134,6 +142,7 @@ public abstract class AndroidLibrary implements RuleConfiguredTargetFactory {
 
     AndroidConfiguration androidConfig = AndroidCommon.getAndroidConfig(ruleContext);
 
+    // "Resources" here include actual resources (xmls, drawables, etc), assets, and the manifest.
     boolean definesLocalResources =
         AndroidResources.definesAndroidResources(ruleContext.attributes());
     if (definesLocalResources) {
@@ -147,9 +156,15 @@ public abstract class AndroidLibrary implements RuleConfiguredTargetFactory {
     ResourceDependencies resourceDeps = ResourceDependencies.fromRuleDeps(ruleContext, isNeverLink);
     AssetDependencies assetDeps = AssetDependencies.fromRuleDeps(ruleContext, isNeverLink);
 
+    // Start processing Android data via the AndroidDataContext.
+    // "Data" is a collective term for manifest, resources, and assets.
     final AndroidDataContext dataContext = androidSemantics.makeContextForNative(ruleContext);
+    // Use a standalone resource-only APK (with extension ".ap_") to decouple Android data from the
+    // other artifacts.
     final ResourceApk resourceApk;
     if (definesLocalResources) {
+      // By decoupling processing of manifest, resources and assets, we get a higher degree of
+      // action parallelism.
       if (androidConfig.decoupleDataProcessing()) {
         StampedAndroidManifest manifest =
             AndroidManifest.fromAttributes(ruleContext, dataContext, androidSemantics)
@@ -168,6 +183,7 @@ public abstract class AndroidLibrary implements RuleConfiguredTargetFactory {
 
         resourceApk = ResourceApk.of(resources, assets, null, null);
       } else {
+        // Monolithically process all Android data in the same pipeline.
         ApplicationManifest applicationManifest =
             androidSemantics
                 .getManifestForRule(ruleContext)
@@ -190,7 +206,7 @@ public abstract class AndroidLibrary implements RuleConfiguredTargetFactory {
         return null;
       }
     } else {
-      // Process transitive resources so we can build artifacts needed to export an aar.
+      // No local resources, but we still need to process transitive resources.
       resourceApk =
           ResourceApk.processFromTransitiveLibraryData(
               dataContext,
@@ -199,6 +215,8 @@ public abstract class AndroidLibrary implements RuleConfiguredTargetFactory {
               StampedAndroidManifest.createEmpty(ruleContext, /* exported = */ false));
     }
 
+    // As android_library makes use of the Java rule compilation pipeline, we collect all
+    // Java-related information here to be passed into the JavaSourceInfoProvider later.
     JavaTargetAttributes javaTargetAttributes =
         androidCommon.init(
             javaSemantics,
@@ -213,6 +231,8 @@ public abstract class AndroidLibrary implements RuleConfiguredTargetFactory {
       return null;
     }
 
+    // Create the implicit AAR output artifact which contains non-transitive resources, proguard
+    // specs and class jar.
     final Aar aar =
         Aar.makeAar(
             dataContext,
@@ -220,6 +240,8 @@ public abstract class AndroidLibrary implements RuleConfiguredTargetFactory {
             proguardLibrary.collectLocalProguardSpecs(),
             androidCommon.getClassJar());
 
+    // Start building the configured target by adding all the necessary transitive providers/infos.
+    // Includes databinding, IDE, Java. Also declares the output groups and sets the files to build.
     RuleConfiguredTargetBuilder builder = new RuleConfiguredTargetBuilder(ruleContext);
     androidCommon.addTransitiveInfoProviders(
         builder,
@@ -238,13 +260,14 @@ public abstract class AndroidLibrary implements RuleConfiguredTargetFactory {
     }
 
     builder
+        // android_library doesn't do any cc steps, so we'll just pass native libs along.
         .addNativeDeclaredProvider(
             new AndroidNativeLibsInfo(
                 AndroidCommon.collectTransitiveNativeLibs(ruleContext).build()))
+        .addNativeDeclaredProvider(androidCommon.getCcLinkingInfo())
         .add(
             JavaSourceInfoProvider.class,
             JavaSourceInfoProvider.fromJavaTargetAttributes(javaTargetAttributes, javaSemantics))
-        .addNativeDeclaredProvider(androidCommon.getCcLinkingInfo())
         .addNativeDeclaredProvider(new ProguardSpecProvider(transitiveProguardConfigs))
         .addNativeDeclaredProvider(
             new AndroidProguardInfo(proguardLibrary.collectLocalProguardSpecs()))
@@ -252,6 +275,7 @@ public abstract class AndroidLibrary implements RuleConfiguredTargetFactory {
         .addNativeDeclaredProvider(
             AndroidLibraryResourceClassJarProvider.create(transitiveResourcesJars.build()));
 
+    // If this isn't a neverlink target, we'll provide the artifacts in the AAR too.
     if (!JavaCommon.isNeverLink(ruleContext)) {
       builder.addNativeDeclaredProvider(aar.toProvider(ruleContext, definesLocalResources));
     }