Add Api level annotations support for Metalava.

Test: m -j docs with Api level annotations enabled.
Bug: b/78245848

Change-Id: Ife93899cdcf5b54ee0c75003c295aa4b917d3dba

java/droiddoc.go

@@ -321,6 +321,10 @@ type DroidstubsProperties struct {
 	// the generated removed Dex API filename by Doclava.
 	Removed_dex_api_filename *string
 
+	// mapping of dex signatures to source file and line number. This is a temporary property and
+	// will be deleted; you probably shouldn't be using it.
+	Dex_mapping_filename *string
+
 	// the generated exact API filename by Doclava.
 	Exact_api_filename *string
 
@@ -341,6 +345,16 @@ type DroidstubsProperties struct {
 
 	// if set to true, allow Metalava to generate doc_stubs source files. Defaults to false.
 	Create_doc_stubs *bool
+
+	// is set to true, Metalava will allow framework SDK to contain API levels annotations.
+	Api_levels_annotations_enabled *bool
+
+	// the dirs which Metalava extracts API levels annotations from.
+	Api_levels_annotations_dirs []string
+
+	// if set to true, collect the values used by the Dev tools and
+	// write them in files packaged with the SDK. Defaults to false.
+	Write_sdk_values *bool
 }
 
 //
@@ -359,7 +373,7 @@ type droiddocBuilderFlags struct {
 
 	metalavaStubsFlags                string
 	metalavaAnnotationsFlags          string
-	metalavaJavadocFlags     string
+	metalavaApiLevelsAnnotationsFlags string
 
 	metalavaDokkaFlags string
 }
@@ -643,7 +657,7 @@ func (j *Javadoc) collectDeps(ctx android.ModuleContext) deps {
 	j.docZip = android.PathForModuleOut(ctx, ctx.ModuleName()+"-"+"docs.zip")
 	j.stubsSrcJar = android.PathForModuleOut(ctx, ctx.ModuleName()+"-"+"stubs.srcjar")
 
-	if j.properties.Local_sourcepaths == nil {
+	if j.properties.Local_sourcepaths == nil && len(j.srcFiles) > 0 {
 		j.properties.Local_sourcepaths = append(j.properties.Local_sourcepaths, ".")
 	}
 	j.sourcepaths = android.PathsForModuleSrc(ctx, j.properties.Local_sourcepaths)
@@ -831,7 +845,16 @@ func (d *Droiddoc) initBuilderFlags(ctx android.ModuleContext, implicits *androi
 	dokkaClasspath = append(dokkaClasspath, deps.classpath...)
 	flags.dokkaClasspathArgs = dokkaClasspath.FormJavaClassPath("-classpath")
 
+	// TODO(nanzhang): Remove this if- statement once we finish migration for all Doclava
+	// based stubs generation.
+	// In the future, all the docs generation depends on Metalava stubs (droidstubs) srcjar
+	// dir. We need add the srcjar dir to -sourcepath arg, so that Javadoc can figure out
+	// the correct package name base path.
+	if len(d.Javadoc.properties.Local_sourcepaths) > 0 {
 		flags.sourcepathArgs = "-sourcepath " + strings.Join(d.Javadoc.sourcepaths.Strings(), ":")
+	} else {
+		flags.sourcepathArgs = "-sourcepath " + android.PathForModuleOut(ctx, "srcjars").String()
+	}
 
 	return flags, nil
 }
@@ -1173,6 +1196,7 @@ type Droidstubs struct {
 	privateDexApiFile android.WritablePath
 	removedApiFile    android.WritablePath
 	removedDexApiFile android.WritablePath
+	apiMappingFile    android.WritablePath
 	exactApiFile      android.WritablePath
 
 	checkCurrentApiTimestamp      android.WritablePath
@@ -1180,6 +1204,7 @@ type Droidstubs struct {
 	checkLastReleasedApiTimestamp android.WritablePath
 
 	annotationsZip android.WritablePath
+	apiVersionsXml android.WritablePath
 
 	apiFilePath android.Path
 }
@@ -1230,6 +1255,12 @@ func (d *Droidstubs) DepsMutator(ctx android.BottomUpMutatorContext) {
 			ctx.AddDependency(ctx.Module(), metalavaMergeAnnotationsDirTag, mergeAnnotationsDir)
 		}
 	}
+
+	if len(d.properties.Api_levels_annotations_dirs) != 0 {
+		for _, apiLevelsAnnotationsDir := range d.properties.Api_levels_annotations_dirs {
+			ctx.AddDependency(ctx.Module(), metalavaAPILevelsAnnotationsDirTag, apiLevelsAnnotationsDir)
+		}
+	}
 }
 
 func (d *Droidstubs) initBuilderFlags(ctx android.ModuleContext, implicits *android.Paths,
@@ -1302,6 +1333,16 @@ func (d *Droidstubs) collectStubsFlags(ctx android.ModuleContext,
 		*implicitOutputs = append(*implicitOutputs, d.exactApiFile)
 	}
 
+	if String(d.properties.Dex_mapping_filename) != "" {
+		d.apiMappingFile = android.PathForModuleOut(ctx, String(d.properties.Dex_mapping_filename))
+		metalavaFlags = metalavaFlags + " --dex-api-mapping " + d.apiMappingFile.String()
+		*implicitOutputs = append(*implicitOutputs, d.apiMappingFile)
+	}
+
+	if Bool(d.properties.Write_sdk_values) {
+		metalavaFlags = metalavaFlags + " --sdk-values " + android.PathForModuleOut(ctx, "out").String()
+	}
+
 	if Bool(d.properties.Create_doc_stubs) {
 		metalavaFlags += " --doc-stubs " + android.PathForModuleOut(ctx, "stubsDir").String()
 	} else {
@@ -1331,7 +1372,7 @@ func (d *Droidstubs) collectAnnotationsFlags(ctx android.ModuleContext,
 		flags += " --extract-annotations " + d.annotationsZip.String()
 
 		if len(d.properties.Merge_annotations_dirs) == 0 {
-			ctx.PropertyErrorf("metalava_merge_annotations_dirs",
+			ctx.PropertyErrorf("merge_annotations_dirs",
 				"has to be non-empty if annotations was enabled!")
 		}
 		ctx.VisitDirectDepsWithTag(metalavaMergeAnnotationsDirTag, func(m android.Module) {
@@ -1339,7 +1380,7 @@ func (d *Droidstubs) collectAnnotationsFlags(ctx android.ModuleContext,
 				*implicits = append(*implicits, t.deps...)
 				flags += " --merge-annotations " + t.dir.String()
 			} else {
-				ctx.PropertyErrorf("metalava_merge_annotations_dirs",
+				ctx.PropertyErrorf("merge_annotations_dirs",
 					"module %q is not a metalava merge-annotations dir", ctx.OtherModuleName(m))
 			}
 		})
@@ -1350,9 +1391,47 @@ func (d *Droidstubs) collectAnnotationsFlags(ctx android.ModuleContext,
 	return flags
 }
 
+func (d *Droidstubs) collectAPILevelsAnnotationsFlags(ctx android.ModuleContext,
+	implicits *android.Paths, implicitOutputs *android.WritablePaths) string {
+	var flags string
+	if Bool(d.properties.Api_levels_annotations_enabled) {
+		d.apiVersionsXml = android.PathForModuleOut(ctx, "api-versions.xml")
+		*implicitOutputs = append(*implicitOutputs, d.apiVersionsXml)
+
+		if len(d.properties.Api_levels_annotations_dirs) == 0 {
+			ctx.PropertyErrorf("api_levels_annotations_dirs",
+				"has to be non-empty if api levels annotations was enabled!")
+		}
+
+		flags = " --generate-api-levels " + d.apiVersionsXml.String() + " --apply-api-levels " +
+			d.apiVersionsXml.String() + " --current-version " + ctx.Config().PlatformSdkVersion() +
+			" --current-codename " + ctx.Config().PlatformSdkCodename() + " "
+
+		ctx.VisitDirectDepsWithTag(metalavaAPILevelsAnnotationsDirTag, func(m android.Module) {
+			if t, ok := m.(*ExportedDroiddocDir); ok {
+				var androidJars android.Paths
+				for _, dep := range t.deps {
+					if strings.HasSuffix(dep.String(), "android.jar") {
+						androidJars = append(androidJars, dep)
+					}
+				}
+				*implicits = append(*implicits, androidJars...)
+				flags += " --android-jar-pattern " + t.dir.String() + "/%/android.jar "
+			} else {
+				ctx.PropertyErrorf("api_levels_annotations_dirs",
+					"module %q is not a metalava api-levels-annotations dir", ctx.OtherModuleName(m))
+			}
+		})
+
+	}
+
+	return flags
+}
+
 func (d *Droidstubs) transformMetalava(ctx android.ModuleContext, implicits android.Paths,
 	implicitOutputs android.WritablePaths, javaVersion,
 	bootclasspathArgs, classpathArgs, sourcepathArgs, opts string) {
+
 	ctx.Build(pctx, android.BuildParams{
 		Rule:            metalava,
 		Description:     "Metalava",
@@ -1401,9 +1480,6 @@ func (d *Droidstubs) transformCheckApi(ctx android.ModuleContext,
 func (d *Droidstubs) GenerateAndroidBuildActions(ctx android.ModuleContext) {
 	deps := d.Javadoc.collectDeps(ctx)
 
-	// always set installable to false for droidstubs, since droidstubs doesn't create doc.zip file.
-	*d.Javadoc.properties.Installable = false
-
 	javaVersion := getJavaVersion(ctx, String(d.Javadoc.properties.Java_version), sdkContext(d))
 
 	var implicits android.Paths
@@ -1423,6 +1499,7 @@ func (d *Droidstubs) GenerateAndroidBuildActions(ctx android.ModuleContext) {
 
 	flags.metalavaStubsFlags = d.collectStubsFlags(ctx, &implicitOutputs)
 	flags.metalavaAnnotationsFlags = d.collectAnnotationsFlags(ctx, &implicits, &implicitOutputs)
+	flags.metalavaApiLevelsAnnotationsFlags = d.collectAPILevelsAnnotationsFlags(ctx, &implicits, &implicitOutputs)
 	if strings.Contains(d.Javadoc.args, "--generate-documentation") {
 		// Currently Metalava have the ability to invoke Javadoc in a seperate process.
 		// Pass "-nodocs" to suppress the Javadoc invocation when Metalava receives
@@ -1431,7 +1508,8 @@ func (d *Droidstubs) GenerateAndroidBuildActions(ctx android.ModuleContext) {
 	}
 	d.transformMetalava(ctx, implicits, implicitOutputs, javaVersion,
 		flags.bootClasspathArgs, flags.classpathArgs, flags.sourcepathArgs,
-		flags.metalavaStubsFlags+flags.metalavaAnnotationsFlags+" "+d.Javadoc.args)
+		flags.metalavaStubsFlags+flags.metalavaAnnotationsFlags+
+			flags.metalavaApiLevelsAnnotationsFlags+" "+d.Javadoc.args)
 
 	if apiCheckEnabled(d.properties.Check_api.Current, "current") &&
 		!ctx.Config().IsPdkBuild() {
@@ -1489,6 +1567,7 @@ func (d *Droidstubs) GenerateAndroidBuildActions(ctx android.ModuleContext) {
 //
 var droiddocTemplateTag = dependencyTag{name: "droiddoc-template"}
 var metalavaMergeAnnotationsDirTag = dependencyTag{name: "metalava-merge-annotations-dir"}
+var metalavaAPILevelsAnnotationsDirTag = dependencyTag{name: "metalava-api-levels-annotations-dir"}
 
 type ExportedDroiddocDirProperties struct {
 	// path to the directory containing Droiddoc related files.