Skip to content

Commit d649ce8

Browse files
jonpryorjonpryor
committed
[Mono.Android] Generate Mono.Android.xml
Context: dotnet/java-interop#687 Context: #5200 What do we want? Updated documentation! 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 are woefully out of date. 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 a `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 extract 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 `anddroid-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. [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 f1a6e22 commit d649ce8

File tree

9 files changed

+99
-6
lines changed

9 files changed

+99
-6
lines changed

‎.gitmodules

+2-2
Original file line numberDiff line numberDiff line change
@@ -12,8 +12,8 @@
1212
branch = master
1313
[submodule "external/Java.Interop"]
1414
path = external/Java.Interop
15-
url = https://github.com/xamarin/java.interop.git
16-
branch = master
15+
url = https://github.com/jonpryor/java.interop.git
16+
branch = jonp-generator-javadoc-xml
1717
[submodule "external/lz4"]
1818
path = external/lz4
1919
url = https://github.com/lz4/lz4.git

‎Xamarin.Android.sln

+8-1
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/installers/create-installers.targets

+3
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" ExcludeFromAndroidNETSdk="true" />
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

+2
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

+13
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

Submodule Java.Interop updated 36 files

‎src/Mono.Android/Mono.Android.csproj

+12-1
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,16 @@
2424
<ProduceReferenceAssembly>true</ProduceReferenceAssembly>
2525
</PropertyGroup>
2626

27+
<PropertyGroup>
28+
<!-- TODO: Default to False? Depends on impact on build times -->
29+
<IncludeAndroidJavadoc Condition=" '$(IncludeAndroidJavadoc)' == '' ">True</IncludeAndroidJavadoc>
30+
</PropertyGroup>
31+
32+
<PropertyGroup Condition=" '$(IncludeAndroidJavadoc)' == 'True' ">
33+
<DocumentationFile>$(OutputPath)Mono.Android.xml</DocumentationFile>
34+
<NoWarn>CS1573;CS1591</NoWarn>
35+
</PropertyGroup>
36+
2737
<PropertyGroup Condition=" '$(TargetFramework)' == 'monoandroid10' ">
2838
<TargetFrameworkIdentifier>MonoAndroid</TargetFrameworkIdentifier>
2939
<TargetFrameworkVersion>v1.0</TargetFrameworkVersion>
@@ -344,7 +354,8 @@
344354
<!-- Explicitly pass the target framework of the project so we don't have conflicts with the multiple targets in this file. -->
345355
<ProjectReference Include="..\..\build-tools\api-merge\api-merge.csproj" ReferenceOutputAssembly="false" SkipGetTargetFrameworkProperties="true" AdditionalProperties="TargetFramework=net472" />
346356
<ProjectReference Include="..\..\build-tools\jnienv-gen\jnienv-gen.csproj" ReferenceOutputAssembly="false" SkipGetTargetFrameworkProperties="true" AdditionalProperties="TargetFramework=net472" />
347-
<ProjectReference Include="..\..\external\Java.Interop\tools\generator\generator.csproj" ReferenceOutputAssembly="false" SkipGetTargetFrameworkProperties="true" AdditionalProperties="TargetFramework=net472"/>
357+
<ProjectReference Include="..\..\external\Java.Interop\tools\generator\generator.csproj" ReferenceOutputAssembly="false" SkipGetTargetFrameworkProperties="true" AdditionalProperties="TargetFramework=net472" />
358+
<ProjectReference Include="..\..\external\Java.Interop\tools\java-source-utils\java-source-utils.csproj" ReferenceOutputAssembly="false" SkipGetTargetFrameworkProperties="true" AdditionalProperties="TargetFramework=net472" />
348359
<ProjectReference Include="..\..\external\Java.Interop\tools\jcw-gen\jcw-gen.csproj" ReferenceOutputAssembly="false" SkipGetTargetFrameworkProperties="true" AdditionalProperties="TargetFramework=net472" />
349360
<ProjectReference Include="..\..\src\java-runtime\java-runtime.csproj" ReferenceOutputAssembly="false" />
350361
<ProjectReference Include="..\r8\r8.csproj" ReferenceOutputAssembly="False" />

‎src/Mono.Android/Mono.Android.targets

