Skip to content

Commit a7413a2

Browse files
jonpryorjonpryor
authored
[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)
1 parent 2e92452 commit a7413a2

File tree

26 files changed

+435
-41
lines changed

26 files changed

+435
-41
lines changed

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

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -298,6 +298,37 @@ such as `<AndroidLibrary Include="..." Bind="false" />`:
298298
</Project>
299299
```
300300

301+
## JavaSourceJar
302+
303+
In a Xamarin.Android binding project, the **JavaSourceJar** build action
304+
is used on `.jar` files which contain *Java source code*, which contains
305+
[Javadoc documentation comments](https://www.oracle.com/technical-resources/articles/java/javadoc-tool.html).
306+
307+
Prior to Xamarin.Android 11.3, the Javadoc would be converted into HTML
308+
via the `javadoc` utility during build time, and later turned into
309+
XML documentation.
310+
311+
Starting with Xamarin.Android 11.3, Javadoc will instead be converted into
312+
[C# XML Documentation Comments](https://docs.microsoft.com/en-us/dotnet/csharp/codedoc)
313+
within the generated binding source code.
314+
315+
[`$(AndroidJavadocVerbosity)`](~/android/deploy-test/building-apps/build-properties.md#androidjavadocverbosity)
316+
controls how "verbose" or "complete" the imported Javadoc is.
317+
318+
Starting in Xamarin.Android 11.3, the following MSBuild metadata is supported:
319+
320+
* `%(CopyrightFile)`: A path to a file that contains copyright
321+
information for the Javadoc contents, which will be appended to
322+
all imported documentation.
323+
324+
* `%(UrlPrefix)`: A URL prefix to support linking to online
325+
documentation within imported documentation.
326+
327+
* `%(UrlStyle)`: The "style" of URLs to generate when linking to
328+
online documentation. Only one style is currently supported:
329+
`developer.android.com/reference@2020-Nov`.
330+
331+
301332
## LibraryProjectZip
302333

303334
In a Xamarin.Android binding project, the **LibraryProjectZip** build

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

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -633,6 +633,33 @@ APK root directory. The format of the path is `lib\ARCH\wrap.sh` where
633633
+ `x86_64`
634634
+ `x86`
635635

636+
## AndroidJavadocVerbosity
637+
638+
Specifies how "verbose"
639+
[C# XML Documentation Comments](https://docs.microsoft.com/en-us/dotnet/csharp/codedoc)
640+
should be when importing Javadoc documentation within binding projects.
641+
642+
Requires use of the
643+
[`@(JavaSourceJar)`](~/android/deploy-test/building-apps/build-items.md#javasourcejar)
644+
build action.
645+
646+
This is an enum-style property, with possible values of `full` or
647+
`intellisense`:
648+
649+
* `intellisense`: Only emit the XML comments:
650+
[`<exception/>](https://docs.microsoft.com/en-us/dotnet/csharp/codedoc#exception),
651+
[`<param/>`](https://docs.microsoft.com/en-us/dotnet/csharp/codedoc#param),
652+
[`<returns/>`](https://docs.microsoft.com/en-us/dotnet/csharp/codedoc#returns),
653+
[`<summary/>`](https://docs.microsoft.com/en-us/dotnet/csharp/codedoc#summary).
654+
* `full`: Emit `intellisense` elements, as well as
655+
[`<remarks/>`](https://docs.microsoft.com/en-us/dotnet/csharp/codedoc#remarks),
656+
[`<seealso/>`](https://docs.microsoft.com/en-us/dotnet/csharp/codedoc#seealso),
657+
and anything else that's supportable.
658+
659+
The default value is `intellisense`.
660+
661+
Added in Xamarin.Android 11.3.
662+
636663
## AndroidKeyStore
637664

638665
A boolean value which indicates whether

‎Documentation/release-notes/5253.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
#### Binding library build
2+
3+
* [GitHub Issue 4789](https://github.com/xamarin/xamarin-android/issues/4789):
4+
Support the `@(JavaSourceJar)` build action on JDK 11 and later.

‎Xamarin.Android.sln‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -142,6 +142,8 @@ Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Xamarin.SourceWriter", "ext
142142
EndProject
143143
Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "apksigner", "src\apksigner\apksigner.csproj", "{9A9EF774-6EA6-414F-9D2F-DCD66C56B92A}"
144144
EndProject
145+
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}"
146+
EndProject
145147
Global
146148
GlobalSection(SharedMSBuildProjectFiles) = preSolution
147149
src\Xamarin.Android.NamingCustomAttributes\Xamarin.Android.NamingCustomAttributes.projitems*{3f1f2f50-af1a-4a5a-bedb-193372f068d7}*SharedItemsImports = 4
@@ -376,7 +378,7 @@ Global
376378
{071D9096-65BB-4359-822E-09788439F210}.Debug|AnyCPU.ActiveCfg = Debug|Any CPU
377379
{071D9096-65BB-4359-822E-09788439F210}.Debug|AnyCPU.Build.0 = Debug|Any CPU
378380
{071D9096-65BB-4359-822E-09788439F210}.Release|AnyCPU.ActiveCfg = Release|Any CPU
379-
{071D9096-65BB-4359-822E-09788439F210}.Release|AnyCPU.Build.0 = Release|Any CPU EndGlobalSection
381+
{071D9096-65BB-4359-822E-09788439F210}.Release|AnyCPU.Build.0 = Release|Any CPU
380382
{2CE4CD4B-B7B7-4EAE-A9BE-2699824D6096}.Debug|AnyCPU.ActiveCfg = Debug|Any CPU
381383
{2CE4CD4B-B7B7-4EAE-A9BE-2699824D6096}.Debug|AnyCPU.Build.0 = Debug|Any CPU
382384
{2CE4CD4B-B7B7-4EAE-A9BE-2699824D6096}.Release|AnyCPU.ActiveCfg = Release|Any CPU
@@ -389,6 +391,10 @@ Global
389391
{9A9EF774-6EA6-414F-9D2F-DCD66C56B92A}.Debug|AnyCPU.Build.0 = Debug|Any CPU
390392
{9A9EF774-6EA6-414F-9D2F-DCD66C56B92A}.Release|AnyCPU.ActiveCfg = Release|Any CPU
391393
{9A9EF774-6EA6-414F-9D2F-DCD66C56B92A}.Release|AnyCPU.Build.0 = Release|Any CPU
394+
{37FCD325-1077-4603-98E7-4509CAD648D6}.Debug|AnyCPU.ActiveCfg = Debug|Any CPU
395+
{37FCD325-1077-4603-98E7-4509CAD648D6}.Debug|AnyCPU.Build.0 = Debug|Any CPU
396+
{37FCD325-1077-4603-98E7-4509CAD648D6}.Release|AnyCPU.ActiveCfg = Release|Any CPU
397+
{37FCD325-1077-4603-98E7-4509CAD648D6}.Release|AnyCPU.Build.0 = Release|Any CPU
392398
EndGlobalSection
393399
GlobalSection(SolutionProperties) = preSolution
394400
HideSolutionNode = FALSE
@@ -454,6 +460,7 @@ Global
454460
{2CE4CD4B-B7B7-4EAE-A9BE-2699824D6096} = {04E3E11E-B47D-4599-8AFC-50515A95E715}
455461
{86A8DEFE-7ABB-4097-9389-C249581E243D} = {04E3E11E-B47D-4599-8AFC-50515A95E715}
456462
{9A9EF774-6EA6-414F-9D2F-DCD66C56B92A} = {04E3E11E-B47D-4599-8AFC-50515A95E715}
463+
{37FCD325-1077-4603-98E7-4509CAD648D6} = {864062D3-A415-4A6F-9324-5820237BA058}
457464
EndGlobalSection
458465
GlobalSection(ExtensibilityGlobals) = postSolution
459466
SolutionGuid = {53A1F287-EFB2-4D97-A4BB-4A5E145613F6}

‎build-tools/automation/azure-pipelines.yaml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -67,6 +67,7 @@ variables:
6767
DotNetNUnitCategories: '& TestCategory != DotNetIgnore & TestCategory != AOT & TestCategory != MkBundle & TestCategory != MonoSymbolicate & TestCategory != PackagesConfig & TestCategory != StaticProject & TestCategory != Debugger'
6868
NUnit.NumberOfTestWorkers: 4
6969
GitHub.Token: $(github--pat--vs-mobiletools-engineering-service2)
70+
CONVERT_JAVADOC_TO_XMLDOC: $[ne(variables['Build.DefinitionName'], 'Xamarin.Android-PR')]
7071

7172
# Stage and Job "display names" are shortened because they are combined to form the name of the corresponding GitHub check.
7273
stages:

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

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -76,6 +76,7 @@ core workload sdk packs imported by Microsoft.NET.Workload.Android.
7676
<_PackageFiles Include="$(ToolsSourceDir)**" PackagePath="tools" />
7777
<_PackageFiles Include="$(NetCoreAppToolsSourceDir)generator.dll" PackagePath="tools" />
7878
<_PackageFiles Include="$(NetCoreAppToolsSourceDir)generator.runtimeconfig.json" PackagePath="tools" />
79+
<_PackageFiles Include="$(NetCoreAppToolsSourceDir)Java.Interop.Tools.Generator.dll" PackagePath="tools" />
7980
<_PackageFiles Include="$(NetCoreAppToolsSourceDir)javadoc-to-mdoc.dll" PackagePath="tools" />
8081
<_PackageFiles Include="$(NetCoreAppToolsSourceDir)javadoc-to-mdoc.runtimeconfig.json" PackagePath="tools" />
8182
<_PackageFiles Include="$(XAInstallPrefix)xbuild-frameworks\Microsoft.Android\Version*" PackagePath="tools" />

‎build-tools/installers/create-installers.targets‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -132,6 +132,7 @@
132132
<_MSBuildFiles Include="$(MSBuildSrcDir)\illinkanalyzer.pdb" ExcludeFromAndroidNETSdk="true" />
133133
<_MSBuildFiles Include="$(MSBuildSrcDir)\Irony.dll" />
134134
<_MSBuildFiles Include="$(MSBuildSrcDir)\java-interop.jar" />
135+
<_MSBuildFiles Include="$(MSBuildSrcDir)\java-source-utils.jar" />
135136
<_MSBuildFiles Include="$(MSBuildSrcDir)\javadoc-to-mdoc.exe" ExcludeFromAndroidNETSdk="true" />
136137
<_MSBuildFiles Include="$(MSBuildSrcDir)\javadoc-to-mdoc.pdb" ExcludeFromAndroidNETSdk="true" />
137138
<_MSBuildFiles Include="$(MSBuildSrcDir)\Java.Interop.dll" />
@@ -149,6 +150,8 @@
149150
<_MSBuildFiles Include="$(MSBuildSrcDir)\Java.Interop.Tools.Generator.pdb" />
150151
<_MSBuildFiles Include="$(MSBuildSrcDir)\Java.Interop.Tools.JavaCallableWrappers.dll" />
151152
<_MSBuildFiles Include="$(MSBuildSrcDir)\Java.Interop.Tools.JavaCallableWrappers.pdb" />
153+
<_MSBuildFiles Include="$(MSBuildSrcDir)\Java.Interop.Tools.JavaSource.dll" />
154+
<_MSBuildFiles Include="$(MSBuildSrcDir)\Java.Interop.Tools.JavaSource.pdb" />
152155
<_MSBuildFiles Include="$(MSBuildSrcDir)\Java.Runtime.Environment.dll" />
153156
<_MSBuildFiles Include="$(MSBuildSrcDir)\Java.Runtime.Environment.pdb" />
154157
<_MSBuildFiles Include="$(MSBuildSrcDir)\Java.Runtime.Environment.dll.config" Condition=" '$(HostOS)' != 'Windows' " />

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

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -62,6 +62,8 @@ public AndroidToolchain ()
6262
new AndroidPlatformComponent ("platform-29_r01", apiLevel: "29", pkgRevision: "1"),
6363
new AndroidPlatformComponent ("platform-30_r01", apiLevel: "30", pkgRevision: "1"),
6464

65+
new AndroidToolchainComponent ("sources-30_r01", destDir: Path.Combine ("platforms", $"android-30", "src"), pkgRevision: "1", dependencyType: AndroidToolchainComponentType.BuildDependency),
66+
6567
new AndroidToolchainComponent ("docs-24_r01", destDir: "docs", pkgRevision: "1", dependencyType: AndroidToolchainComponentType.BuildDependency),
6668
new AndroidToolchainComponent ("android_m2repository_r47", destDir: Path.Combine ("extras", "android", "m2repository"), pkgRevision: "47.0.0", dependencyType: AndroidToolchainComponentType.BuildDependency),
6769
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‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,7 @@ class JavaInterop_External_Dependencies_Group : ThirdPartyNoticeGroup
1212
public override List<ThirdPartyNotice> Notices => new List <ThirdPartyNotice> {
1313
new JavaInterop_xamarin_Java_Interop_TPN (),
1414
new JavaInterop_gityf_crc_TPN (),
15+
new JavaInterop_javaparser_javaparser_TPN (),
1516
new JavaInterop_jbevain_mono_linq_expressions_TPN (),
1617
new JavaInterop_mono_csharp_TPN (),
1718
new JavaInterop_mono_LineEditor_TPN (),
@@ -69,6 +70,18 @@ POSSIBILITY OF SUCH DAMAGE.
6970
";
7071
}
7172

73+
// via: https://github.com/xamarin/java.interop/blob/b588ef502d8d3b4c32e0ad731115e1b71fd56b5c/tools/java-source-utils/build.gradle#L33-L34
74+
class JavaInterop_javaparser_javaparser_TPN : ThirdPartyNotice
75+
{
76+
static readonly Uri url = new Uri ("https://github.com/javaparser/javaparser/");
77+
static readonly string licenseFile = Path.Combine (Configurables.Paths.ExternalJavaInteropDir, "LICENSE");
78+
79+
public override string LicenseFile => CommonLicenses.Apache20Path;
80+
public override string Name => "javaparser/javaparser";
81+
public override Uri SourceUrl => url;
82+
public override string LicenseText => String.Empty;
83+
}
84+
7285
// git submodules of Java.Interop
7386
class JavaInterop_jbevain_mono_linq_expressions_TPN : ThirdPartyNotice
7487
{

‎external/Java.Interop‎

0 commit comments

Comments
 (0)