Skip to content

[Mono.Android] Generate API docs for .NET Android #8007

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jonpryor merged 2 commits into from
May 10, 2023
Merged

[Mono.Android] Generate API docs for .NET Android #8007

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
7d95f36
[Mono.Android] Generate API docs for .NET Android
pjcollins May 2, 2023
a3367b4
Feedback
pjcollins May 9, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion build-tools/create-packs/Microsoft.Android.Ref.proj
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@ by projects that use the Microsoft.Android framework in .NET 6+.
</PropertyGroup>

<Target Name="_GetTargetingPackItems"
DependsOnTargets="AssembleApiDocs;_GetLicense">
DependsOnTargets="_GetLicense">
<PropertyGroup>
<FrameworkListFile Condition="'$(FrameworkListFile)' == ''">$(IntermediateOutputPath)FrameworkList.xml</FrameworkListFile>
</PropertyGroup>
Expand Down
67 changes: 1 addition & 66 deletions build-tools/installers/create-installers.targets
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,8 +7,6 @@
<UsingTask AssemblyFile="$(PrepTasksAssembly)" TaskName="Xamarin.Android.BuildTools.PrepTasks.ReplaceFileContents" />
<PropertyGroup>
<FrameworkSrcDir>$(XAInstallPrefix)xbuild-frameworks\MonoAndroid\</FrameworkSrcDir>
<AndroidApiDocsPath Condition=" '$(AndroidApiDocsPath)' == '' ">$(XamarinAndroidSourcePath)external\android-api-docs\</AndroidApiDocsPath>
<_AndroidApiDocsPath>$([MSBuild]::EnsureTrailingSlash($(AndroidApiDocsPath)))</_AndroidApiDocsPath>
<_LatestStableFrameworkDir>$(FrameworkSrcDir)$(AndroidLatestStableFrameworkVersion)\</_LatestStableFrameworkDir>
<_MonoDocOutputPath>$(XamarinAndroidSourcePath)bin\$(Configuration)\lib\monodoc\</_MonoDocOutputPath>
<LegacyMSBuildSrcDir>$(XAInstallPrefix)xbuild\Xamarin\Android\</LegacyMSBuildSrcDir>
Expand All @@ -23,75 +21,13 @@
<UseCommercialInstallerName Condition="'$(UseCommercialInstallerName)' == ''">False</UseCommercialInstallerName>
<_HasCommercialFiles Condition="Exists('$(MicrosoftAndroidSdkOutDir)Xamarin.Android.Common.Debugging.targets')">True</_HasCommercialFiles>
</PropertyGroup>
<ItemGroup>
<_MsxDocAssembly Include="Mono.Android">
<SourceDir>$(_AndroidApiDocsPath)docs\%(Identity)\en</SourceDir>
</_MsxDocAssembly>
<_MonoDocAssembly Include="@(_MsxDocAssembly);OpenTK-1.0;Xamarin.Android.NUnitLite">
<SourceDir>$(_AndroidApiDocsPath)docs\%(Identity)\en</SourceDir>
</_MonoDocAssembly>
<_BclDocsAssembly Include="mscorlib;System.Core;System.ComponentModel.Composition;System.ComponentModel.DataAnnotations;System.Data;System" />
<_BclDocsAssembly Include="System.EnterpriseServices;System.Json;System.Numerics;System.Runtime.Serialization;System.ServiceModel" />
<_BclDocsAssembly Include="System.ServiceModel.Web;System.Transactions;System.Web.Services;System.Xml;System.Xml.Linq" />
</ItemGroup>
<Target Name="_FindFrameworkDirs">
<ItemGroup>
<_FrameworkDirs Include="@(AndroidApiInfo->'$(FrameworkSrcDir)%(Identity)\')" />
<_FrameworkDirsThatExist Condition="Exists('%(Identity)')" Include="@(_FrameworkDirs)" Exclude="$(FrameworkSrcDir)v13.0.99\" />
<_EarlierFrameworkDir Include="@(_FrameworkDirsThatExist)" Exclude="$(_LatestStableFrameworkDir)" />
</ItemGroup>
</Target>
<Target Name="_FindDocSourceFiles">
<ItemGroup>
<_MsxDocSourceFile Include="%(_MsxDocAssembly.SourceDir)\**" />
<_MonoDocSourceFile Include="%(_MonoDocAssembly.SourceDir)\**" />
</ItemGroup>
</Target>
<Target Name="_GenerateMsxDocXmls"
DependsOnTargets="_FindFrameworkDirs;_FindDocSourceFiles"
Inputs="@(_MsxDocSourceFile)"
Outputs="@(_MsxDocAssembly->'$(_LatestStableFrameworkDir)%(Identity).xml');@(_MsxDocAssembly->'$(_MonoAndroidNETDefaultOutDir)%(Identity).xml')">
<Exec Command="$(ManagedRuntime) &quot;$(MicrosoftAndroidSdkOutDir)mdoc.exe&quot; --debug export-msxdoc -o &quot;$(_LatestStableFrameworkDir)%(_MsxDocAssembly.Identity).xml&quot; &quot;%(_MsxDocAssembly.SourceDir)&quot;" />
<Copy
SourceFiles="$(_LatestStableFrameworkDir)%(_MsxDocAssembly.Identity).xml"
DestinationFolder="$(_MonoAndroidNETDefaultOutDir)"
/>
<Touch Files="@(_MsxDocAssembly->'$(_LatestStableFrameworkDir)%(Identity).xml');@(_MsxDocAssembly->'$(_MonoAndroidNETDefaultOutDir)%(Identity).xml')" />
</Target>
<Target Name="_GenerateMsxDocXmlRedirects"
DependsOnTargets="_FindFrameworkDirs"
Inputs="$(XamarinAndroidSourcePath)build-tools\scripts\redirect-Mono.Android.xml.in"
Outputs="@(_EarlierFrameworkDir->'%(Identity)Mono.Android.xml')">
<ReplaceFileContents
SourceFile="$(XamarinAndroidSourcePath)build-tools\scripts\redirect-Mono.Android.xml.in"
DestinationFile="%(_EarlierFrameworkDir.Identity)Mono.Android.xml"
Replacements="@LAST_FRAMEWORK_VERSION@=$(AndroidLatestStableFrameworkVersion)" />
</Target>
<Target Name="_GenerateMonoAndroidLibArchive"
DependsOnTargets="_FindDocSourceFiles"
Inputs="@(_MonoDocSourceFile)"
Outputs="$(_MonoDocOutputPath)MonoAndroid-lib.zip;$(_MonoDocOutputPath)MonoAndroid-lib.tree">
<MakeDir Directories="$(_MonoDocOutputPath)"/>
<Exec Command="$(ManagedRuntime) &quot;$(MicrosoftAndroidSdkOutDir)mdoc.exe&quot; --debug assemble -o &quot;$(_MonoDocOutputPath)MonoAndroid-lib&quot; @(_MonoDocAssembly->'&quot;%(SourceDir)&quot;', ' ')" />
</Target>
<Target Name="_GenerateBclAssemblyDocXmlRedirects"
Inputs="$(XamarinAndroidSourcePath)build-tools\scripts\redirect-BCL.xml.in"
Outputs="@(_BclDocsAssembly->'$(FrameworkSrcDir)$(BclFrameworkVersion)\%(Identity).xml')">
<ReplaceFileContents
SourceFile="$(XamarinAndroidSourcePath)build-tools\scripts\redirect-BCL.xml.in"
DestinationFile="$(FrameworkSrcDir)$(BclFrameworkVersion)\%(_BclDocsAssembly.Identity).xml"
Replacements="@ASSEMBLY@=%(_BclDocsAssembly.Identity)" />
</Target>
<Target Name="_CopyMonoAndroidDocsSource"
Inputs="$(_AndroidApiDocsPath)MonoAndroid-docs.source"
Outputs="$(_MonodocOutputPath)MonoAndroid-docs.source">
<Copy
SourceFiles="$(_AndroidApiDocsPath)MonoAndroid-docs.source"
DestinationFolder="$(_MonoDocOutputPath)" />
</Target>
<Target
Name="AssembleApiDocs"
DependsOnTargets="_GenerateMsxDocXmls;_GenerateMsxDocXmlRedirects;_GenerateMonoAndroidLibArchive;_GenerateBclAssemblyDocXmlRedirects;_CopyMonoAndroidDocsSource" />
<Target Name="_WriteVersionFiles"
DependsOnTargets="GetXAVersionInfo" >
<WriteLinesToFile
Expand Down Expand Up @@ -179,7 +115,6 @@
<_FrameworkFiles Include="$(FrameworkSrcDir)\$(BclFrameworkVersion)\Xamarin.Android.NUnitLite.dll" />
<_FrameworkFiles Include="$(FrameworkSrcDir)\$(BclFrameworkVersion)\Xamarin.Android.NUnitLite.pdb" />
<_FrameworkFilesWin Include="$(FrameworkSrcDir)\$(FirstInstallerFrameworkVersion)\OpenTK-1.0.xml" />
<_FrameworkFilesWin Include="@(_BclDocsAssembly->'$(FrameworkSrcDir)$(BclFrameworkVersion)\%(Identity).xml')" />
<_FrameworkFilesWin Include="$(FrameworkSrcDir)\$(BclFrameworkVersion)\Xamarin.Android.NUnitLite.xml" />
</ItemGroup>
<ItemGroup>
Expand Down Expand Up @@ -460,7 +395,7 @@
<LegacyTargetsFiles Include="$(XAInstallPrefix)xbuild\Novell\Xamarin.Android.VisualBasic.targets" />
</ItemGroup>
<Target Name="ConstructInstallerItems"
DependsOnTargets="_FindFrameworkDirs;AssembleApiDocs;_WriteVersionFiles"
DependsOnTargets="_FindFrameworkDirs;_WriteVersionFiles"
Returns="@(FrameworkItemsWin);@(FrameworkItemsUnix);@(MSBuildItemsWin);@(LegacyMSBuildItemsWin);@(MSBuildItemsUnix);@(LegacyMSBuildItemsUnix)">
<ItemGroup>
<_FrameworkFiles Include="@(_FrameworkDirsThatExist->'%(Identity)\AndroidApiInfo.xml')" />
Expand Down
4 changes: 2 additions & 2 deletions build-tools/scripts/JavaCallableWrappers.targets
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,14 +12,14 @@
<_CorlibDir>@(_CorlibPath)</_CorlibDir>
<OutputPathAbs Condition="$([System.IO.Path]::IsPathRooted($(OutputPath)))">$(OutputPath)</OutputPathAbs>
<OutputPathAbs Condition=" '$(OutputPathAbs)' == '' ">$(MSBuildProjectDirectory)/$(OutputPath)</OutputPathAbs>
<JcwGen>"$(XAInstallPrefix)xbuild/Xamarin/Android/jcw-gen.exe" -v10</JcwGen>
<JcwGen>"$(MicrosoftAndroidSdkOutDir)jcw-gen.dll" -v10</JcwGen>
<_LibDirs>-L "$(OutputPathAbs.TrimEnd('\'))"</_LibDirs>
<_LibDirs Condition=" '$(TargetFramework)' == 'monoandroid10' ">$(_LibDirs) -L "$(OutputPathAbs)../v1.0" -L "$(OutputPathAbs)../v1.0/Facades"</_LibDirs>
<_LibDirs Condition=" '$(TargetFramework)' != 'monoandroid10' ">$(_LibDirs) -L "$(_CorlibDir.TrimEnd('\'))"</_LibDirs>
<_Out>-o "$(MSBuildProjectDirectory)/$(IntermediateOutputPath)jcw/src"</_Out>
</PropertyGroup>
<Exec
Command="$(ManagedRuntime) $(ManagedRuntimeArgs) $(JcwGen) $(_Out) $(_LibDirs) &quot;$(JavaCallableWrapperAbsAssembly)&quot;"
Command="&quot;$(DotNetPreviewTool)&quot; $(JcwGen) $(_Out) $(_LibDirs) &quot;$(JavaCallableWrapperAbsAssembly)&quot;"
/>
<ItemGroup>
<_JavaSources Include="$(IntermediateOutputPath)jcw\src\**\*.java" />
Expand Down
6 changes: 4 additions & 2 deletions src/Mono.Android/Mono.Android.csproj
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -393,8 +393,9 @@
<ItemGroup>
<ProjectReference Include="..\..\build-tools\create-android-api\create-android-api.csproj" ReferenceOutputAssembly="false" />
<!-- Explicitly pass the target framework of the project so we don't have conflicts with the multiple targets in this file. -->
<ProjectReference Include="..\..\external\Java.Interop\tools\generator\generator.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="..\..\external\Java.Interop\tools\generator\generator.csproj" ReferenceOutputAssembly="false" SkipGetTargetFrameworkProperties="true" AdditionalProperties="TargetFramework=net7.0" />
<ProjectReference Include="..\..\external\Java.Interop\tools\jcw-gen\jcw-gen.csproj" ReferenceOutputAssembly="false" SkipGetTargetFrameworkProperties="true" AdditionalProperties="TargetFramework=net7.0" />
<ProjectReference Include="..\..\external\Java.Interop\tools\java-source-utils\java-source-utils.csproj" ReferenceOutputAssembly="false" SkipGetTargetFrameworkProperties="true" AdditionalProperties="TargetFramework=net7.0" />
<ProjectReference Include="..\..\src\java-runtime\java-runtime.csproj" ReferenceOutputAssembly="false" />
<ProjectReference Include="..\r8\r8.csproj" ReferenceOutputAssembly="False" />
</ItemGroup>
Expand All @@ -421,6 +422,7 @@
<PropertyGroup Condition=" '$(TargetFramework)' != 'monoandroid10' And '$(AndroidApiLevel)' &gt;= '$(AndroidDefaultTargetDotnetApiLevel)' ">
<BuildDependsOn>
$(BuildDependsOn);
_ExportMsxDoc;
_CopyToPackDirs;
</BuildDependsOn>
</PropertyGroup>
Expand Down
42 changes: 25 additions & 17 deletions src/Mono.Android/Mono.Android.targets
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -160,7 +160,7 @@
/>
</ItemGroup>
<PropertyGroup>
<Generator>"$(XAInstallPrefix)xbuild\Xamarin\Android\generator.exe"</Generator>
<Generator>"$(MicrosoftAndroidSdkOutDir)generator.dll"</Generator>
<_GenFlags>--public --product-version=7</_GenFlags>
<_ApiLevel>--api-level=$(AndroidApiLevel)</_ApiLevel>
<_Out>-o "$(IntermediateOutputPath)mcw"</_Out>
Expand All @@ -180,7 +180,7 @@
<_LangFeatures Condition=" $([MSBuild]::VersionGreaterThanOrEquals($(TargetFrameworkVersion), '7.0')) ">$(_LangFeatures),obsoleted-platform-attributes</_LangFeatures>
</PropertyGroup>
<Exec
Command="$(ManagedRuntime) $(ManagedRuntimeArgs) $(Generator) $(_GenFlags) $(_ApiLevel) $(_Out) $(_Codegen) $(_Fixup) $(_Enums1) $(_Enums2) $(_Versions) $(_Annotations) $(_Assembly) $(_TypeMap) $(_LangFeatures) $(_Dirs) $(_Api) $(_WithJavadocXml)"
Command="&quot;$(DotNetPreviewTool)&quot; $(Generator) $(_GenFlags) $(_ApiLevel) $(_Out) $(_Codegen) $(_Fixup) $(_Enums1) $(_Enums2) $(_Versions) $(_Annotations) $(_Assembly) $(_TypeMap) $(_LangFeatures) $(_Dirs) $(_Api) $(_WithJavadocXml)"
IgnoreStandardErrorWarningFormat="True"
/>
<ItemGroup>
Expand Down Expand Up @@ -292,26 +292,26 @@
<!-- Override these properties to generate docs against a specific API level -->
<DocsApiLevel Condition=" '$(DocsApiLevel)' == '' ">33</DocsApiLevel>
<DocsPlatformId Condition=" '$(DocsPlatformId)' == '' ">33</DocsPlatformId>
<DocsFxVersion Condition=" '$(DocsFxVersion)' == '' ">v13.0</DocsFxVersion>
<DocsFxMoniker Condition=" '$(DocsFxMoniker)' == '' ">xamarin-android-sdk-13</DocsFxMoniker>
<_LogPrefix>$(MSBuildThisFileDirectory)../../bin/Build$(Configuration)/UpdateApiDocs-$([System.DateTime]::Now.ToString ("yyyyMMddTHHmmss"))</_LogPrefix>
<_Mdoc Condition=" '$(Pkgmdoc)' != '' ">"$(Pkgmdoc)/tools/mdoc.exe"</_Mdoc>
<_Mdoc Condition=" '$(Pkgmdoc)' == '' ">"$(XAPackagesDir)/mdoc/$(MdocPackageVersion)/tools/mdoc.exe"</_Mdoc>
</PropertyGroup>