+47-1
Original file line numberDiff line numberDiff line change
@@ -53,6 +53,50 @@
5353
Replacements="@PACKAGE_VERSION@=$(_PackageVersion);@PACKAGE_VERSION_BUILD@=$(_PackageVersionBuild);@PACKAGE_HEAD_REV@=$(XAVersionHash);@PACKAGE_HEAD_BRANCH@=$(XAVersionBranch)">
5454
</ReplaceFileContents>
5555
</Target>
56+
<PropertyGroup>
57+
<_JavaSourceUtilsJar>$(XAInstallPrefix)xbuild\Xamarin\Android\java-source-utils.jar</_JavaSourceUtilsJar>
58+
<_AndroidStableSrcDir>$(AndroidSdkDirectory)\platforms\android-$(AndroidLatestStableApiLevel)\src</_AndroidStableSrcDir>
59+
<_AndroidJavadocXml>..\..\bin\Build$(Configuration)\android-javadoc.xml</_AndroidJavadocXml>
60+
</PropertyGroup>
61+
<Target Name="_BuildAndroidJavadocXml"
62+
Condition=" '$(IncludeAndroidJavadoc)' == 'True' "
63+
BeforeTargets="CoreCompile"
64+
Inputs="$(MSBuildThisFile);$(_AndroidStableSrcDir)\source.properties;$(_JavaSourceUtilsJar)"
65+
Outputs="$(_AndroidJavadocXml)">
66+
<ItemGroup>
67+
<_Doclink Include="--doc-copyright" />
68+
<_Doclink Include="$(MSBuildThisFileDirectory)javadoc-copyright.xml" />
69+
<_Doclink Include="--doc-url-prefix" />
70+
<_Doclink Include="https://developer.android.com/reference" />
71+
<_Doclink Include="--doc-url-style" />
72+
<_Doclink Include="developer.android.com/reference@2020-Nov" />
73+
</ItemGroup>
74+
<ItemGroup>
75+
<_AndroidSources Include="$(_AndroidStableSrcDir)\android\**\*.java" />
76+
<_AndroidSources Include="$(_AndroidStableSrcDir)\java\**\*.java" />
77+
<_AndroidSources Include="$(_AndroidStableSrcDir)\javax\**\*.java" />
78+
<_AndroidSources Include="$(_AndroidStableSrcDir)\org\**\*.java" />
79+
<_AndroidSources Remove="$(_AndroidStableSrcDir)\**\*.annotated.java" />
80+
</ItemGroup>
81+
<PropertyGroup>
82+
<_Filenames>$(IntermediateOutputPath)\java-sources.txt</_Filenames>
83+
</PropertyGroup>
84+
<WriteLinesToFile
85+
File="$(_Filenames)"
86+
Lines="@(_Doclink);@(_AndroidSources)"
87+
Overwrite="True"
88+
/>
89+
<ItemGroup>
90+
<_JSIArg Include="-v" />
91+
<_JSIArg Include="--source &quot;$(_AndroidStableSrcDir)&quot;" />
92+
<_JSIArg Include="--output-javadoc &quot;$(_AndroidJavadocXml)&quot;" />
93+
<_JSIArg Include="@$(_Filenames)" />
94+
</ItemGroup>
95+
<Exec
96+
Command="&quot;$(JavaPath)&quot; -jar &quot;$(_JavaSourceUtilsJar)&quot; @(_JSIArg, ' ')"
97+
/>
98+
<Touch Files="$(_AndroidJavadocXml)" />
99+
</Target>
56100
<Target Name="_BuildJNIEnv"
57101
BeforeTargets="CoreCompile"
58102
Inputs="..\..\bin\Build$(Configuration)\jnienv-gen.exe"
@@ -113,12 +157,14 @@
113157
<_TypeMap>--type-map-report=$(IntermediateOutputPath)mcw\type-mapping.txt</_TypeMap>
114158
<_Api>$(IntermediateOutputPath)mcw\api.xml</_Api>
115159
<_Dirs>--enumdir=$(IntermediateOutputPath)mcw</_Dirs>
160+
<_WithJavadocXml Condition=" '$(IncludeAndroidJavadoc)' == 'True' ">"--with-javadoc-xml=$(_AndroidJavadocXml)"</_WithJavadocXml>
116161
<_FullIntermediateOutputPath>$([System.IO.Path]::GetFullPath('$(IntermediateOutputPath)'))</_FullIntermediateOutputPath>
117162
<_LangFeatures>--lang-features=nullable-reference-types</_LangFeatures>
118163
<_LangFeatures Condition="$(AndroidApiLevel) &gt;= 30">$(_LangFeatures),default-interface-methods,nested-interface-types,interface-constants</_LangFeatures>
119164
</PropertyGroup>
120165
<Exec
121-
Command="$(ManagedRuntime) $(ManagedRuntimeArgs) $(Generator) $(_GenFlags) $(_ApiLevel) $(_Out) $(_Codegen) $(_Fixup) $(_Enums1) $(_Enums2) $(_Versions) $(_Annotations) $(_Assembly) $(_TypeMap) $(_LangFeatures) $(_Dirs) $(_Api)"
166+
Command="$(ManagedRuntime) $(ManagedRuntimeArgs) $(Generator) $(_GenFlags) $(_ApiLevel) $(_Out) $(_Codegen) $(_Fixup) $(_Enums1) $(_Enums2) $(_Versions) $(_Annotations) $(_Assembly) $(_TypeMap) $(_LangFeatures) $(_Dirs) $(_Api) $(_WithJavadocXml)"
167+
IgnoreStandardErrorWarningFormat="True"
122168
/>
123169
<ItemGroup>
124170
<Compile Include="$(_FullIntermediateOutputPath)\mcw\**\*.cs" KeepDuplicates="False" />

‎src/Mono.Android/javadoc-copyright.xml

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

0 commit comments

Comments
 (0)