[Mono.Android] Add UpdateExternalDocumentation target

Fixes: #5200

Context: a7413a2
Context: xamarin/android-api-docs#23
Context: https://review.docs.microsoft.com/en-us/engineering/projects/reference/dotnet/mdoc

Add a new `UpdateExternalDocumentation` target which:

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

    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.

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/

Author: jonpryor

src/Mono.Android/Mono.Android.csproj

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

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,29 @@
       <FileWrites Include="$(IntermediateOutputPath)CheckApiCompatibility.stamp" />
     </ItemGroup>
   </Target>
+
+  <Target Name="UpdateExternalDocumentation">
+    <Exec Command="git clean -xdf obj" WorkingDirectory="$(MSBuildThisFileDirectory)" />
+    <PropertyGroup>
+      <_Binlog>UpdateExternalDocumentation-$([System.DateTime]::Now.ToString ("yyyyMMddTHHmmss")).binlog</_Binlog>
+    </PropertyGroup>
+    <Exec
+        Command="msbuild /restore /p:IncludeAndroidJavadoc=True /bl:$(_Binlog)"
+        IgnoreStandardErrorWarningFormat="True"
+        WorkingDirectory="$(MSBuildThisFileDirectory)"
+    />
+    <PropertyGroup>
+      <_Mdoc Condition=" '$(Pkgmdoc)' != '' ">"$(Pkgmdoc)/tools/mdoc.exe"</_Mdoc>
+      <_Mdoc Condition=" '$(_Mdoc)' == '' ">"$(MSBuildThisFileDirectory)../../packages/mdoc/5.0.0.25/tools/mdoc.exe"</_Mdoc>
+      <_Libdir>-L "$(XAInstallPrefix)/xbuild-frameworks/MonoAndroid/v1.0"</_Libdir>
+      <_AssemblyBasename>$(XAInstallPrefix)/xbuild-frameworks/MonoAndroid/$(AndroidFrameworkVersion)/Mono.Android</_AssemblyBasename>
+      <_ImportXml>-i "$(_AssemblyBasename).xml"</_ImportXml>
+      <_Assembly>"$(_AssemblyBasename).dll"</_Assembly>
+      <_Output>-o "$(MSBuildThisFileDirectory)../../external/android-api-docs/docs/Mono.Android/en"</_Output>
+    </PropertyGroup>
+    <Exec
+        Command="$(ManagedRuntime) $(ManagedRuntimeArgs) $(_Mdoc) --debug update --use-docid --delete $(_Libdir) $(_ImportXml) $(_Output) $(_Assembly)"
+        WorkingDirectory="$(MSBuildThisFileDirectory)"
+    />
+  </Target>
 </Project>