Stop using preprocessed .aidl files for types in the same android_library.

This makes very little sense, because we only do this when compiling
them within a rule. The preprocessed files are not shipped to other rules,
meaning we treat things differently depending on the dependency
structure. And, worst of all, this can lead to a bug in the aidl compiler,
which causes the preprocessed definition to take precedence over the input
file, which causes certain modifiers to be stripped away.

Also, Gradle doesn't do it, and that's proof enough that this is no longer
the way to go, if ever it was.

Unfortunately, this causes a problem: the preprocessing had an effect, in
that all preprocessed types are available without the use of imports. This
means that .aidl files which were previously legal before this change may
now be broken, if they relied on this behavior. But, those .aidl files are
actually not legal according to the .aidl specification. Unfortunate, but
the right thing to do.

This CL also updates the idl documentation. Which, let's face it, could
probably have used some improvement.

RELNOTES[INC]: .aidl files correctly require import statements for types
defined in the same package and the same android_library.

--
MOS_MIGRATED_REVID=115718918

3 files changed, 204 insertions, 76 deletions

diff --git a/src/main/java/com/google/devtools/build/lib/bazel/rules/android/BazelAndroidLibraryRule.java b/src/main/java/com/google/devtools/build/lib/bazel/rules/android/BazelAndroidLibraryRule.java
index 640f908570..8cacc9e86c 100644
--- a/src/main/java/com/google/devtools/build/lib/bazel/rules/android/BazelAndroidLibraryRule.java
+++ b/src/main/java/com/google/devtools/build/lib/bazel/rules/android/BazelAndroidLibraryRule.java
@@ -78,4 +78,77 @@ ${IMPLICIT_OUTPUTS}
 <p>Examples of Android rules can be found in the <code>examples/android</code> directory of the
 Bazel source tree.
 
+<p id="android_library_examples.idl_import_root">The following example shows
+how to set <code>idl_import_root</code>.
+Let <code>//java/bazel/helloandroid/BUILD</code> contain:</p>
+<pre class="code">
+android_library(
+    name = "parcelable",
+    srcs = ["MyParcelable.java"], # bazel.helloandroid.MyParcelable
+
+    # MyParcelable.aidl will be used as import for other .aidl
+    # files that depend on it, but will not be compiled.
+    idl_parcelables = ["MyParcelable.aidl"] # bazel.helloandroid.MyParcelable
+
+    # We don't need to specify idl_import_root since the aidl file
+    # which declares bazel.helloandroid.MyParcelable
+    # is present at java/bazel/helloandroid/MyParcelable.aidl
+    # underneath a java root (java/).
+)
+
+android_library(
+    name = "foreign_parcelable",
+    srcs = ["src/android/helloandroid/OtherParcelable.java"], # android.helloandroid.OtherParcelable
+    idl_parcelables = [
+        "src/android/helloandroid/OtherParcelable.aidl" # android.helloandroid.OtherParcelable
+    ],
+
+    # We need to specify idl_import_root because the aidl file which
+    # declares android.helloandroid.OtherParcelable is not positioned
+    # at android/helloandroid/OtherParcelable.aidl under a normal java root.
+    # Setting idl_import_root to "src" in //java/bazel/helloandroid
+    # adds java/bazel/helloandroid/src to the list of roots
+    # the aidl compiler will search for imported types.
+    idl_import_root = "src",
+)
+
+# Here, OtherInterface.aidl has an "import android.helloandroid.CallbackInterface;" statement.
+android_library(
+    name = "foreign_interface",
+    idl_srcs = [
+        "src/android/helloandroid/OtherInterface.aidl" # android.helloandroid.OtherInterface
+        "src/android/helloandroid/CallbackInterface.aidl" # android.helloandroid.CallbackInterface
+    ],
+
+    # As above, idl_srcs which are not correctly positioned under a java root
+    # must have idl_import_root set. Otherwise, OtherInterface (or any other
+    # interface in a library which depends on this one) will not be able
+    # to find CallbackInterface when it is imported.
+    idl_import_root = "src",
+)
+
+# MyParcelable.aidl is imported by MyInterface.aidl, so the generated
+# MyInterface.java requires MyParcelable.class at compile time.
+# Depending on :parcelable ensures that aidl compilation of MyInterface.aidl
+# specifies the correct import roots and can access MyParcelable.aidl, and
+# makes MyParcelable.class available to Java compilation of MyInterface.java
+# as usual.
+android_library(
+    name = "idl",
+    idl_srcs = ["MyInterface.aidl"],
+    deps = [":parcelable"],
+)
+
+# Here, ServiceParcelable uses and thus depends on ParcelableService,
+# when it's compiled, but ParcelableService also uses ServiceParcelable,
+# which creates a circular dependency.
+# As a result, these files must be compiled together, in the same android_library.
+android_library(
+    name = "circular_dependencies",
+    srcs = ["ServiceParcelable.java"],
+    idl_srcs = ["ParcelableService.aidl"],
+    idl_parcelables = ["ServiceParcelable.aidl"],
+)
+</pre>
+
 <!-- #END_BLAZE_RULE -->*/
