[Mono.Android] Generate docs for any API level

The `_UpdateExternalDocumentation` target has been updated to allow API
docs to be updated against any API level.  Latest stable versions will
still be used by default, however the `$(AndroidApiLevel)`,
`$(AndroidPlatformId)`, and `$(AndroidFrameworkVersion)` properties can
now be set if needed.  This will let us update the current API 31 docs
without having to release an API 32 update.

The api docs pipeline has been updated to allow these properties to be
set at queue time, and it will now upload a `.diff` file rather than
the entire docs folder.

Author: pjcollins

Makefile

@@ -223,3 +223,6 @@ APK_SIZES_REFERENCE_DIR=tests/apk-sizes-reference
 update-apk-sizes-reference:
 	-mkdir -p $(APK_SIZES_REFERENCE_DIR)
 	cp -v *values-$(CONFIGURATION).csv $(APK_SIZES_REFERENCE_DIR)/
+
+update-api-docs:
+		$(call DOTNET_BINLOG,update-api-docs) -t:UpdateExternalDocumentation src/Mono.Android/Mono.Android.csproj

build-tools/automation/azure-pipelines-apidocs.yaml

@@ -8,6 +8,22 @@
 trigger: none
 pr: none
 
+parameters:
+- name: apiLevel
+  displayName: AndroidApiLevel property value
+  type: string
+  default: 31
+
+- name: platformId
+  displayName: AndroidPlatformId property value
+  type: string
+  default: 31
+
+- name: frameworkVersion
+  displayName: AndroidFrameworkVersion property value
+  type: string
+  default: v12.0
+
 # Global variables
 variables:
 - template: yaml-templates/variables.yaml
@@ -20,7 +36,8 @@ stages:
   - job: mac_build_update_docs
     displayName: Update API Docs
     pool:
-      vmImage: macOS-11
+      name: VSEng-Xamarin-RedmondMac-Android-Untrusted
+      demands: macOS.Name -equals Monterey
     timeoutInMinutes: 120
     workspace:
       clean: all
@@ -47,28 +64,22 @@ stages:
       workingDirectory: $(Build.SourcesDirectory)
       displayName: make prepare
 
-    - task: MSBuild@1
-      displayName: build jnienv-gen.csproj
-      inputs:
-        solution: $(Build.SourcesDirectory)/external/Java.Interop/build-tools/jnienv-gen/jnienv-gen.csproj
-        configuration: $(XA.Build.Configuration)
-        msbuildArguments: /restore
-
-    - task: MSBuild@1
-      displayName: update android-api-docs
-      inputs:
-        solution: $(Build.SourcesDirectory)/src/Mono.Android/Mono.Android.csproj
-        configuration: $(XA.Build.Configuration)
-        msbuildArguments: /restore /t:UpdateExternalDocumentation
+    - script: make update-api-docs CONFIGURATION=$(XA.Build.Configuration) MSBUILD_ARGS='-p:AndroidApiLevel=${{ parameters.apiLevel }} -p:AndroidPlatformId=${{ parameters.platformId }} -p:AndroidFrameworkVersion=${{ parameters.frameworkVersion }}'
+      workingDirectory: $(Build.SourcesDirectory)
+      displayName: make update-api-docs
 
     - template: yaml-templates/upload-results.yaml
       parameters:
-        xaSourcePath: $(System.DefaultWorkingDirectory)/xamarin-android
         artifactName: Build Results - API Docs Update
         includeBuildResults: true
 
+    - script: >
+        mkdir -p $(Build.StagingDirectory)/api-doc-diff &&
+        ln $(Build.SourcesDirectory)/bin/Build$(XA.Build.Configuration)/UpdateApiDocs*.diff $(Build.StagingDirectory)/api-doc-diff/
+      displayName: copy api docs diff
+
     - task: PublishPipelineArtifact@1
-      displayName: upload Mono.Android docs
+      displayName: upload api docs diff
       inputs:
-        artifactName: Mono.Android Docs
-        targetPath: $(Build.SourcesDirectory)/external/android-api-docs/docs/Mono.Android/en/
+        artifactName: Api Docs Diff
+        targetPath: $(Build.StagingDirectory)/api-doc-diff

src/Mono.Android/Mono.Android.targets

@@ -75,14 +75,14 @@
   <!-- Pulls documentation from JavaDoc -->
   <PropertyGroup>
     <_JavaSourceUtilsJar>$(MicrosoftAndroidSdkOutDir)java-source-utils.jar</_JavaSourceUtilsJar>
-    <_AndroidStableSrcDir>$(AndroidSdkDirectory)\platforms\android-$(AndroidLatestStableApiLevel)\src</_AndroidStableSrcDir>
+    <_AndroidSrcDir>$(AndroidSdkDirectory)\platforms\android-$(AndroidApiLevel)\src</_AndroidSrcDir>
     <_AndroidJavadocXml>..\..\bin\Build$(Configuration)\android-javadoc.xml</_AndroidJavadocXml>
   </PropertyGroup>
 
   <Target Name="_BuildAndroidJavadocXml"
       Condition=" '$(IncludeAndroidJavadoc)' == 'True' "
       BeforeTargets="CoreCompile"
