From 07dc60b04273941787e56ff3d02fbb8df98ab0ce Mon Sep 17 00:00:00 2001
From: Peter Collins <pecolli@microsoft.com>
Date: Tue, 17 Oct 2023 21:31:27 -0400
Subject: [PATCH] [Mono.Android] Generate API docs with "full" verbosity
 (#8435)

Updates `$(AndroidJavadocVerbosity)` to `full` to generate additional
API docs content.  A `javadocVerbosity` parameter has been added to
the API docs build pipeline to make it easier to toggle this setting
when queueing a docs build.

The docs build pipeline has been updated to upload the output of the
`Mono.Android` build to make it easier to download and push docs
updates to the [apidrop/binaries][0] repository.

[0]: https://apidrop.visualstudio.com/binaries/_git/binaries
---
 .../automation/azure-pipelines-apidocs.yaml   | 36 +++++++++++++++----
 src/Mono.Android/Mono.Android.csproj          |  2 +-
 2 files changed, 31 insertions(+), 7 deletions(-)

diff --git a/build-tools/automation/azure-pipelines-apidocs.yaml b/build-tools/automation/azure-pipelines-apidocs.yaml
index 22642c3a19c..bb7ac1dcd93 100644
--- a/build-tools/automation/azure-pipelines-apidocs.yaml
+++ b/build-tools/automation/azure-pipelines-apidocs.yaml
@@ -29,6 +29,12 @@ parameters:
   type: string
   default: default
 
+- name: javadocVerbosity
+  displayName: AndroidJavadocVerbosity property value
+  type: string
+  default: default
+
+
 # Global variables
 variables:
 - template: yaml-templates/variables.yaml
@@ -40,6 +46,8 @@ variables:
   value: ''
 - name: MdocPackageVersionArg
   value: ''
+- name: AndroidJavadocVerbosity
+  value: ''
 
 
 stages:
@@ -79,6 +87,10 @@ stages:
       - script: echo "##vso[task.setvariable variable=MdocPackageVersionArg]-p:MdocPackageVersion=${{ parameters.mdocVersion }}"
         displayName: set MdocPackageVersionArg
 
+    - ${{ if ne(parameters.javadocVerbosity, 'default') }}:
+      - script: echo "##vso[task.setvariable variable=AndroidJavadocVerbosity]-p:AndroidJavadocVerbosity=${{ parameters.javadocVerbosity }}"
+        displayName: set AndroidJavadocVerbosity
+
     - template: yaml-templates/use-dot-net.yaml
 
     - task: NuGetAuthenticate@0
@@ -97,15 +109,21 @@ stages:
 
     - script: >-
         make update-api-docs CONFIGURATION=$(XA.Build.Configuration)
-        MSBUILD_ARGS='$(DocsApiLevelArg) $(DocsPlatformIdArg) $(DocsFxVersionArg) $(MdocPackageVersionArg)'
+        MSBUILD_ARGS='$(DocsApiLevelArg) $(DocsPlatformIdArg) $(DocsFxVersionArg) $(MdocPackageVersionArg) $(AndroidJavadocVerbosity)'
       workingDirectory: $(Build.SourcesDirectory)
       displayName: make update-api-docs
 
-    - template: yaml-templates/upload-results.yaml
-      parameters:
-        artifactName: Build Results - API Docs Update
-        includeBuildResults: true
-        condition: always()
+    - script: >
+        mkdir -p $(Build.StagingDirectory)/docs-binaries &&
+        ln $(Build.SourcesDirectory)/bin/$(XA.Build.Configuration)/lib/xamarin.android/xbuild-frameworks/Microsoft.Android/34/*.dll $(Build.StagingDirectory)/docs-binaries/ &&
+        ln $(Build.SourcesDirectory)/bin/$(XA.Build.Configuration)/lib/xamarin.android/xbuild-frameworks/Microsoft.Android/34/*.xml $(Build.StagingDirectory)/docs-binaries/
+      displayName: copy docs files
+
+    - task: PublishPipelineArtifact@1
+      displayName: upload docs files
+      inputs:
+        artifactName: Binaries
+        targetPath: $(Build.StagingDirectory)/docs-binaries
 
     - script: >
         mkdir -p $(Build.StagingDirectory)/api-doc-diff &&
@@ -118,6 +136,12 @@ stages:
         artifactName: Api Docs Diff
         targetPath: $(Build.StagingDirectory)/api-doc-diff
 
+    - template: yaml-templates/upload-results.yaml
+      parameters:
+        artifactName: Build Results - API Docs Update
+        includeBuildResults: true
+        condition: always()
+
     - powershell: |
         $docsUpdateBinlog = Get-ChildItem -Path "$(Build.SourcesDirectory)/bin/Build$(XA.Build.Configuration)" -Filter *UpdateApiDocs-*.binlog | Select-Object -First 1
         $buildLog = "$(Build.SourcesDirectory)/bin/Build$(XA.Build.Configuration)/temp-build.log"
diff --git a/src/Mono.Android/Mono.Android.csproj b/src/Mono.Android/Mono.Android.csproj
index d1e4a1ff731..aed5a7bc6de 100644
--- a/src/Mono.Android/Mono.Android.csproj
+++ b/src/Mono.Android/Mono.Android.csproj
@@ -37,7 +37,7 @@
   </PropertyGroup>
 
   <PropertyGroup Condition=" '$(IncludeAndroidJavadoc)' == 'True' ">
-    <AndroidJavadocVerbosity Condition=" '$(AndroidJavadocVerbosity)' == '' ">intellisense+extraremarks</AndroidJavadocVerbosity>
+    <AndroidJavadocVerbosity Condition=" '$(AndroidJavadocVerbosity)' == '' ">full</AndroidJavadocVerbosity>
     <DocumentationFile>$(OutputPath)Mono.Android.xml</DocumentationFile>
     <NoWarn>$(NoWarn);CS1572;CS1573;CS1574;CS1584;CS1587;CS1591;CS1658;</NoWarn>
   </PropertyGroup>