Skip to content

Commit

Permalink
[Mono.Android] Add UpdateExternalDocumentation target (#5485)
Browse files Browse the repository at this point in the history
Context: a7413a2
Context: #5200
Context: xamarin/android-api-docs#23
Context: https://review.docs.microsoft.com/en-us/engineering/projects/reference/dotnet/mdoc

Add a new `UpdateExternalDocumentation` target to
`src/Mono.Android/Mono.Android.csproj` which:

 1. *Rebuilds* `src/Mono.Android` with
    `$(IncludeAndroidJavadoc)`=True.  This produces a
    `Mono.Anroid.xml` file containing imported API-30 Javadoc.

    On macOS, this *also* produces the log file
    `src/Mono.Android/UpdateExternalDocumentation-{TIME}.binlog`,
    which contains the build output for the rebuild.

 2. Runs `mdoc update --import Mono.Android.xml --use-docid`,
    updating the [**mdoc**(5) documentation][0] within
    `external/android-api-docs/docs/Mono.Android/en`

    The `--use-docid` flag is needed for integration with the
    documentation infrastructure.

Usage:

	msbuild /t:UpdateExternalDocumentation src/Mono.Android/Mono.Android.csproj

This process takes ~60 minutes on my machine.

Additionally, add a new `RunMdoc` target, which just runs the
`mdoc update --import…` command.  This is useful for one-off testing.

The `UpdateExternalDocumentation` and `RunMdoc` targets also takes an
optional `$(DocTypeName)` MSBuild property, which is used to restrict
the types that `mdoc update` will update:

	msbuild /p:DocTypeName=Java.Lang.Object /t:UpdateExternalDocumentation src/Mono.Android/Mono.Android.csproj
	# -or-
	msbuild /p:DocTypeName=Java.Lang.Object /t:RunMdoc src/Mono.Android/Mono.Android.csproj

Note: This uses the [mdoc NuGet package][1].

[0]: http://docs.go-mono.com/?link=man%3amdoc(5)
[1]: https://www.nuget.org/packages/mdoc/5.8.0
  • Loading branch information
jonpryor authored Sep 29, 2021
1 parent 1bb7602 commit cee5e72
Show file tree
Hide file tree
Showing 2 changed files with 67 additions and 1 deletion.
10 changes: 10 additions & 0 deletions src/Mono.Android/Mono.Android.csproj
Original file line number Diff line number Diff line change
Expand Up @@ -46,6 +46,16 @@
<OutputPath>$(XAInstallPrefix)xbuild-frameworks\Microsoft.Android\$(TargetFramework)\</OutputPath>
</PropertyGroup>

<PropertyGroup>
<IncludeAndroidJavadoc Condition=" '$(IncludeAndroidJavadoc)' == '' And '$(CONVERT_JAVADOC_TO_XMLDOC)' == 'true' And '$(AndroidFrameworkVersion)' == '$(AndroidLatestStableFrameworkVersion)'">True</IncludeAndroidJavadoc>
<AndroidJavadocVerbosity Condition=" '$(AndroidJavadocVerbosity)' == '' ">intellisense+extraremarks</AndroidJavadocVerbosity>
</PropertyGroup>

<PropertyGroup Condition=" '$(IncludeAndroidJavadoc)' == 'True' ">
<DocumentationFile>$(OutputPath)Mono.Android.xml</DocumentationFile>
<NoWarn>$(NoWarn);CS1572;CS1573;CS1574;CS1584;CS1587;CS1591;CS1658;</NoWarn>
</PropertyGroup>

<PropertyGroup>
<JavaCallableWrapperAbsAssembly>$([System.IO.Path]::GetFullPath ('$(OutputPath)$(AssemblyName).dll'))</JavaCallableWrapperAbsAssembly>
</PropertyGroup>
Expand Down
58 changes: 57 additions & 1 deletion src/Mono.Android/Mono.Android.targets
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,14 @@
<ItemGroup>
<Compile Include="$(IntermediateOutputPath)AssemblyInfo.cs" />
</ItemGroup>
<ItemGroup>
<PackageReference Include="mdoc"
PackageVersion="5.8.0"
GeneratePathProperty="True"
ReferenceOutputAssembly="False"
SkipGetTargetFrameworkProperties="True"
/>
</ItemGroup>
<Target Name="_BuildJavaInterop"
BeforeTargets="BeforeResolveReferences"
Condition=" '$(TargetFramework)' == 'monoandroid10' "
Expand Down Expand Up @@ -157,7 +165,7 @@
<_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>
<_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>
Expand Down Expand Up @@ -260,4 +268,52 @@
<FileWrites Include="$(IntermediateOutputPath)CheckApiCompatibility.stamp" />
</ItemGroup>
</Target>

<Target Name="UpdateExternalDocumentation">
<MSBuild Projects="$(MSBuildThisFileDirectory)Mono.Android.csproj"
Properties="TargetFramework=monoandroid10"
Targets="_UpdateExternalDocumentation;_RunMdoc"
/>
</Target>
<Target Name="_UpdateExternalDocumentation">
<RemoveDir Directories="$(BaseIntermediateOutputPath)" />
<PropertyGroup>
<_Binlog>UpdateExternalDocumentation-$([System.DateTime]::Now.ToString ("yyyyMMddTHHmmss")).binlog</_Binlog>
</PropertyGroup>
<Exec
Condition=" '$(HostOS)' != 'Windows' "
Command="msbuild /restore /p:Configuration=$(Configuration) /p:IncludeAndroidJavadoc=True /bl:$(_Binlog)"
IgnoreStandardErrorWarningFormat="True"
WorkingDirectory="$(MSBuildThisFileDirectory)"
/>
<MSBuild
Condition=" '$(HostOS)' == 'Windows' "
Projects="$(MSBuildThisFileDirectory)Mono.Android.csproj"
Properties="IncludeAndroidJavadoc=True"
Targets="Restore;Build"
/>
</Target>

<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 "$(OutputPath)../v1.0"</_Libdir>
<_AssemblyBasename>$(OutputPath)Mono.Android</_AssemblyBasename>
<_ImportXml>-i "$(_AssemblyBasename).xml"</_ImportXml>
<_Assembly>"$(_AssemblyBasename).dll"</_Assembly>
<_Output>-o "$(MSBuildThisFileDirectory)../../external/android-api-docs/docs/Mono.Android/en"</_Output>
<_DocTypeArgs Condition=" '$(DocTypeName)' != '' ">--type=$(DocTypeName)</_DocTypeArgs>
</PropertyGroup>
<Exec
Command="$(ManagedRuntime) $(ManagedRuntimeArgs) $(_Mdoc) --debug update --use-docid --delete $(_Libdir) $(_ImportXml) $(_Output) $(_DocTypeArgs) $(_Assembly) "
WorkingDirectory="$(MSBuildThisFileDirectory)"
/>
</Target>

</Project>

0 comments on commit cee5e72

Please sign in to comment.