Merge "Support Dokka in Soong."

java/config/config.go

@@ -121,6 +121,7 @@ func init() {
 	pctx.HostJavaToolVariable("JsilverJar", "jsilver.jar")
 	pctx.HostJavaToolVariable("DoclavaJar", "doclava.jar")
 	pctx.HostJavaToolVariable("MetalavaJar", "metalava.jar")
+	pctx.HostJavaToolVariable("DokkaJar", "dokka.jar")
 
 	pctx.HostBinToolVariable("SoongJavacWrapper", "soong_javac_wrapper")
 

java/droiddoc.go

@@ -265,26 +265,31 @@ type DroiddocProperties struct {
 
 	// a list of top-level directories containing files to merge annotations from.
 	Metalava_merge_annotations_dirs []string
+
+	// if set to true, generate docs through Dokka instead of Doclava. Valid only when
+	// metalava_enabled is set to true.
+	Dokka_enabled *bool
 }
 
 //
 // Common flags passed down to build rule
 //
 type droiddocBuilderFlags struct {
-	args              string
+	args               string
-	bootClasspathArgs string
+	bootClasspathArgs  string
-	classpathArgs     string
+	classpathArgs      string
-	aidlFlags         string
+	dokkaClasspathArgs string
+	aidlFlags          string
 
-	doclavaDocsFlags  string
 	doclavaStubsFlags string
+	doclavaDocsFlags  string
 	postDoclavaCmds   string
 
-	metalavaAnnotationsFlags string
-	metalavaDocsFlags        string
 	metalavaStubsFlags       string
+	metalavaAnnotationsFlags string
+	metalavaJavadocFlags     string
 
-	dokkaFlags string
+	metalavaDokkaFlags string
 }
 
 func InitDroiddocModule(module android.DefaultableModule, hod android.HostOrDeviceSupported) {
@@ -720,6 +725,11 @@ func (d *Droiddoc) initBuilderFlags(ctx android.ModuleContext, implicits *androi
 		flags.bootClasspathArgs = deps.bootClasspath.FormJavaClassPath("-bootclasspath")
 	}
 	flags.classpathArgs = deps.classpath.FormJavaClassPath("-classpath")
+	// Dokka doesn't support boocClasspath, so combine these two classpath vars for Dokka.
+	dokkaClasspath := classpath{}
+	dokkaClasspath = append(dokkaClasspath, deps.bootClasspath...)
+	dokkaClasspath = append(dokkaClasspath, deps.classpath...)
+	flags.dokkaClasspathArgs = dokkaClasspath.FormJavaClassPath("-classpath")
 
 	argFiles := ctx.ExpandSources(d.properties.Arg_files, nil)
 	argFilesMap := map[string]android.Path{}
@@ -969,7 +979,7 @@ func (d *Droiddoc) collectMetalavaAnnotationsFlags(
 	return flags
 }
 
-func (d *Droiddoc) collectMetalavaDocsFlags(ctx android.ModuleContext,
+func (d *Droiddoc) collectMetalavaJavadocFlags(ctx android.ModuleContext,
 	bootClasspathArgs, classpathArgs, outDir, docStubsDir string) string {
 	return " --doc-stubs " + docStubsDir +
 		" --write-doc-stubs-source-list " + android.PathForModuleOut(ctx, "doc_stubs.srclist").String() +
@@ -978,6 +988,104 @@ func (d *Droiddoc) collectMetalavaDocsFlags(ctx android.ModuleContext,
 		docStubsDir + " -quiet -d " + outDir
 }
 
+func (d *Droiddoc) collectMetalavaDokkaFlags(ctx android.ModuleContext, implicits *android.Paths,
+	classpathArgs, outDir, docStubsDir string) string {
+	dokka := android.PathForOutput(ctx, "host", ctx.Config().PrebuiltOS(), "framework", "dokka.jar")
+	*implicits = append(*implicits, dokka)
+
+	return " --doc-stubs " + docStubsDir + " --write-doc-stubs-source-list " +
+		android.PathForModuleOut(ctx, "doc_stubs.srclist").String() +
+		" --generate-documentation ${config.JavaCmd} -jar " + dokka.String() + " " +
+		docStubsDir + " " + classpathArgs + " -format dac -dacRoot /reference/kotlin -output " + outDir
+}
+
+func (d *Droiddoc) transformMetalava(ctx android.ModuleContext, implicits android.Paths,
+	implicitOutputs android.WritablePaths, outDir, docStubsDir, javaVersion,
+	bootclasspathArgs, classpathArgs, opts string) {
+	ctx.Build(pctx, android.BuildParams{
+		Rule:            metalava,
+		Description:     "Metalava",
+		Output:          d.Javadoc.stubsSrcJar,
+		Inputs:          d.Javadoc.srcFiles,
+		Implicits:       implicits,
+		ImplicitOutputs: implicitOutputs,
+		Args: map[string]string{
+			"outDir":            outDir,
+			"srcJarDir":         android.PathForModuleOut(ctx, "srcjars").String(),
+			"stubsDir":          android.PathForModuleOut(ctx, "stubsDir").String(),
+			"docStubsDir":       docStubsDir,
+			"srcJars":           strings.Join(d.Javadoc.srcJars.Strings(), " "),
+			"javaVersion":       javaVersion,
+			"bootclasspathArgs": bootclasspathArgs,
+			"classpathArgs":     classpathArgs,
+			"sourcepath":        strings.Join(d.Javadoc.sourcepaths.Strings(), ":"),
+			"docZip":            d.Javadoc.docZip.String(),
+			"opts":              opts,
+		},
+	})
+}
+
+func (d *Droiddoc) transformDoclava(ctx android.ModuleContext, implicits android.Paths,
+	implicitOutputs android.WritablePaths, bootclasspathArgs, classpathArgs, opts, postDoclavaCmds string) {
+	ctx.Build(pctx, android.BuildParams{
+		Rule:            javadoc,
+		Description:     "Doclava",
+		Output:          d.Javadoc.stubsSrcJar,
+		Inputs:          d.Javadoc.srcFiles,
+		Implicits:       implicits,
+		ImplicitOutputs: implicitOutputs,
+		Args: map[string]string{
+			"outDir":            android.PathForModuleOut(ctx, "out").String(),
+			"srcJarDir":         android.PathForModuleOut(ctx, "srcjars").String(),
+			"stubsDir":          android.PathForModuleOut(ctx, "stubsDir").String(),
+			"srcJars":           strings.Join(d.Javadoc.srcJars.Strings(), " "),
+			"opts":              opts,
+			"bootclasspathArgs": bootclasspathArgs,
+			"classpathArgs":     classpathArgs,
+			"sourcepath":        strings.Join(d.Javadoc.sourcepaths.Strings(), ":"),
+			"docZip":            d.Javadoc.docZip.String(),
+			"postDoclavaCmds":   postDoclavaCmds,
+		},
+	})
+}
+
+func (d *Droiddoc) transformCheckApi(ctx android.ModuleContext, apiFile, removedApiFile android.Path,
+	checkApiClasspath classpath, msg, opts string, output android.WritablePath) {
+	ctx.Build(pctx, android.BuildParams{
+		Rule:        apiCheck,
+		Description: "Check API",
+		Output:      output,
+		Inputs:      nil,
+		Implicits: append(android.Paths{apiFile, removedApiFile, d.apiFile, d.removedApiFile},
+			checkApiClasspath...),
+		Args: map[string]string{
+			"classpath":             checkApiClasspath.FormJavaClassPath(""),
+			"opts":                  opts,
+			"apiFile":               apiFile.String(),
+			"apiFileToCheck":        d.apiFile.String(),
+			"removedApiFile":        removedApiFile.String(),
+			"removedApiFileToCheck": d.removedApiFile.String(),
+			"msg": msg,
+		},
+	})
+}
+
+func (d *Droiddoc) transformUpdateApi(ctx android.ModuleContext, apiFile, removedApiFile android.Path,
+	output android.WritablePath) {
+	ctx.Build(pctx, android.BuildParams{
+		Rule:        updateApi,
+		Description: "Update API",
+		Output:      output,
+		Implicits:   append(android.Paths{}, apiFile, removedApiFile, d.apiFile, d.removedApiFile),
+		Args: map[string]string{
+			"apiFile":               apiFile.String(),
+			"apiFileToCheck":        d.apiFile.String(),
+			"removedApiFile":        removedApiFile.String(),
+			"removedApiFileToCheck": d.removedApiFile.String(),
+		},
+	})
+}
+
 func (d *Droiddoc) GenerateAndroidBuildActions(ctx android.ModuleContext) {
 	deps := d.Javadoc.collectDeps(ctx)
 
@@ -1008,68 +1116,41 @@ func (d *Droiddoc) GenerateAndroidBuildActions(ctx android.ModuleContext) {
 		return
 	}
 
-	outDir := android.PathForModuleOut(ctx, "out").String()
 	flags.doclavaStubsFlags, flags.metalavaStubsFlags = d.collectStubsFlags(ctx, &implicitOutputs)
 	if Bool(d.properties.Metalava_enabled) {
-		opts := flags.metalavaStubsFlags
 		flags.metalavaAnnotationsFlags = d.collectMetalavaAnnotationsFlags(ctx, &implicits, &implicitOutputs)
-		opts += flags.metalavaAnnotationsFlags
+		outDir := android.PathForModuleOut(ctx, "out").String()
 		docStubsDir := android.PathForModuleOut(ctx, "docStubsDir").String()
-		if strings.Contains(flags.args, "--generate-documentation") {
+		// TODO(nanzhang): Add a Soong property to handle documentation args.
-			// TODO(nanzhang): Add a Soong property to handle documentation args.
+		if strings.Contains(flags.args, "--generate-documentation") { // enable docs generation
-			flags.doclavaDocsFlags = d.collectDoclavaDocsFlags(ctx, &implicits, javaVersion, jsilver, doclava)
+			if Bool(d.properties.Dokka_enabled) {
-			flags.metalavaDocsFlags = d.collectMetalavaDocsFlags(ctx,
+				flags.metalavaDokkaFlags = d.collectMetalavaDokkaFlags(ctx, &implicits,
-				flags.bootClasspathArgs, flags.classpathArgs, outDir, docStubsDir)
+					flags.dokkaClasspathArgs, outDir, docStubsDir)
-			opts += " " + strings.Split(flags.args, "--generate-documentation")[0] + " " +
+				d.transformMetalava(ctx, implicits, implicitOutputs, outDir, docStubsDir, javaVersion,
-				flags.metalavaDocsFlags + flags.doclavaDocsFlags +
+					flags.bootClasspathArgs, flags.classpathArgs, flags.metalavaStubsFlags+
-				" " + strings.Split(flags.args, "--generate-documentation")[1]
+						flags.metalavaAnnotationsFlags+" "+strings.Split(flags.args, "--generate-documentation")[0]+
+						flags.metalavaDokkaFlags+" "+strings.Split(flags.args, "--generate-documentation")[1])
+			} else {
+				flags.metalavaJavadocFlags = d.collectMetalavaJavadocFlags(
+					ctx, flags.bootClasspathArgs, flags.classpathArgs, outDir, docStubsDir)
+				flags.doclavaDocsFlags = d.collectDoclavaDocsFlags(ctx, &implicits, javaVersion, jsilver, doclava)
+				d.transformMetalava(ctx, implicits, implicitOutputs, outDir, docStubsDir, javaVersion,
+					flags.bootClasspathArgs, flags.classpathArgs, flags.metalavaStubsFlags+
+						flags.metalavaAnnotationsFlags+" "+strings.Split(flags.args, "--generate-documentation")[0]+
+						flags.metalavaJavadocFlags+flags.doclavaDocsFlags+
+						" "+strings.Split(flags.args, "--generate-documentation")[1])
+			}
 		} else {
-			opts += " " + flags.args
+			d.transformMetalava(ctx, implicits, implicitOutputs, outDir, docStubsDir, javaVersion,
+				flags.bootClasspathArgs, flags.classpathArgs,
+				flags.metalavaStubsFlags+flags.metalavaAnnotationsFlags+flags.args)
 		}
-		ctx.Build(pctx, android.BuildParams{
-			Rule:            metalava,
-			Description:     "Metalava",
-			Output:          d.Javadoc.stubsSrcJar,
-			Inputs:          d.Javadoc.srcFiles,
-			Implicits:       implicits,
-			ImplicitOutputs: implicitOutputs,
-			Args: map[string]string{
-				"outDir":            outDir,
-				"srcJarDir":         android.PathForModuleOut(ctx, "srcjars").String(),
-				"stubsDir":          android.PathForModuleOut(ctx, "stubsDir").String(),
-				"docStubsDir":       docStubsDir,
-				"srcJars":           strings.Join(d.Javadoc.srcJars.Strings(), " "),
-				"javaVersion":       javaVersion,
-				"bootclasspathArgs": flags.bootClasspathArgs,
-				"classpathArgs":     flags.classpathArgs,
-				"sourcepath":        strings.Join(d.Javadoc.sourcepaths.Strings(), ":"),
-				"docZip":            d.Javadoc.docZip.String(),
-				"opts":              opts,
-			},
-		})
 	} else {
 		flags.doclavaDocsFlags = d.collectDoclavaDocsFlags(ctx, &implicits, javaVersion, jsilver, doclava)
 		flags.postDoclavaCmds = d.getPostDoclavaCmds(ctx, &implicits)
-		ctx.Build(pctx, android.BuildParams{
+		d.transformDoclava(ctx, implicits, implicitOutputs, flags.bootClasspathArgs, flags.classpathArgs,
-			Rule:            javadoc,
+			flags.doclavaDocsFlags+flags.doclavaStubsFlags+" "+flags.args,
-			Description:     "Droiddoc",
+			flags.postDoclavaCmds)
-			Output:          d.Javadoc.stubsSrcJar,
-			Inputs:          d.Javadoc.srcFiles,
-			Implicits:       implicits,
-			ImplicitOutputs: implicitOutputs,
-			Args: map[string]string{
-				"outDir":            outDir,
-				"srcJarDir":         android.PathForModuleOut(ctx, "srcjars").String(),
-				"stubsDir":          android.PathForModuleOut(ctx, "stubsDir").String(),
-				"srcJars":           strings.Join(d.Javadoc.srcJars.Strings(), " "),
-				"opts":              flags.doclavaDocsFlags + flags.doclavaStubsFlags + " " + flags.args,
-				"bootclasspathArgs": flags.bootClasspathArgs,
-				"classpathArgs":     flags.classpathArgs,
-				"sourcepath":        strings.Join(d.Javadoc.sourcepaths.Strings(), ":"),
-				"docZip":            d.Javadoc.docZip.String(),
-				"postDoclavaCmds":   flags.postDoclavaCmds,
-			},
-		})
 	}
 
 	if d.checkCurrentApi() && !ctx.Config().IsPdkBuild() {
@@ -1080,46 +1161,21 @@ func (d *Droiddoc) GenerateAndroidBuildActions(ctx android.ModuleContext) {
 		removedApiFile := ctx.ExpandSource(String(d.properties.Check_api.Current.Removed_api_file),
 			"check_api.current_removed_api_file")
 
-		ctx.Build(pctx, android.BuildParams{
+		d.transformCheckApi(ctx, apiFile, removedApiFile, checkApiClasspath,
-			Rule:        apiCheck,
+			fmt.Sprintf(`\n******************************\n`+
-			Description: "Current API check",
+				`You have tried to change the API from what has been previously approved.\n\n`+
-			Output:      d.checkCurrentApiTimestamp,
+				`To make these errors go away, you have two choices:\n`+
-			Inputs:      nil,
+				`   1. You can add '@hide' javadoc comments to the methods, etc. listed in the\n`+
-			Implicits: append(android.Paths{apiFile, removedApiFile, d.apiFile, d.removedApiFile},
+				`      errors above.\n\n`+
-				checkApiClasspath...),
+				`   2. You can update current.txt by executing the following command:\n`+
-			Args: map[string]string{
+				`         make %s-update-current-api\n\n`+
-				"classpath":             checkApiClasspath.FormJavaClassPath(""),
+				`      To submit the revised current.txt to the main Android repository,\n`+
-				"opts":                  String(d.properties.Check_api.Current.Args),
+				`      you will need approval.\n`+
-				"apiFile":               apiFile.String(),
+				`******************************\n`, ctx.ModuleName()), String(d.properties.Check_api.Current.Args),
-				"apiFileToCheck":        d.apiFile.String(),
+			d.checkCurrentApiTimestamp)
-				"removedApiFile":        removedApiFile.String(),
-				"removedApiFileToCheck": d.removedApiFile.String(),
-				"msg": fmt.Sprintf(`\n******************************\n`+
-					`You have tried to change the API from what has been previously approved.\n\n`+
-					`To make these errors go away, you have two choices:\n`+
-					`   1. You can add '@hide' javadoc comments to the methods, etc. listed in the\n`+
-					`      errors above.\n\n`+
-					`   2. You can update current.txt by executing the following command:\n`+
-					`         make %s-update-current-api\n\n`+
-					`      To submit the revised current.txt to the main Android repository,\n`+
-					`      you will need approval.\n`+
-					`******************************\n`, ctx.ModuleName()),
-			},
-		})
 
 		d.updateCurrentApiTimestamp = android.PathForModuleOut(ctx, "update_current_api.timestamp")
-		ctx.Build(pctx, android.BuildParams{
+		d.transformUpdateApi(ctx, apiFile, removedApiFile, d.updateCurrentApiTimestamp)
-			Rule:        updateApi,
-			Description: "update current API",
-			Output:      d.updateCurrentApiTimestamp,
-			Implicits:   append(android.Paths{}, apiFile, removedApiFile, d.apiFile, d.removedApiFile),
-			Args: map[string]string{
-				"apiFile":               apiFile.String(),
-				"apiFileToCheck":        d.apiFile.String(),
-				"removedApiFile":        removedApiFile.String(),
-				"removedApiFileToCheck": d.removedApiFile.String(),
-			},
-		})
 	}
 
 	if d.checkLastReleasedApi() && !ctx.Config().IsPdkBuild() {
@@ -1130,26 +1186,12 @@ func (d *Droiddoc) GenerateAndroidBuildActions(ctx android.ModuleContext) {
 		removedApiFile := ctx.ExpandSource(String(d.properties.Check_api.Last_released.Removed_api_file),
 			"check_api.last_released.removed_api_file")
 
-		ctx.Build(pctx, android.BuildParams{
+		d.transformCheckApi(ctx, apiFile, removedApiFile, checkApiClasspath,
-			Rule:        apiCheck,
+			`\n******************************\n`+
-			Description: "Last Released API check",
+				`You have tried to change the API from what has been previously released in\n`+
-			Output:      d.checkLastReleasedApiTimestamp,
+				`an SDK.  Please fix the errors listed above.\n`+
-			Inputs:      nil,
+				`******************************\n`, String(d.properties.Check_api.Last_released.Args),
-			Implicits: append(android.Paths{apiFile, removedApiFile, d.apiFile, d.removedApiFile},
+			d.checkLastReleasedApiTimestamp)
-				checkApiClasspath...),
-			Args: map[string]string{
-				"classpath":             checkApiClasspath.FormJavaClassPath(""),
-				"opts":                  String(d.properties.Check_api.Last_released.Args),
-				"apiFile":               apiFile.String(),
-				"apiFileToCheck":        d.apiFile.String(),
-				"removedApiFile":        removedApiFile.String(),
-				"removedApiFileToCheck": d.removedApiFile.String(),
-				"msg": `\n******************************\n` +
-					`You have tried to change the API from what has been previously released in\n` +
-					`an SDK.  Please fix the errors listed above.\n` +
-					`******************************\n`,
-			},
-		})
 	}
 }