From ee390f26eb899a8044a663ba7309d6de78fbb717 Mon Sep 17 00:00:00 2001 From: Anton Hansson Date: Thu, 16 Sep 2021 15:26:49 +0100 Subject: [PATCH] Enhance documentation in mainline stubs Metalava has a feature to "enhance documentation" which is mostly based on auto-generating documentation text based on source-retention annotations. This is turned on automatically for doc stubs, but here we are enabling it for module's jar stubs as well. The point of this is to be able to replace the module source code with module jar stub source code when generating doc stubs -- something previously not possible because most source-retention annotations are not present in the jar stubs. In order for the enhancement to work properly, metalava needs to be passed the annotation source code rather than the annotations library. This is because of various javadoc tags controlling what documentation is generated, e.g. @paramDoc, @returnDoc etc. Bug: 186197911 Test: manually inspect module stub source code is enhanced Change-Id: I3fda4cd64e49c1da33fe614c30aafd9fa0dba3b9 --- sdk/ModuleDefaults.bp | 13 ++++++++++--- 1 file changed, 10 insertions(+), 3 deletions(-) diff --git a/sdk/ModuleDefaults.bp b/sdk/ModuleDefaults.bp index 442fe60..877d979 100644 --- a/sdk/ModuleDefaults.bp +++ b/sdk/ModuleDefaults.bp @@ -30,7 +30,8 @@ mainline_stubs_args = "--hide SdkConstant " + "--hide Todo " + "--hide Typo " + - "--hide UnavailableSymbol " + "--hide UnavailableSymbol " + + "--enhance-documentation " // TODO: modularize this so not every module has the same list framework_packages_to_document = [ @@ -76,8 +77,14 @@ mainline_service_stubs_args = java_defaults { name: "framework-module-common-defaults", - // Additional annotations used for compiling both the implementation and the - // stubs libraries. + // Use the source of annotations that affect metalava doc generation, since + // the relevant generation instructions are themselves in javadoc, which is + // not present in class files. + api_srcs: [":framework-metalava-annotations"], + + // Make the source retention annotations available on the classpath when compiling + // the implementation library. (This should be in impl_only_libs but some modules + // use these defaults for java_library, sigh.) libs: ["framework-annotations-lib"], // Framework modules are not generally shared libraries, i.e. they are not