diff --git a/src/main/java/com/google/devtools/build/lib/rules/android/AndroidIdlHelper.java b/src/main/java/com/google/devtools/build/lib/rules/android/AndroidIdlHelper.java
index dc00cbb369..6a5ff8e112 100644
--- a/src/main/java/com/google/devtools/build/lib/rules/android/AndroidIdlHelper.java
+++ b/src/main/java/com/google/devtools/build/lib/rules/android/AndroidIdlHelper.java
@@ -16,7 +16,6 @@ package com.google.devtools.build.lib.rules.android;
 import com.google.common.collect.ImmutableList;
 import com.google.common.collect.ImmutableMap;
 import com.google.devtools.build.lib.actions.Artifact;
-import com.google.devtools.build.lib.actions.MiddlemanFactory;
 import com.google.devtools.build.lib.actions.ParameterFile.ParameterFileType;
 import com.google.devtools.build.lib.analysis.RuleConfiguredTarget.Mode;
 import com.google.devtools.build.lib.analysis.RuleConfiguredTargetBuilder;
@@ -24,6 +23,7 @@ import com.google.devtools.build.lib.analysis.RuleContext;
 import com.google.devtools.build.lib.analysis.actions.CustomCommandLine;
 import com.google.devtools.build.lib.analysis.actions.SpawnAction;
 import com.google.devtools.build.lib.cmdline.Label;
+import com.google.devtools.build.lib.collect.nestedset.NestedSet;
 import com.google.devtools.build.lib.collect.nestedset.NestedSetBuilder;
 import com.google.devtools.build.lib.packages.BuildType;
 import com.google.devtools.build.lib.rules.java.JavaUtil;
@@ -34,9 +34,9 @@ import com.google.devtools.build.lib.vfs.PathFragment;
 import java.util.ArrayList;
 import java.util.Collection;
 import java.util.HashSet;
-import java.util.LinkedHashSet;
 import java.util.List;
 import java.util.Map;
+import java.util.Map.Entry;
 import java.util.Set;
 
 import javax.annotation.Nullable;