-      Inputs="$(MSBuildThisFile);$(_AndroidStableSrcDir)\source.properties;$(_JavaSourceUtilsJar)"
+      Inputs="$(MSBuildThisFile);$(_AndroidSrcDir)\source.properties;$(_JavaSourceUtilsJar)"
       Outputs="$(_AndroidJavadocXml)">
     <ItemGroup>
       <_Doclink Include="--doc-copyright" />
@@ -95,11 +95,11 @@
       <_Doclink Include="https://developer.android.com/" />
     </ItemGroup>
     <ItemGroup>
-      <_AndroidSources Include="$(_AndroidStableSrcDir)\android\**\*.java" />
-      <_AndroidSources Include="$(_AndroidStableSrcDir)\java\**\*.java" />
-      <_AndroidSources Include="$(_AndroidStableSrcDir)\javax\**\*.java" />
-      <_AndroidSources Include="$(_AndroidStableSrcDir)\org\**\*.java" />
-      <_AndroidSources Remove="$(_AndroidStableSrcDir)\**\*.annotated.java" />
+      <_AndroidSources Include="$(_AndroidSrcDir)\android\**\*.java" />
+      <_AndroidSources Include="$(_AndroidSrcDir)\java\**\*.java" />
+      <_AndroidSources Include="$(_AndroidSrcDir)\javax\**\*.java" />
+      <_AndroidSources Include="$(_AndroidSrcDir)\org\**\*.java" />
+      <_AndroidSources Remove="$(_AndroidSrcDir)\**\*.annotated.java" />
     </ItemGroup>
     <PropertyGroup>
       <_Filenames>$(IntermediateOutputPath)\java-sources.txt</_Filenames>
@@ -111,7 +111,7 @@
     />
     <ItemGroup>
       <_JSIArg Include="-v" />
-      <_JSIArg Include="--source &quot;$(_AndroidStableSrcDir)&quot;" />
+      <_JSIArg Include="--source &quot;$(_AndroidSrcDir)&quot;" />
       <_JSIArg Include="--output-javadoc &quot;$(_AndroidJavadocXml)&quot;" />
       <_JSIArg Include="@$(_Filenames)" />
     </ItemGroup>
@@ -289,16 +289,24 @@
   <Target Name="UpdateExternalDocumentation">
     <MSBuild Projects="$(MSBuildThisFileDirectory)Mono.Android.csproj"
         Properties="TargetFramework=monoandroid10"
-        Targets="_UpdateExternalDocumentation;_RunMdoc"
+        Targets="_UpdateExternalDocumentation;_RunMdoc;_GenerateApiDocsDiff"
     />
   </Target>
   <Target Name="_UpdateExternalDocumentation">
     <RemoveDir Directories="$(BaseIntermediateOutputPath)" />
     <PropertyGroup>
-      <_Binlog>$(MSBuildThisFileDirectory)../../bin/Build$(Configuration)/UpdateExternalDocumentation-$([System.DateTime]::Now.ToString ("yyyyMMddTHHmmss")).binlog</_Binlog>
+      <_Binlog>$(MSBuildThisFileDirectory)../../bin/Build$(Configuration)/UpdateApiDocs-$([System.DateTime]::Now.ToString ("yyyyMMddTHHmmss")).binlog</_Binlog>
     </PropertyGroup>
+    <ItemGroup>
+      <_BuildProps Include="-p:IncludeAndroidJavadoc=True" />
+      <_BuildProps Include="-p:TargetFramework=monoandroid10" />
+      <!-- Override these properties to generate docs against a specific API level -->
+      <_BuildProps Include="-p:AndroidApiLevel=$(AndroidApiLevel)" />
+      <_BuildProps Include="-p:AndroidPlatformId=$(AndroidPlatformId)" />
+      <_BuildProps Include="-p:AndroidFrameworkVersion=$(AndroidFrameworkVersion)" />
+    </ItemGroup>
     <Exec
-        Command="dotnet build -v:n -c $(Configuration) -p:IncludeAndroidJavadoc=True -bl:$(_Binlog)"
+        Command="&quot;$(DotNetPreviewTool)&quot; build -v:n -c $(Configuration) -bl:$(_Binlog) @(_BuildProps, ' ')"
         IgnoreStandardErrorWarningFormat="True"
         WorkingDirectory="$(MSBuildThisFileDirectory)"
     />
@@ -352,5 +360,15 @@
         WorkingDirectory="$(MSBuildThisFileDirectory)"
     />
   </Target>
-  
+
+  <Target Name="_GenerateApiDocsDiff">
+    <PropertyGroup>
+      <_DiffFile>$(XamarinAndroidSourcePath)bin/Build$(Configuration)/UpdateApiDocs$([System.DateTime]::Now.ToString ("yyyyMMddTHHmmss")).diff</_DiffFile>
+    </PropertyGroup>
+    <Exec
+        Command="git diff --output=&quot;$(_DiffFile)&quot;"
+        WorkingDirectory="$(XamarinAndroidSourcePath)external/android-api-docs"
+    />
+  </Target>
+
 </Project>