From cee5e72764ab9fa2f9c78a651707b7efbf8732cc Mon Sep 17 00:00:00 2001
From: Jonathan Pryor <jonpryor@vt.edu>
Date: Tue, 28 Sep 2021 20:42:57 -0400
Subject: [PATCH] [Mono.Android] Add UpdateExternalDocumentation target (#5485)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Context: a7413a2389886082c3d3422c50a7e6cc84f43d8f
Context: https://github.com/xamarin/xamarin-android/issues/5200
Context: https://github.com/xamarin/android-api-docs/pull/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
---
 src/Mono.Android/Mono.Android.csproj  | 10 +++++
 src/Mono.Android/Mono.Android.targets | 58 ++++++++++++++++++++++++++-
 2 files changed, 67 insertions(+), 1 deletion(-)

diff --git a/src/Mono.Android/Mono.Android.csproj b/src/Mono.Android/Mono.Android.csproj
index f96fdd296d4..06ec9cbc912 100644
--- a/src/Mono.Android/Mono.Android.csproj
+++ b/src/Mono.Android/Mono.Android.csproj
@@ -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>
diff --git a/src/Mono.Android/Mono.Android.targets b/src/Mono.Android/Mono.Android.targets
index 725b7fdabb3..26a20fd179b 100644
--- a/src/Mono.Android/Mono.Android.targets
+++ b/src/Mono.Android/Mono.Android.targets
@@ -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' "
@@ -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>
@@ -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>