@@ -48,22 +48,27 @@ public class AndroidIdlHelper {
 
   private final RuleContext ruleContext;
   private final AndroidIdlProvider androidIdlProvider;
-  private final Collection<Artifact> idls;
   private final Map<Artifact, Artifact> translatedIdlSources;
   private final Artifact idlClassJar;
   private final Artifact idlSourceJar;
 
-  public AndroidIdlHelper(RuleContext ruleContext, Artifact classJar) {
+  /**
+   * Creates a new AndroidIdlHelper wrapping the given {@code ruleContext}.
+   *
+   * @param ruleContext The rule context whose idl attributes will be used to collect .aidl files.
+   * @param baseArtifact An artifact used to calculate the paths for the IDL class and source jars.
+   */
+  public AndroidIdlHelper(RuleContext ruleContext, Artifact baseArtifact) {
     this.ruleContext = ruleContext;
 
     checkIdlRootImport(ruleContext);
 
-    idls = getIdlSrcs(ruleContext);
+    Collection<Artifact> idls = getIdlSrcs(ruleContext);
 
     if (!idls.isEmpty() && !ruleContext.hasErrors()) {
       translatedIdlSources = generateTranslatedIdlArtifacts(ruleContext, idls);
-      idlClassJar = createIdlJar(classJar, "-idl.jar");
-      idlSourceJar = createIdlJar(classJar, "-idl.srcjar");
+      idlClassJar = createIdlJar(baseArtifact, "-idl.jar");
+      idlSourceJar = createIdlJar(baseArtifact, "-idl.srcjar");
     } else {
       translatedIdlSources = ImmutableMap.of();
       idlClassJar = null;
@@ -74,11 +79,24 @@ public class AndroidIdlHelper {
         ruleContext, idlClassJar, idlSourceJar);
   }
 
+  /**
+   * Adds the necessary providers to the {@code builder}.
+   *
+   * Adds an {@link AndroidIdlProvider} to the target, and adds the transitive generated IDL jars to
+   * the IDL_JARS_OUTPUT_GROUP. This also generates the actions to compile the .aidl files to .java,
+   * as well as the .jar and .srcjar files consisting of only the IDL-generated source and class
+   * files.
+   *
+   * @param builder The target builder to add the providers to.
+   * @param classJar The class jar to be separated into the IDL class jar.
+   * @param manifestProtoOutput The manifest generated by JavaBuilder, for identifying IDL-generated
+   *     class files in the class jar.
+   */
   public void addTransitiveInfoProviders(RuleConfiguredTargetBuilder builder,
       Artifact classJar, Artifact manifestProtoOutput) {
-    if (!idls.isEmpty()) {
+    if (!translatedIdlSources.isEmpty()) {
       generateAndroidIdlCompilationActions(
-          ruleContext, idls, androidIdlProvider, translatedIdlSources);
+          ruleContext, androidIdlProvider, translatedIdlSources);
       createIdlClassJarAction(ruleContext, classJar, translatedIdlSources.values(),
           manifestProtoOutput, idlClassJar, idlSourceJar);
     }
@@ -88,38 +106,59 @@ public class AndroidIdlHelper {
             AndroidSemantics.IDL_JARS_OUTPUT_GROUP, androidIdlProvider.getTransitiveIdlJars());
   }
 
+  /**
+   * Returns the raw (non-processed) idl_srcs, not including parcelable marker files.
+   */
   public Collection<Artifact> getIdlSources() {
-    return idls;
+    return translatedIdlSources.keySet();
   }
 
+  /**
+   * Returns the idl_parcelables, consisting of parcelable marker files defined on this rule.
+   */
   public Collection<Artifact> getIdlParcelables() {
     return getIdlParcelables(ruleContext);
   }
 
+  /**
+   * Returns the generated Java sources created from the idl_srcs.
+   */
   public Collection<Artifact> getIdlGeneratedJavaSources() {
     return translatedIdlSources.values();
   }
 
+  /**
+   * Returns the jar containing class files derived from the .aidl files.
+   *
+   * <p>Will be null if there are no idl_srcs.
+   */
   @Nullable
   public Artifact getIdlClassJar() {
     return idlClassJar;
   }
 
+  /**
+   * Returns the jar containing source files derived from the .aidl files.
+   *
+   * <p>Will be null if there are no idl_srcs.
+   */
   @Nullable
   public Artifact getIdlSourceJar() {
     return idlSourceJar;
   }
 
   /**
-   * Returns the artifact for a jar file containing class files that were generated by
-   * annotation processors.
+   * Generates an artifact by replacing the extension of the input with the suffix.
    */
-  private Artifact createIdlJar(Artifact outputJar, String suffix) {
+  private Artifact createIdlJar(Artifact baseArtifact, String suffix) {
     return ruleContext.getDerivedArtifact(
-        FileSystemUtils.replaceExtension(outputJar.getRootRelativePath(), suffix),
-        outputJar.getRoot());
+        FileSystemUtils.replaceExtension(baseArtifact.getRootRelativePath(), suffix),
+        baseArtifact.getRoot());
   }
 
+  /**
+   * Returns the idl_parcelables defined on the given rule.
+   */
   private static ImmutableList<Artifact> getIdlParcelables(RuleContext ruleContext) {
     return ruleContext.getRule().isAttrDefined("idl_parcelables", BuildType.LABEL_LIST)
         ? ImmutableList.copyOf(ruleContext.getPrerequisiteArtifacts(
@@ -127,6 +166,9 @@ public class AndroidIdlHelper {
         : ImmutableList.<Artifact>of();
   }
 
+  /**
+   * Returns the idl_srcs defined on the given rule.
+   */
   private static Collection<Artifact> getIdlSrcs(RuleContext ruleContext) {
     if (!ruleContext.getRule().isAttrDefined("idl_srcs", BuildType.LABEL_LIST)) {
       return ImmutableList.of();
@@ -136,6 +178,9 @@ public class AndroidIdlHelper {
         "idl_srcs", Mode.TARGET).filter(AndroidRuleClasses.ANDROID_IDL).list();
   }
 
+  /**
+   * Checks that all of the idl_srcs in the given rule are in the same package as the rule itself.
+   */
   private static void checkIdlSrcsSamePackage(RuleContext ruleContext) {
     PathFragment packageName = ruleContext.getLabel().getPackageFragment();
     Collection<Artifact> idls = ruleContext
@@ -152,6 +197,11 @@ public class AndroidIdlHelper {
     }
   }
 
+  /**
+   * Generates matching .java sources for the given .aidl sources.
+   *
+   * @return A mapping from .aidl input to .java output.
+   */
   private static ImmutableMap<Artifact, Artifact> generateTranslatedIdlArtifacts(
       RuleContext ruleContext, Collection<Artifact> idls) {
     ImmutableMap.Builder<Artifact, Artifact> outputJavaSources = ImmutableMap.builder();
@@ -170,51 +220,45 @@ public class AndroidIdlHelper {
     return outputJavaSources.build();
   }
 
+  /**
+   * Generates the actions to compile the given .aidl sources into .java sources.
+   *
+   * @param ruleContext The rule context in which to generate the actions.
+   * @param transitiveIdlImportData A provider to supply the artifacts and import roots to give to
+   *     the compiler.
+   * @param translatedIdlSources A map from input .aidl to output .java of files to be compiled.
+   */
   private static void generateAndroidIdlCompilationActions(
       RuleContext ruleContext,
-      Collection<Artifact> idls,
       AndroidIdlProvider transitiveIdlImportData,
       Map<Artifact, Artifact> translatedIdlSources) {
     AndroidSdkProvider sdk = AndroidSdkProvider.fromRuleContext(ruleContext);
-    Set<Artifact> preprocessedIdls = new LinkedHashSet<>();
     List<String> preprocessedArgs = new ArrayList<>();
 
-    // add imports
+    // add import roots so the aidl compiler will know where to look for the imports
     for (String idlImport : transitiveIdlImportData.getTransitiveIdlImportRoots()) {
       preprocessedArgs.add("-I" + idlImport);
     }
 
-    // preprocess each aidl file
     preprocessedArgs.add("-p" + sdk.getFrameworkAidl().getExecPathString());
-    String ruleName = ruleContext.getRule().getName();
-    for (Artifact idl : idls) {
-      // Reconstruct the package tree under <rule>_aidl to avoid a name conflict
-      // if the source AIDL files are also generated.
-      PathFragment preprocessedPath = new PathFragment(ruleName + "_aidl")
-          .getRelative(idl.getRootRelativePath());
-      Artifact preprocessed = ruleContext.getPackageRelativeArtifact(
-          preprocessedPath, ruleContext.getConfiguration().getGenfilesDirectory());
-      preprocessedIdls.add(preprocessed);
-      preprocessedArgs.add("-p" + preprocessed.getExecPathString());
-
-      createAndroidIdlPreprocessAction(ruleContext, idl, preprocessed);
-    }
 
-    // aggregate all preprocessed aidl files
-    MiddlemanFactory middlemanFactory = ruleContext.getAnalysisEnvironment().getMiddlemanFactory();
-    Artifact preprocessedIdlsMiddleman = middlemanFactory.createAggregatingMiddleman(
-        ruleContext.getActionOwner(), "AndroidIDLMiddleman", preprocessedIdls,
-        ruleContext.getConfiguration().getMiddlemanDirectory());
-
-    for (Artifact idl : translatedIdlSources.keySet()) {
-      createAndroidIdlAction(ruleContext, idl,
+    for (Entry<Artifact, Artifact> entry : translatedIdlSources.entrySet()) {
+      createAndroidIdlAction(ruleContext, entry.getKey(),
           transitiveIdlImportData.getTransitiveIdlImports(),
-          preprocessedIdlsMiddleman, translatedIdlSources.get(idl), preprocessedArgs);
+          entry.getValue(), preprocessedArgs);
     }
   }
 
   /**
-   * Creates the idl class jar action.
+   * Creates an action to split out classes and source files created by aidls.
+   *
+   * @param ruleContext The rule context in which to generate the action.
+   * @param classJar The class jar to divide into IDL class and source jars.
+   * @param generatedIdlJavaFiles The source files which should be put into the source jar and used
+   *     to determine the classes to take.
+   * @param manifestProtoOutput The protobuf containing the manifest generated from JavaBuilder.
+   * @param idlClassJar The artifact into which the IDL class jar should be written.
+   * @param idlSourceJar The artifact into which the IDL source jar should be written.
    */
   private static void createIdlClassJarAction(
       RuleContext ruleContext,
@@ -223,6 +267,10 @@ public class AndroidIdlHelper {
       Artifact manifestProtoOutput,
       Artifact idlClassJar,
       Artifact idlSourceJar) {
+    String basename = FileSystemUtils.removeExtension(classJar.getExecPath().getBaseName());
+    PathFragment idlTempDir = ruleContext.getConfiguration().getBinDirectory().getExecPath()
+        .getRelative(ruleContext.getUniqueDirectory("_idl"))
+        .getRelative(basename + "_temp");
     ruleContext.registerAction(new SpawnAction.Builder()
         .addInput(manifestProtoOutput)
         .addInput(classJar)
@@ -235,7 +283,7 @@ public class AndroidIdlHelper {
             .addExecPath("--class_jar", classJar)
             .addExecPath("--output_class_jar", idlClassJar)
             .addExecPath("--output_source_jar", idlSourceJar)
-            .add("--temp_dir").addPath(idlTempDir(ruleContext, idlClassJar))
+            .add("--temp_dir").addPath(idlTempDir)
             .addExecPaths(generatedIdlJavaFiles)
             .build())
         .useParameterFile(ParameterFileType.SHELL_QUOTED)
@@ -244,45 +292,27 @@ public class AndroidIdlHelper {
         .build(ruleContext));
   }
 
-  private static PathFragment idlTempDir(RuleContext ruleContext, Artifact outputJar) {
-    String basename = FileSystemUtils.removeExtension(outputJar.getExecPath().getBaseName());
-    return ruleContext.getConfiguration().getBinDirectory().getExecPath()
-        .getRelative(ruleContext.getUniqueDirectory("_idl"))
-        .getRelative(basename + "_temp");
-  }
-
-  private static void createAndroidIdlPreprocessAction(RuleContext ruleContext,
-      Artifact idl, Artifact preprocessed) {
-    AndroidSdkProvider sdk = AndroidSdkProvider.fromRuleContext(ruleContext);
-    ruleContext.registerAction(new SpawnAction.Builder()
-        .setExecutable(sdk.getAidl())
-        // Note the below may be an overapproximation of the actual runfiles, due to "conditional
-        // artifacts" (see Runfiles.PruningManifest).
-        // TODO(bazel-team): When using getFilesToRun(), the middleman is
-        // not expanded. Fix by providing code to expand and use getFilesToRun here.
-        .addInput(idl)
-        .addOutput(preprocessed)
-        .addArgument("--preprocess")
-        .addArgument(preprocessed.getExecPathString())
-        .addArgument(idl.getExecPathString())
-        .setProgressMessage("Android IDL preprocessing")
-        .setMnemonic("AndroidIDLPreprocess")
-        .build(ruleContext));
-  }
-
+  /**
+   * Creates an action to convert an .aidl source into a .java output.
+   *
+   * @param ruleContext The rule context in which to generate the action.
+   * @param idl The .aidl file to be converted to .java.
+   * @param idlImports The artifacts which should be accessible to this compilation action.
+   * @param output The .java file where the .aidl file will be converted to.
+   * @param importArgs The arguments defining the import roots and framework .aidl.
+   */
   private static void createAndroidIdlAction(RuleContext ruleContext,
-      Artifact idl, Iterable<Artifact> idlImports, Artifact preprocessedIdls,
-      Artifact output, List<String> preprocessedArgs) {
+      Artifact idl, NestedSet<Artifact> idlImports,
+      Artifact output, List<String> importArgs) {
     AndroidSdkProvider sdk = AndroidSdkProvider.fromRuleContext(ruleContext);
     ruleContext.registerAction(new SpawnAction.Builder()
         .setExecutable(sdk.getAidl())
         .addInput(idl)
         .addInputs(idlImports)
-        .addInput(preprocessedIdls)
         .addInput(sdk.getFrameworkAidl())
         .addOutput(output)
         .addArgument("-b") // Fail if trying to compile a parcelable.
-        .addArguments(preprocessedArgs)
+        .addArguments(importArgs)
         .addArgument(idl.getExecPathString())
         .addArgument(output.getExecPathString())
         .setProgressMessage("Android IDL generation")
@@ -301,6 +331,17 @@ public class AndroidIdlHelper {
         .build();
   }
 
+  /**
+   * Collects the importable .aidl files and AIDL class/source jars from this rule and its deps.
+   *
+   * @param ruleContext The rule context from which to harvest .aidl sources and parcelables, as
+   *     well as dependencies.
+   * @param idlClassJar An artifact corresponding to an AIDL class jar for this rule, or null if one
+   *     does not exist.
+   * @param idlSourceJar An artifact corresponding to an AIDL source jar for this rule, or null if
+   *     one does not exist.
+   * @return A provider containing the collected data, suitable to be provided by this rule.
+   */
   private static AndroidIdlProvider createAndroidIdlProvider(RuleContext ruleContext,
       @Nullable Artifact idlClassJar, @Nullable Artifact idlSourceJar) {
     NestedSetBuilder<String> rootsBuilder = NestedSetBuilder.naiveLinkOrder();
@@ -349,6 +390,9 @@ public class AndroidIdlHelper {
         importsBuilder.build(), jarsBuilder.build());
   }
 
+  /**
+   * Checks that idl_import_root is only set if idl_srcs or idl_parcelables was.
+   */
   private static void checkIdlRootImport(RuleContext ruleContext) {
     if (hasExplicitlySpecifiedIdlImportRoot(ruleContext)
         && !hasExplicitlySpecifiedIdlSrcsOrParcelables(ruleContext)) {
diff --git a/src/main/java/com/google/devtools/build/lib/rules/android/AndroidLibraryBaseRule.java b/src/main/java/com/google/devtools/build/lib/rules/android/AndroidLibraryBaseRule.java
index f1877165ee..48983045dd 100644
--- a/src/main/java/com/google/devtools/build/lib/rules/android/AndroidLibraryBaseRule.java
+++ b/src/main/java/com/google/devtools/build/lib/rules/android/AndroidLibraryBaseRule.java
@@ -97,9 +97,14 @@ public final class AndroidLibraryBaseRule implements RuleDefinition {
         /* <!-- #BLAZE_RULE(android_library).ATTRIBUTE(idl_import_root) -->
         Package-relative path to the root of the java package tree containing idl
         sources included in this library.
-        This path will be used as the import root when processing idl sources that
-        depend on this library. (See
-        <a href="#android_library_examples.idl_import_root">examples</a>.)
+        <p>This path will be used as the import root when processing idl sources that
+        depend on this library.</p>
+        <p>When <code>idl_import_root</code> is specified, both <code>idl_parcelables</code>
+        and <code>idl_srcs</code> must be at the path specified by the java package of the object
+        they represent under <code>idl_import_root</code>. When <code>idl_import_root</code> is
+        not specified, both <code>idl_parcelables</code> and <code>idl_srcs</code> must be at the
+        path specified by their package under a Java root.</p>
+        <p>See <a href="#android_library_examples.idl_import_root">examples</a>.</p>
         <!-- #END_BLAZE_RULE.ATTRIBUTE --> */
         .add(attr("idl_import_root", STRING))
         /* <!-- #BLAZE_RULE(android_library).ATTRIBUTE(idl_srcs) -->
@@ -109,6 +114,9 @@ public final class AndroidLibraryBaseRule implements RuleDefinition {
         <p>These files will be made available as imports for any
         <code>android_library</code> target that depends on this library, directly
         or via its transitive closure.</p>
+        <p>These files must be placed appropriately for the aidl compiler to find them.
+        See <a href="#android_library.idl_import_root">the description of idl_import_root</a>
+        for information about what this means.</p>
         <!-- #END_BLAZE_RULE.ATTRIBUTE --> */
         .add(attr("idl_srcs", LABEL_LIST).direct_compile_time_input()
             .allowedFileTypes(AndroidRuleClasses.ANDROID_IDL))
@@ -122,6 +130,9 @@ public final class AndroidLibraryBaseRule implements RuleDefinition {
         <code>.java</code> sources in this library should be included (e.g., custom
         implementations of Parcelable), otherwise <code>idl_srcs</code> should be
         used.</p>
+        <p>These files must be placed appropriately for the aidl compiler to find them.
+        See <a href="#android_library.idl_import_root">the description of idl_import_root</a>
+        for information about what this means.</p>
         <!-- #END_BLAZE_RULE.ATTRIBUTE --> */
         .add(attr("idl_parcelables", LABEL_LIST).direct_compile_time_input()
             .allowedFileTypes(AndroidRuleClasses.ANDROID_IDL))