From 63f78b7bb8c8ec25029b69409b9a28e99d0dbac6 Mon Sep 17 00:00:00 2001
From: Jonathan Pryor <jonpryor@vt.edu>
Date: Mon, 11 Jan 2021 13:11:09 -0500
Subject: [PATCH 1/2] [Mono.Android] Add UpdateExternalDocumentation target

Fixes: https://github.com/xamarin/xamarin-android/issues/5200

Context: a7413a2389886082c3d3422c50a7e6cc84f43d8f
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 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/
---
 src/Mono.Android/Mono.Android.csproj  |  2 +-
 src/Mono.Android/Mono.Android.targets | 43 ++++++++++++++++++++++++++-
 2 files changed, 43 insertions(+), 2 deletions(-)

diff --git a/src/Mono.Android/Mono.Android.csproj b/src/Mono.Android/Mono.Android.csproj
index 21378536fec..20078285cc6 100644
--- a/src/Mono.Android/Mono.Android.csproj
+++ b/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' ">
diff --git a/src/Mono.Android/Mono.Android.targets b/src/Mono.Android/Mono.Android.targets
index 98364ae33dd..03f2b547697 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,37 @@
       <FileWrites Include="$(IntermediateOutputPath)CheckApiCompatibility.stamp" />
     </ItemGroup>
   </Target>
+
+  <Target Name="UpdateExternalDocumentation">
+    <MSBuild Projects="$(MSBuildThisFileDirectory)Mono.Android.csproj"
+        Properties="TargetFramework=monoandroid10"
+        Targets="_UpdateExternalDocumentation"
+    />
+  </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>
+      <_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>
+    </PropertyGroup>
+    <Exec
+        Command="$(ManagedRuntime) $(ManagedRuntimeArgs) $(_Mdoc) --debug update --use-docid --delete $(_Libdir) $(_ImportXml) $(_Output) $(_Assembly)"
+        WorkingDirectory="$(MSBuildThisFileDirectory)"
+    />
+  </Target>
 </Project>

From 583196d850b69fa168f28a958453513260f444db Mon Sep 17 00:00:00 2001
From: Peter Collins <pecolli@microsoft.com>
Date: Wed, 12 May 2021 14:25:58 -0400
Subject: [PATCH 2/2] Separate mdoc target, add doc type arg

---
 src/Mono.Android/Mono.Android.csproj  | 20 +++++++++---------
 src/Mono.Android/Mono.Android.targets | 29 ++++++++++++++++++++-------
 2 files changed, 32 insertions(+), 17 deletions(-)

diff --git a/src/Mono.Android/Mono.Android.csproj b/src/Mono.Android/Mono.Android.csproj
index b3ec7189b80..0a927e2f28e 100644
--- a/src/Mono.Android/Mono.Android.csproj
+++ b/src/Mono.Android/Mono.Android.csproj
@@ -23,16 +23,6 @@
     <ProduceReferenceAssembly>true</ProduceReferenceAssembly>
   </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 Condition=" '$(TargetFramework)' == 'monoandroid10' ">
     <TargetFrameworkIdentifier>MonoAndroid</TargetFrameworkIdentifier>
     <TargetFrameworkVersion>v1.0</TargetFrameworkVersion>
@@ -45,6 +35,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 7f1a1bd031d..26a20fd179b 100644
--- a/src/Mono.Android/Mono.Android.targets
+++ b/src/Mono.Android/Mono.Android.targets
@@ -272,22 +272,35 @@
   <Target Name="UpdateExternalDocumentation">
     <MSBuild Projects="$(MSBuildThisFileDirectory)Mono.Android.csproj"
         Properties="TargetFramework=monoandroid10"
-        Targets="_UpdateExternalDocumentation"
+        Targets="_UpdateExternalDocumentation;_RunMdoc"
     />
   </Target>
   <Target Name="_UpdateExternalDocumentation">
-    <Exec
-        Command="git clean -xdf obj"
-        WorkingDirectory="$(MSBuildThisFileDirectory)"
-    />
+    <RemoveDir Directories="$(BaseIntermediateOutputPath)" />
     <PropertyGroup>
       <_Binlog>UpdateExternalDocumentation-$([System.DateTime]::Now.ToString ("yyyyMMddTHHmmss")).binlog</_Binlog>
     </PropertyGroup>
     <Exec
-        Command="msbuild /restore /p:IncludeAndroidJavadoc=True /bl:$(_Binlog)"
+        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>
@@ -295,10 +308,12 @@
       <_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) $(_Assembly)"
+        Command="$(ManagedRuntime) $(ManagedRuntimeArgs) $(_Mdoc) --debug update --use-docid --delete $(_Libdir) $(_ImportXml) $(_Output) $(_DocTypeArgs) $(_Assembly) "
         WorkingDirectory="$(MSBuildThisFileDirectory)"
     />
   </Target>
+
 </Project>