From 6877e6d951ab963c276c0f91c16b284f429a7374 Mon Sep 17 00:00:00 2001 From: Paul Duffin Date: Fri, 25 Sep 2020 19:59:14 +0100 Subject: [PATCH] Output Javadoc comments for public API When generating stubs source for contributions to the public API keep the Javadoc comments from the input source so that the stubs source can be used as input to the metalava invocation that creates the stubs from which the public Javadoc is generated. This is needed to fix an issue with conscrypt's contributions to the public API, i.e. SSLEngines and SSLSockets where the Javadoc comments were not present in the generated Javadoc. Test: Built offline-sdk-docs with and without the change and diffed them. The only difference was the timestamp.js file and they now included proper documentation for the SSLEngines/SSLSockets classes. Bug: 169162018 Change-Id: I1b50cff3b91766ce261b2f8e798b77ebc6faac70 --- java/droiddoc.go | 8 +++++++- java/sdk_library.go | 6 ++++++ 2 files changed, 13 insertions(+), 1 deletion(-) diff --git a/java/droiddoc.go b/java/droiddoc.go index 8b66dbf46..33f422d4e 100644 --- a/java/droiddoc.go +++ b/java/droiddoc.go @@ -253,6 +253,10 @@ type DroidstubsProperties struct { // if set to true, allow Metalava to generate doc_stubs source files. Defaults to false. Create_doc_stubs *bool + // if set to true, cause Metalava to output Javadoc comments in the stubs source files. Defaults to false. + // Has no effect if create_doc_stubs: true. + Output_javadoc_comments *bool + // if set to false then do not write out stubs. Defaults to true. // // TODO(b/146727827): Remove capability when we do not need to generate stubs and API separately. @@ -1150,7 +1154,9 @@ func (d *Droidstubs) stubsFlags(ctx android.ModuleContext, cmd *android.RuleBuil cmd.FlagWithArg("--doc-stubs ", stubsDir.String()) } else { cmd.FlagWithArg("--stubs ", stubsDir.String()) - cmd.Flag("--exclude-documentation-from-stubs") + if !Bool(d.properties.Output_javadoc_comments) { + cmd.Flag("--exclude-documentation-from-stubs") + } } } } diff --git a/java/sdk_library.go b/java/sdk_library.go index a7b92b3a8..0d29a3763 100644 --- a/java/sdk_library.go +++ b/java/sdk_library.go @@ -1203,6 +1203,7 @@ func (module *SdkLibrary) createStubsSourcesAndApi(mctx android.DefaultableHookC Sdk_version *string System_modules *string Libs []string + Output_javadoc_comments *bool Arg_files []string Args *string Java_version *string @@ -1278,6 +1279,11 @@ func (module *SdkLibrary) createStubsSourcesAndApi(mctx android.DefaultableHookC } droidstubsArgs = append(droidstubsArgs, android.JoinWithPrefix(disabledWarnings, "--hide ")) + // Output Javadoc comments for public scope. + if apiScope == apiScopePublic { + props.Output_javadoc_comments = proptools.BoolPtr(true) + } + // Add in scope specific arguments. droidstubsArgs = append(droidstubsArgs, scopeSpecificDroidstubsArgs...) props.Arg_files = module.sdkLibraryProperties.Droiddoc_option_files