[Mono.Android] Generate Mono.Android.xml; @(JavaSourceJar) on JDK11 (#5253)

Fixes: #4789

Context: dotnet/java-interop@7574f16
Context: #5200

What do we want?  Updated documentation!  Better Bindings!

How do we get that?  Uh…

Historically, [Xamarin.Android API docs][0] were produced by parsing
Android's HTML documentation from `docs-24_r01.zip` and converting it
into [**mdoc**(5) documentation][1] via `tools/javadoc2mdoc`.
The problem is that Google hasn't released an updated `docs*.zip`
package since API-24 (~6 years ago), and thus our documentation is
woefully out of date.

We could have scraped developer.android.com/reference within that
time frame, but web scraping is annoying, and we'd still have to deal
with the pain of parsing HTML.

There is an alternative, though: with API-30, there is a new `sources`
package which contains the Java source code used for the API level,
which in turn contains Javadoc source code comments.  Previous API
levels similarly contained an `android-stubs-src.jar` file which
likewise contained Java source code containing Javadoc comments.

The new approach is to:

 1. Update `build-tools/xaprepare` to install the `sources` package.

 2. Use [`java-source-tool.jar`][2] to parse the Java source code,
    creating an `android-javadoc.xml` file.

 3. [Update `generator`][3] to consume `android-javadoc.xml` and
    convert the Javadocs into [C# XML documentation comments][4].

 4. Update `src/Mono.Android` so that `generator` will emit
    C# XML doc comments, and then produce a `Mono.Android.xml` file.

The result is a `Mono.Android.xml` file which contains imported
Android Javadoc documentation, e.g.

	<doc>
	  <assembly><name>Mono.Android</name></assembly>
	  <members>
	    <member name="T:Java.Lang.Object">
	      <summary>Class <c>Object</c> is the root of the class hierarchy.</summary>
	      <remarks>
	        <para>Class <c>Object</c> is the root of the class hierarchy.
	…

"Later", `Mono.Android.xml` can then be used alongside
[`mdoc update --import=Mono.Android.xml`][5] to update our published
API documentation.

Generation of `Mono.Android.xml` is disabled by default on CI PR
builds, as generating `Mono.Android.xml` increases `src/Mono.Android`
build times by an unacceptable amount.

With the inclusion of `java-source-tools.jar`, we can now fix the
TODO mentioned in commit 380e95e, and re-add support for
`@(JavaSourceJar)` when running under JDK 11.

Update `Xamarin.Android.Bindings.Core.targets` so that before
invoking `generator`, we first run `java-source-utils.jar` on the
`@(JavaSourceJar)` files, producing Javadoc XML files.
The `<BindingsGenerator/>` task in turn is updated to accept a new
`BindingsGenerator.JavadocXml` property, which is converted into a
`generator --with-javadoc-xml=FILE` option.

The `@(JavaSourceJar)` item group is "extended" to support the
following item metadata:

  * `%(CopyrightFile)`: A path to a file that contains copyright
    information for the Javadoc contents, which will be appended to
	all imported documentation.

  * `%(UrlPrefix)`: A URL prefix to support linking to online
    documentation within imported documentation.

  * `%(UrlStyle)`: The "style" of URLs to generate when linking to
    online documentation.  Only one style is currently supported:
    `developer.android.com/reference@2020-Nov`.

For .NET 6 ("One .NET") integration purposes, provide a default item
group of `@(JavaSourceJar)` which includes `**\*-source*.jar` and
`**\*-src.jar`.  This will allow `dotnet build` of an "Android Java
Library Binding" project (`dotnet new android-bindinglib`) to
automatically process `.java` source code for documentation
translation purposes.

Add a new `$(AndroidJavadocVerbosity)` MSBuild property, which
controls "how much" of the Javadoc comments are converted into C#
XML documentation.  Supported values are:

  * `full`: Convert as much Javadoc as possible.
  * `intellisense`: Only emit XML documentation for IDE-useful
    constructs: summary, parameters, returns, exceptions.

The difference between the two is *build time* impact: `full` takes
longer, and thus may not always be desirable.

Finally, add a new `$(_UseLegacyJavadocImport)` MSBuild property
which *disables* use of `java-source-utils.jar` for Javadoc importing,
and instead use the previous, legacy, doesn't work on JDK 11,
approach of using `javadoc` and HTML parsing.  This shouldn't be
needed, but just in case it *is* needed…

[0]: https://github.com/xamarin/android-api-docs
[1]: http://docs.go-mono.com/?link=man%3amdoc(5)
[2]: dotnet/java-interop@69e1b80
[3]: dotnet/java-interop#687
[4]: https://docs.microsoft.com/dotnet/csharp/codedoc
[5]: http://docs.go-mono.com/?link=man%3amdoc-update(1)

Author: jonpryor

Documentation/guides/building-apps/build-items.md

@@ -298,6 +298,37 @@ such as `<AndroidLibrary Include="..." Bind="false" />`:
 </Project>
 ```
 
+## JavaSourceJar
+
+In a Xamarin.Android binding project, the **JavaSourceJar** build action
+is used on `.jar` files which contain *Java source code*, which contains
+[Javadoc documentation comments](https://www.oracle.com/technical-resources/articles/java/javadoc-tool.html).
+
+Prior to Xamarin.Android 11.3, the Javadoc would be converted into HTML
+via the `javadoc` utility during build time, and later turned into
+XML documentation.
+
+Starting with Xamarin.Android 11.3, Javadoc will instead be converted into
+[C# XML Documentation Comments](https://docs.microsoft.com/en-us/dotnet/csharp/codedoc)
+within the generated binding source code.
+
+[`$(AndroidJavadocVerbosity)`](~/android/deploy-test/building-apps/build-properties.md#androidjavadocverbosity)
+controls how "verbose" or "complete" the imported Javadoc is.
+
+Starting in Xamarin.Android 11.3, the following MSBuild metadata is supported:
+
+* `%(CopyrightFile)`: A path to a file that contains copyright
+    information for the Javadoc contents, which will be appended to
+    all imported documentation.
+
+* `%(UrlPrefix)`: A URL prefix to support linking to online
+    documentation within imported documentation.
+
+* `%(UrlStyle)`: The "style" of URLs to generate when linking to
+    online documentation.  Only one style is currently supported:
+    `developer.android.com/reference@2020-Nov`.
+
+
 ## LibraryProjectZip
 
 In a Xamarin.Android binding project, the **LibraryProjectZip** build

Documentation/guides/building-apps/build-properties.md

@@ -633,6 +633,33 @@ APK root directory. The format of the path is `lib\ARCH\wrap.sh` where
 + `x86_64`
 + `x86`
 
+## AndroidJavadocVerbosity
+
+Specifies how "verbose"
+[C# XML Documentation Comments](https://docs.microsoft.com/en-us/dotnet/csharp/codedoc)
+should be when importing Javadoc documentation within binding projects.
+
+Requires use of the
+[`@(JavaSourceJar)`](~/android/deploy-test/building-apps/build-items.md#javasourcejar)
+build action.
+
+This is an enum-style property, with possible values of `full` or
+`intellisense`:
+
+  * `intellisense`: Only emit the XML comments:
+    [`<exception/>](https://docs.microsoft.com/en-us/dotnet/csharp/codedoc#exception),
+    [`<param/>`](https://docs.microsoft.com/en-us/dotnet/csharp/codedoc#param),
+    [`<returns/>`](https://docs.microsoft.com/en-us/dotnet/csharp/codedoc#returns),
+    [`<summary/>`](https://docs.microsoft.com/en-us/dotnet/csharp/codedoc#summary).
+  * `full`: Emit `intellisense` elements, as well as
+    [`<remarks/>`](https://docs.microsoft.com/en-us/dotnet/csharp/codedoc#remarks),
+    [`<seealso/>`](https://docs.microsoft.com/en-us/dotnet/csharp/codedoc#seealso),
+    and anything else that's supportable.
+
+The default value is `intellisense`.
+
+Added in Xamarin.Android 11.3.
+
 ## AndroidKeyStore
 
 A boolean value which indicates whether

Documentation/release-notes/5253.md

@@ -0,0 +1,4 @@
+#### Binding library build
+
+  * [GitHub Issue 4789](https://github.com/xamarin/xamarin-android/issues/4789):
+    Support the `@(JavaSourceJar)` build action on JDK 11 and later.

Xamarin.Android.sln

@@ -142,6 +142,8 @@ Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Xamarin.SourceWriter", "ext
 EndProject
 Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "apksigner", "src\apksigner\apksigner.csproj", "{9A9EF774-6EA6-414F-9D2F-DCD66C56B92A}"
 EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "java-source-utils", "external\Java.Interop\tools\java-source-utils\java-source-utils.csproj", "{37FCD325-1077-4603-98E7-4509CAD648D6}"
+EndProject
 Global
 	GlobalSection(SharedMSBuildProjectFiles) = preSolution
 		src\Xamarin.Android.NamingCustomAttributes\Xamarin.Android.NamingCustomAttributes.projitems*{3f1f2f50-af1a-4a5a-bedb-193372f068d7}*SharedItemsImports = 4
@@ -376,7 +378,7 @@ Global
 		{071D9096-65BB-4359-822E-09788439F210}.Debug|AnyCPU.ActiveCfg = Debug|Any CPU
 		{071D9096-65BB-4359-822E-09788439F210}.Debug|AnyCPU.Build.0 = Debug|Any CPU
 		{071D9096-65BB-4359-822E-09788439F210}.Release|AnyCPU.ActiveCfg = Release|Any CPU
-		{071D9096-65BB-4359-822E-09788439F210}.Release|AnyCPU.Build.0 = Release|Any CPU	EndGlobalSection
+		{071D9096-65BB-4359-822E-09788439F210}.Release|AnyCPU.Build.0 = Release|Any CPU
 		{2CE4CD4B-B7B7-4EAE-A9BE-2699824D6096}.Debug|AnyCPU.ActiveCfg = Debug|Any CPU
 		{2CE4CD4B-B7B7-4EAE-A9BE-2699824D6096}.Debug|AnyCPU.Build.0 = Debug|Any CPU
 		{2CE4CD4B-B7B7-4EAE-A9BE-2699824D6096}.Release|AnyCPU.ActiveCfg = Release|Any CPU
@@ -389,6 +391,10 @@ Global
 		{9A9EF774-6EA6-414F-9D2F-DCD66C56B92A}.Debug|AnyCPU.Build.0 = Debug|Any CPU
 		{9A9EF774-6EA6-414F-9D2F-DCD66C56B92A}.Release|AnyCPU.ActiveCfg = Release|Any CPU
 		{9A9EF774-6EA6-414F-9D2F-DCD66C56B92A}.Release|AnyCPU.Build.0 = Release|Any CPU
+		{37FCD325-1077-4603-98E7-4509CAD648D6}.Debug|AnyCPU.ActiveCfg = Debug|Any CPU
+		{37FCD325-1077-4603-98E7-4509CAD648D6}.Debug|AnyCPU.Build.0 = Debug|Any CPU
+		{37FCD325-1077-4603-98E7-4509CAD648D6}.Release|AnyCPU.ActiveCfg = Release|Any CPU
+		{37FCD325-1077-4603-98E7-4509CAD648D6}.Release|AnyCPU.Build.0 = Release|Any CPU
 	EndGlobalSection
 	GlobalSection(SolutionProperties) = preSolution
 		HideSolutionNode = FALSE
@@ -454,6 +460,7 @@ Global
 		{2CE4CD4B-B7B7-4EAE-A9BE-2699824D6096} = {04E3E11E-B47D-4599-8AFC-50515A95E715}
 		{86A8DEFE-7ABB-4097-9389-C249581E243D} = {04E3E11E-B47D-4599-8AFC-50515A95E715}
 		{9A9EF774-6EA6-414F-9D2F-DCD66C56B92A} = {04E3E11E-B47D-4599-8AFC-50515A95E715}
+		{37FCD325-1077-4603-98E7-4509CAD648D6} = {864062D3-A415-4A6F-9324-5820237BA058}
 	EndGlobalSection
 	GlobalSection(ExtensibilityGlobals) = postSolution
 		SolutionGuid = {53A1F287-EFB2-4D97-A4BB-4A5E145613F6}

build-tools/automation/azure-pipelines.yaml

@@ -67,6 +67,7 @@ variables:
   DotNetNUnitCategories: '& TestCategory != DotNetIgnore & TestCategory != AOT & TestCategory != MkBundle & TestCategory != MonoSymbolicate & TestCategory != PackagesConfig & TestCategory != StaticProject & TestCategory != Debugger'
   NUnit.NumberOfTestWorkers: 4
   GitHub.Token: $(github--pat--vs-mobiletools-engineering-service2)
+  CONVERT_JAVADOC_TO_XMLDOC: $[ne(variables['Build.DefinitionName'], 'Xamarin.Android-PR')]
 
 # Stage and Job "display names" are shortened because they are combined to form the name of the corresponding GitHub check.
 stages:

build-tools/create-packs/Microsoft.Android.Sdk.proj

@@ -76,6 +76,7 @@ core workload sdk packs imported by Microsoft.NET.Workload.Android.
       <_PackageFiles Include="$(ToolsSourceDir)**" PackagePath="tools" />
       <_PackageFiles Include="$(NetCoreAppToolsSourceDir)generator.dll" PackagePath="tools" />
       <_PackageFiles Include="$(NetCoreAppToolsSourceDir)generator.runtimeconfig.json" PackagePath="tools" />
+      <_PackageFiles Include="$(NetCoreAppToolsSourceDir)Java.Interop.Tools.Generator.dll" PackagePath="tools" />
       <_PackageFiles Include="$(NetCoreAppToolsSourceDir)javadoc-to-mdoc.dll" PackagePath="tools" />
       <_PackageFiles Include="$(NetCoreAppToolsSourceDir)javadoc-to-mdoc.runtimeconfig.json" PackagePath="tools" />
       <_PackageFiles Include="$(XAInstallPrefix)xbuild-frameworks\Microsoft.Android\Version*" PackagePath="tools" />

build-tools/installers/create-installers.targets

@@ -132,6 +132,7 @@
     <_MSBuildFiles Include="$(MSBuildSrcDir)\illinkanalyzer.pdb"  ExcludeFromAndroidNETSdk="true" />
     <_MSBuildFiles Include="$(MSBuildSrcDir)\Irony.dll" />
     <_MSBuildFiles Include="$(MSBuildSrcDir)\java-interop.jar" />
+    <_MSBuildFiles Include="$(MSBuildSrcDir)\java-source-utils.jar" />
     <_MSBuildFiles Include="$(MSBuildSrcDir)\javadoc-to-mdoc.exe" ExcludeFromAndroidNETSdk="true" />
     <_MSBuildFiles Include="$(MSBuildSrcDir)\javadoc-to-mdoc.pdb" ExcludeFromAndroidNETSdk="true" />
     <_MSBuildFiles Include="$(MSBuildSrcDir)\Java.Interop.dll" />
@@ -149,6 +150,8 @@
     <_MSBuildFiles Include="$(MSBuildSrcDir)\Java.Interop.Tools.Generator.pdb" />
     <_MSBuildFiles Include="$(MSBuildSrcDir)\Java.Interop.Tools.JavaCallableWrappers.dll" />
     <_MSBuildFiles Include="$(MSBuildSrcDir)\Java.Interop.Tools.JavaCallableWrappers.pdb" />
+    <_MSBuildFiles Include="$(MSBuildSrcDir)\Java.Interop.Tools.JavaSource.dll" />
+    <_MSBuildFiles Include="$(MSBuildSrcDir)\Java.Interop.Tools.JavaSource.pdb" />
     <_MSBuildFiles Include="$(MSBuildSrcDir)\Java.Runtime.Environment.dll" />
     <_MSBuildFiles Include="$(MSBuildSrcDir)\Java.Runtime.Environment.pdb" />
     <_MSBuildFiles Include="$(MSBuildSrcDir)\Java.Runtime.Environment.dll.config" Condition=" '$(HostOS)' != 'Windows' " />

build-tools/xaprepare/xaprepare/ConfigAndData/Dependencies/AndroidToolchain.cs

@@ -62,6 +62,8 @@ public AndroidToolchain ()
 				new AndroidPlatformComponent ("platform-29_r01",   apiLevel: "29", pkgRevision: "1"),
 				new AndroidPlatformComponent ("platform-30_r01",   apiLevel: "30", pkgRevision: "1"),
 
+				new AndroidToolchainComponent ("sources-30_r01",   destDir: Path.Combine ("platforms", $"android-30", "src"), pkgRevision: "1", dependencyType: AndroidToolchainComponentType.BuildDependency),
+
 				new AndroidToolchainComponent ("docs-24_r01",                                       destDir: "docs", pkgRevision: "1", dependencyType: AndroidToolchainComponentType.BuildDependency),
 				new AndroidToolchainComponent ("android_m2repository_r47",                          destDir: Path.Combine ("extras", "android", "m2repository"), pkgRevision: "47.0.0", dependencyType: AndroidToolchainComponentType.BuildDependency),
 				new AndroidToolchainComponent ($"x86_64-29_r07-{osTag}",                            destDir: Path.Combine ("system-images", "android-29", "default", "x86_64"), relativeUrl: new Uri ("sys-img/android/", UriKind.Relative), pkgRevision: "7", dependencyType: AndroidToolchainComponentType.EmulatorDependency),

build-tools/xaprepare/xaprepare/ThirdPartyNotices/Java.Interop.cs

@@ -12,6 +12,7 @@ class JavaInterop_External_Dependencies_Group : ThirdPartyNoticeGroup
 		public override List<ThirdPartyNotice> Notices => new List <ThirdPartyNotice> {
 			new JavaInterop_xamarin_Java_Interop_TPN (),
 			new JavaInterop_gityf_crc_TPN (),
+			new JavaInterop_javaparser_javaparser_TPN (),
 			new JavaInterop_jbevain_mono_linq_expressions_TPN (),
 			new JavaInterop_mono_csharp_TPN (),
 			new JavaInterop_mono_LineEditor_TPN (),
@@ -69,6 +70,18 @@ POSSIBILITY OF SUCH DAMAGE.
 ";
 	}
 
+	// via: https://github.com/xamarin/java.interop/blob/b588ef502d8d3b4c32e0ad731115e1b71fd56b5c/tools/java-source-utils/build.gradle#L33-L34
+	class JavaInterop_javaparser_javaparser_TPN : ThirdPartyNotice
+	{
+		static readonly Uri    url         = new Uri ("https://github.com/javaparser/javaparser/");
+		static readonly string licenseFile = Path.Combine (Configurables.Paths.ExternalJavaInteropDir, "LICENSE");
+
+		public override string LicenseFile => CommonLicenses.Apache20Path;
+		public override string Name        => "javaparser/javaparser";
+		public override Uri    SourceUrl   => url;
+		public override string LicenseText => String.Empty;
+	}
+
 	// git submodules of Java.Interop
 	class JavaInterop_jbevain_mono_linq_expressions_TPN : ThirdPartyNotice
 	{

external/Java.Interop

@@ -23,6 +23,16 @@
     <ProduceReferenceAssembly>true</ProduceReferenceAssembly>
   </PropertyGroup>
 
+  <PropertyGroup>
+    <IncludeAndroidJavadoc Condition=" '$(IncludeAndroidJavadoc)' == '' And '$(CONVERT_JAVADOC_TO_XMLDOC)' == 'true' And '$(AndroidFrameworkVersion)' == '$(AndroidLatestStableFrameworkVersion)'">True</IncludeAndroidJavadoc>
+    <AndroidJavadocVerbosity Condition=" '$(AndroidJavadocVerbosity)' == '' ">intellisense</AndroidJavadocVerbosity>
+  </PropertyGroup>
+
+  <PropertyGroup Condition=" '$(IncludeAndroidJavadoc)' == 'True' ">
+    <DocumentationFile>$(OutputPath)Mono.Android.xml</DocumentationFile>
+    <NoWarn>$(NoWarn);CS1572;CS1573;CS1574;CS1587;CS1591;</NoWarn>
+  </PropertyGroup>
+
   <PropertyGroup Condition=" '$(TargetFramework)' == 'monoandroid10' ">
     <TargetFrameworkIdentifier>MonoAndroid</TargetFrameworkIdentifier>
     <TargetFrameworkVersion>v1.0</TargetFrameworkVersion>
@@ -349,6 +359,7 @@
     <ProjectReference Include="..\..\build-tools\api-merge\api-merge.csproj" ReferenceOutputAssembly="false" SkipGetTargetFrameworkProperties="true" AdditionalProperties="TargetFramework=net472" />
     <ProjectReference Include="..\..\build-tools\jnienv-gen\jnienv-gen.csproj" ReferenceOutputAssembly="false" SkipGetTargetFrameworkProperties="true" AdditionalProperties="TargetFramework=net472" />
     <ProjectReference Include="..\..\external\Java.Interop\tools\generator\generator.csproj" ReferenceOutputAssembly="false" SkipGetTargetFrameworkProperties="true" AdditionalProperties="TargetFramework=net472"/>
+    <ProjectReference Include="..\..\external\Java.Interop\tools\java-source-utils\java-source-utils.csproj" ReferenceOutputAssembly="false" SkipGetTargetFrameworkProperties="true" AdditionalProperties="TargetFramework=net472" />
     <ProjectReference Include="..\..\external\Java.Interop\tools\jcw-gen\jcw-gen.csproj" ReferenceOutputAssembly="false" SkipGetTargetFrameworkProperties="true" AdditionalProperties="TargetFramework=net472" />
     <ProjectReference Include="..\..\src\java-runtime\java-runtime.csproj" ReferenceOutputAssembly="false" />
     <ProjectReference Include="..\r8\r8.csproj" ReferenceOutputAssembly="False" />

src/Mono.Android/Mono.Android.csproj

@@ -53,6 +53,50 @@
         Replacements="@PACKAGE_VERSION@=$(_PackageVersion);@PACKAGE_VERSION_BUILD@=$(_PackageVersionBuild);@PACKAGE_HEAD_REV@=$(XAVersionHash);@PACKAGE_HEAD_BRANCH@=$(XAVersionBranch)">
     </ReplaceFileContents>
   </Target>
+  <PropertyGroup>
+    <_JavaSourceUtilsJar>$(XAInstallPrefix)xbuild\Xamarin\Android\java-source-utils.jar</_JavaSourceUtilsJar>
+    <_AndroidStableSrcDir>$(AndroidSdkDirectory)\platforms\android-$(AndroidLatestStableApiLevel)\src</_AndroidStableSrcDir>
+    <_AndroidJavadocXml>..\..\bin\Build$(Configuration)\android-javadoc.xml</_AndroidJavadocXml>
+  </PropertyGroup>
+  <Target Name="_BuildAndroidJavadocXml"
+      Condition=" '$(IncludeAndroidJavadoc)' == 'True' "
+      BeforeTargets="CoreCompile"
+      Inputs="$(MSBuildThisFile);$(_AndroidStableSrcDir)\source.properties;$(_JavaSourceUtilsJar)"
+      Outputs="$(_AndroidJavadocXml)">
+    <ItemGroup>
+      <_Doclink Include="--doc-copyright" />
+      <_Doclink Include="$(MSBuildThisFileDirectory)javadoc-copyright.xml" />
+      <_Doclink Include="--doc-url-prefix" />
+      <_Doclink Include="https://developer.android.com/reference" />
+      <_Doclink Include="--doc-url-style" />
+      <_Doclink Include="developer.android.com/reference@2020-Nov" />
+    </ItemGroup>
+    <ItemGroup>
+      <_AndroidSources Include="$(_AndroidStableSrcDir)\android\**\*.java" />
+      <_AndroidSources Include="$(_AndroidStableSrcDir)\java\**\*.java" />
+      <_AndroidSources Include="$(_AndroidStableSrcDir)\javax\**\*.java" />
+      <_AndroidSources Include="$(_AndroidStableSrcDir)\org\**\*.java" />
+      <_AndroidSources Remove="$(_AndroidStableSrcDir)\**\*.annotated.java" />
+    </ItemGroup>
+    <PropertyGroup>
+      <_Filenames>$(IntermediateOutputPath)\java-sources.txt</_Filenames>
+    </PropertyGroup>
+    <WriteLinesToFile
+       File="$(_Filenames)"
+       Lines="@(_Doclink);@(_AndroidSources)"
+       Overwrite="True"
+    />
+    <ItemGroup>
+      <_JSIArg Include="-v" />
+      <_JSIArg Include="--source &quot;$(_AndroidStableSrcDir)&quot;" />
+      <_JSIArg Include="--output-javadoc &quot;$(_AndroidJavadocXml)&quot;" />
+      <_JSIArg Include="@$(_Filenames)" />
+    </ItemGroup>
+    <Exec
+        Command="&quot;$(JavaPath)&quot; -jar &quot;$(_JavaSourceUtilsJar)&quot; @(_JSIArg, ' ')"
+    />
+    <Touch Files="$(_AndroidJavadocXml)" />
+  </Target>
   <Target Name="_BuildJNIEnv"
       BeforeTargets="CoreCompile"
       Inputs="..\..\bin\Build$(Configuration)\jnienv-gen.exe"
@@ -113,12 +157,14 @@
       <_TypeMap>--type-map-report=$(IntermediateOutputPath)mcw\type-mapping.txt</_TypeMap>
       <_Api>$(IntermediateOutputPath)mcw\api.xml</_Api>
       <_Dirs>--enumdir=$(IntermediateOutputPath)mcw</_Dirs>
+      <_WithJavadocXml Condition=" '$(IncludeAndroidJavadoc)' == 'True' ">--doc-comment-verbosity=$(AndroidJavadocVerbosity) "--with-javadoc-xml=$(_AndroidJavadocXml)"</_WithJavadocXml>
       <_FullIntermediateOutputPath>$([System.IO.Path]::GetFullPath('$(IntermediateOutputPath)'))</_FullIntermediateOutputPath>
       <_LangFeatures>--lang-features=nullable-reference-types</_LangFeatures>
       <_LangFeatures Condition="$(AndroidApiLevel) &gt;= 30">$(_LangFeatures),default-interface-methods,nested-interface-types,interface-constants</_LangFeatures>
     </PropertyGroup>
     <Exec
-        Command="$(ManagedRuntime) $(ManagedRuntimeArgs) $(Generator) $(_GenFlags) $(_ApiLevel) $(_Out) $(_Codegen) $(_Fixup) $(_Enums1) $(_Enums2) $(_Versions) $(_Annotations) $(_Assembly) $(_TypeMap) $(_LangFeatures) $(_Dirs) $(_Api)"
+        Command="$(ManagedRuntime) $(ManagedRuntimeArgs) $(Generator) $(_GenFlags) $(_ApiLevel) $(_Out) $(_Codegen) $(_Fixup) $(_Enums1) $(_Enums2) $(_Versions) $(_Annotations) $(_Assembly) $(_TypeMap) $(_LangFeatures) $(_Dirs) $(_Api) $(_WithJavadocXml)"
+        IgnoreStandardErrorWarningFormat="True"
     />
     <ItemGroup>
       <Compile Include="$(_FullIntermediateOutputPath)\mcw\**\*.cs" KeepDuplicates="False" />

src/Mono.Android/Mono.Android.targets

@@ -0,0 +1,5 @@
+<para>Portions of this page are modifications based on work created and shared by the <format type="text/html">
+<a href="https://developers.google.com/terms/site-policies" title="Android Open Source Project">Android Open Source Project</a>
+</format> and used according to terms described in the <format type="text/html">
+<a href="https://creativecommons.org/licenses/by/2.5/" title="Creative Commons 2.5 Attribution License">Creative Commons 2.5 Attribution License.</a></format>
+</para>

src/Mono.Android/javadoc-copyright.xml

@@ -14,9 +14,14 @@ This file is only used by binding projects.
   <UsingTask TaskName="Xamarin.Android.Tasks.ClassParse" AssemblyFile="Xamarin.Android.Build.Tasks.dll" />
 
   <Target Name="_ExportJarToXml"
+      DependsOnTargets="_ExtractJavadocsFromJavaSourceJars"
       Inputs="@(EmbeddedJar);@(EmbeddedReferenceJar);@(InputJar);@(ReferenceJar);@(_AndroidMSBuildAllProjects)"
       Outputs="$(ApiOutputFile)">
+
     <ItemGroup>
+      <!-- TODO: add when `ClassPath` supports `<api api-source="java-source-utils">`
+      <_AndroidDocumentationPath Include="@(_JavaSourceJavadocXml)" />
+        -->
       <_AndroidDocumentationPath Include="@(JavaDocIndex->'%(RootDir)\%(Directory)')" />
       <_AndroidDocumentationPath Include="$(JavaDocPaths)" />
       <_AndroidDocumentationPath Include="$(Java7DocPaths)" />
@@ -43,4 +48,39 @@ This file is only used by binding projects.
     />
   </Target>
 
+  <Target Name="_GetJavaSourceJarJavadocFiles"
+      Condition=" '$(_UseLegacyJavadocImport)' != 'True' And '@(JavaSourceJar->Count())' != '0' ">
+    <ComputeHash
+        CopyMetadata="True"
+        Source="@(JavaSourceJar)">
+      <Output TaskParameter="Output" ItemName="_JavaSourceJarHashes" />
+    </ComputeHash>
+    <ItemGroup>
+      <_JavaSourceJavadocXml Include="@(_JavaSourceJarHashes->'$(IntermediateOutputPath)javadoc-%(Filename)-%(Hash).xml')" />
+    </ItemGroup>
+  </Target>
+
+  <Target Name="_ExtractJavadocsFromJavaSourceJars"
+      Condition=" '$(_UseLegacyJavadocImport)' != 'True' And '@(JavaSourceJar->Count())' != '0' "
+      DependsOnTargets="_GetJavaSourceJarJavadocFiles"
+      Inputs="@(JavaSourceJar)"
+      Outputs="@(_JavaSourceJavadocXml)">
+    <JavaSourceUtils
+        ContinueOnError="True"
+        JavaSourceUtilsJar="$(AndroidJavaSourceUtilsJar)"
+        InputFiles="%(_JavaSourceJavadocXml.OriginalItemSpec)"
+        JavadocCopyrightFile="%(_JavaSourceJavadocXml.CopyrightFile)"
+        JavadocUrlPrefix="%(_JavaSourceJavadocXml.UrlPrefix)"
+        JavadocUrlStyle="%(_JavaSourceJavadocXml.UrlStyle)"
+        JavaMaximumHeapSize="$(JavaMaximumHeapSize)"
+        JavaOptions="$(JavaOptions)"
+        JavaSdkDirectory="$(_JavaSdkDirectory)"
+        OutputJavadocXml="%(_JavaSourceJavadocXml.Identity)"
+        References="@(JavaSourceJar)"
+    />
+    <ItemGroup>
+      <FileWrites Include="@(_JavaSourceJavadocXml)" />
+    </ItemGroup>
+  </Target>
+
 </Project>