<!-- Generate documentation using MDoc -->
<Target Name="UpdateExternalDocumentation">
<MSBuild Projects="$(MSBuildThisFileDirectory)Mono.Android.csproj"
Properties="TargetFramework=monoandroid10"
Targets="_UpdateExternalDocumentation;_RunMdoc;_GenerateApiDocsDiff"
Properties="TargetFramework=$(DotNetTargetFramework)"
Targets="_UpdateExternalDocumentation;_RunMdoc;_ExportMsxDoc;_GenerateApiDocsDiff"
/>
</Target>
<Target Name="_UpdateExternalDocumentation">
<RemoveDir Directories="$(BaseIntermediateOutputPath)" />
<ItemGroup>
<_BuildProps Include="-p:TargetFramework=$(DotNetTargetFramework)" />
<_BuildProps Include="-p:IncludeAndroidJavadoc=True" />
<_BuildProps Include="-p:TargetFramework=monoandroid10" />
<_BuildProps Include="-p:AndroidApiLevel=$(DocsApiLevel)" />
<_BuildProps Include="-p:AndroidPlatformId=$(DocsPlatformId)" />
<_BuildProps Include="-p:AndroidFrameworkVersion=$(DocsFxVersion)" />
</ItemGroup>
<Exec
Command="&quot;$(DotNetPreviewTool)&quot; build -v:n -c $(Configuration) -bl:$(_LogPrefix).binlog @(_BuildProps, ' ')"
Expand All @@ -322,18 +322,16 @@

<Target Name="RunMdoc">
<MSBuild Projects="$(MSBuildThisFileDirectory)Mono.Android.csproj"
Properties="TargetFramework=monoandroid10"
Targets="_RunMdoc"
/>
</Target>
<Target Name="_RunMdoc">
<PropertyGroup>
<_Mdoc Condition=" '$(Pkgmdoc)' != '' ">"$(Pkgmdoc)/tools/mdoc.exe"</_Mdoc>
<_Libdir>-L "$(XAInstallPrefix)xbuild-frameworks/MonoAndroid/v1.0"</_Libdir>
<_AssemblyBasename>$(XAInstallPrefix)xbuild-frameworks/MonoAndroid/$(DocsFxVersion)/Mono.Android</_AssemblyBasename>
<_Libdir>-L "$(DotNetPreviewPath)packs/Microsoft.NETCore.App.Ref"</_Libdir>
<_AssemblyBasename>$(_MonoAndroidNETDefaultOutDir)Mono.Android</_AssemblyBasename>
<_ImportXml>-i "$(_AssemblyBasename).xml"</_ImportXml>
<_Assembly>$(_AssemblyBasename).dll</_Assembly>
<_JIAssembly>$(XAInstallPrefix)xbuild-frameworks/MonoAndroid/v1.0/Java.Interop.dll</_JIAssembly>
<_JIAssembly>$(_MonoAndroidNETDefaultOutDir)Java.Interop.dll</_JIAssembly>
<_Output>-o "$(MSBuildThisFileDirectory)../../external/android-api-docs/docs/Mono.Android/en"</_Output>
<_DocTypeArgs Condition=" '$(DocTypeName)' != '' ">--type=$(DocTypeName)</_DocTypeArgs>
<_RootFxDir>$(BaseIntermediateOutputPath)docs-gen-temp/</_RootFxDir>
Expand Down Expand Up @@ -366,11 +364,6 @@
Command="$(ManagedRuntime) $(ManagedRuntimeArgs) $(_Mdoc) --debug update --use-docid --delete $(_Libdir) $(_ImportXml) $(_Output) $(_DocTypeArgs) $(_FxConfig) $(_Lang)"
WorkingDirectory="$(MSBuildThisFileDirectory)"
/>
<!-- Ensure updated docs can also be exported to msxdoc format -->
<Exec
Command="$(ManagedRuntime) $(ManagedRuntimeArgs) $(_Mdoc) --debug export-msxdoc -o &quot;$(_LogPrefix)-Export.xml&quot; &quot;$(XamarinAndroidSourcePath)external/android-api-docs/docs/Mono.Android/en/&quot;"
WorkingDirectory="$(MSBuildThisFileDirectory)"
/>
</Target>

<Target Name="_GenerateApiDocsDiff">
Expand All @@ -388,4 +381,19 @@
/>
</Target>

<Target Name="_FindDocSourceFiles">
<ItemGroup>
<_MsxDocSourceFile Include="$(XamarinAndroidSourcePath)external\android-api-docs\docs\Mono.Android\en\**" />
</ItemGroup>
</Target>

<Target Name="_ExportMsxDoc"
DependsOnTargets="_FindDocSourceFiles"
Inputs="@(_MsxDocSourceFile)"
Outputs="$(_MonoAndroidNETDefaultOutDir)Mono.Android.xml">
<Exec
Command="$(ManagedRuntime) $(ManagedRuntimeArgs) $(_Mdoc) --debug export-msxdoc -o &quot;$(_MonoAndroidNETDefaultOutDir)Mono.Android.xml&quot; &quot;$(XamarinAndroidSourcePath)external/android-api-docs/docs/Mono.Android/en/&quot;"
/>
</Target>

</Project>