[Xamarin.Android.Build.Tasks] Support %(JavaSourceJar.DocRootUrl)

Author: pjcollins

Documentation/guides/building-apps/build-items.md

@@ -370,6 +370,11 @@ Starting in Xamarin.Android 11.3, the following MSBuild metadata is supported:
     online documentation.  Only one style is currently supported:
     `developer.android.com/reference@2020-Nov`.
 
+Starting in Xamarin.Android 12.1, the following MSBuild metadata is supported:
+
+* `%(DocRootUrl)`: A URL prefix to use in place of all {@docroot}
+    instances in the imported documentation.
+
 
 ## LibraryProjectZip
 

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

@@ -47,19 +47,11 @@ 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
+    - task: DotNetCoreCLI@2
       displayName: update android-api-docs
       inputs:
-        solution: $(Build.SourcesDirectory)/src/Mono.Android/Mono.Android.csproj
-        configuration: $(XA.Build.Configuration)
-        msbuildArguments: /restore /t:UpdateExternalDocumentation
+        projects: $(Build.SourcesDirectory)/src/Mono.Android/Mono.Android.csproj
+        arguments: -t:UpdateExternalDocumentation -c $(XA.Build.Configuration) -v:n
 
     - template: yaml-templates/upload-results.yaml
       parameters:

external/Java.Interop

@@ -78,6 +78,8 @@
       <_Doclink Include="https://developer.android.com/reference" />
       <_Doclink Include="--doc-url-style" />
       <_Doclink Include="developer.android.com/reference@2020-Nov" />
+      <_Doclink Include="--doc-root-url" />
+      <_Doclink Include="https://developer.android.com/" />
     </ItemGroup>
     <ItemGroup>
       <_AndroidSources Include="$(_AndroidStableSrcDir)\android\**\*.java" />
@@ -285,6 +287,7 @@
     <PropertyGroup>
       <_Binlog>$(MSBuildThisFileDirectory)../../bin/Build$(Configuration)/UpdateExternalDocumentation-$([System.DateTime]::Now.ToString ("yyyyMMddTHHmmss")).binlog</_Binlog>
     </PropertyGroup>
+    <Exec Command="dotnet build -v:n -c $(Configuration) $(JavaInteropFullPath)\build-tools\jnienv-gen\jnienv-gen.csproj" />
     <Exec
         Command="dotnet build -v:n -c $(Configuration) -p:IncludeAndroidJavadoc=True -bl:$(_Binlog)"
         IgnoreStandardErrorWarningFormat="True"

src/Mono.Android/Mono.Android.targets

@@ -79,6 +79,7 @@ This file is only used by binding projects.
         JavadocCopyrightFile="%(_JavaSourceJavadocXml.CopyrightFile)"
         JavadocUrlPrefix="%(_JavaSourceJavadocXml.UrlPrefix)"
         JavadocUrlStyle="%(_JavaSourceJavadocXml.UrlStyle)"
+        JavadocDocRootUrl="%(_JavaSourceJavadocXml.DocRootUrl)"
         JavaMaximumHeapSize="$(JavaMaximumHeapSize)"
         JavaOptions="$(JavaOptions)"
         JavaSdkDirectory="$(_JavaSdkDirectory)"

src/Xamarin.Android.Build.Tasks/MSBuild/Xamarin/Android/Xamarin.Android.Bindings.ClassParse.targets

@@ -31,6 +31,7 @@ public class JavaSourceUtils : AndroidToolTask
 		public  ITaskItem   JavadocCopyrightFile        { get; set; }
 		public  string      JavadocUrlPrefix            { get; set; }
 		public  string      JavadocUrlStyle             { get; set; }
+		public  string      JavadocDocRootUrl           { get; set; }
 
 		public  string      JavaOptions                 { get; set; }
 
@@ -139,11 +140,15 @@ string CreateResponseFile ()
 			}
 			if (!string.IsNullOrEmpty (JavadocUrlPrefix)) {
 				AppendArg (response, "--doc-url-prefix");
-				AppendArg (response, Path.GetFullPath (JavadocUrlPrefix));
+				AppendArg (response, JavadocUrlPrefix);
 			}
 			if (!string.IsNullOrEmpty (JavadocUrlStyle)) {
-				AppendArg (response, "--doc-link-style");
-				AppendArg (response, Path.GetFullPath (JavadocUrlStyle));
+				AppendArg (response, "--doc-url-style");
+				AppendArg (response, JavadocUrlStyle);
+			}
+			if (!string.IsNullOrEmpty (JavadocDocRootUrl)) {
+				AppendArg (response, "--doc-root-url");
+				AppendArg (response, JavadocDocRootUrl);
 			}
 
 			foreach (var path in InputFiles) {

src/Xamarin.Android.Build.Tasks/Tasks/JavaSourceUtils.cs

@@ -470,18 +470,29 @@ public void JavaSourceJar ()
 				AndroidClassParser = "class-parse",
 			};
 			binding.SetProperty ("DocumentationFile", "UnnamedProject.xml");
+			binding.SetProperty ("AndroidJavadocVerbosity", "full");
 			using (var bindingBuilder = CreateDllBuilder ()) {
 				binding.Jars.Add (new AndroidItem.EmbeddedJar ("javasourcejartest.jar") {
 					BinaryContent = () => ResourceData.JavaSourceJarTestJar,
 				});
+				binding.OtherBuildItems.Add (new BuildItem ("None", "javadoc-copyright.xml") {
+					BinaryContent = () => ResourceData.JavadocCopyright,
+				});
 				binding.OtherBuildItems.Add (new BuildItem ("JavaSourceJar", "javasourcejartest-sources.jar") {
 					BinaryContent = () => ResourceData.JavaSourceJarTestSourcesJar,
+					MetadataValues = "CopyrightFile=$(MSBuildThisFileDirectory)javadoc-copyright.xml;" +
+						"UrlPrefix=https://developer.android.com/reference;" +
+						"UrlStyle=developer.android.com/reference@2020-Nov;" +
+						"DocRootUrl=https://developer.android.com",
 				});
 				Assert.IsTrue (bindingBuilder.Build (binding), "binding build should have succeeded");
 
 				var path    = Path.Combine (Root, bindingBuilder.ProjectDirectory, binding.OutputPath, "UnnamedProject.xml");
 				var xml     = File.ReadAllText (path);
 				Assert.IsTrue (xml.Contains ("<param name=\"name\">name to display.</param>"), "param `name` documentation not imported!");
+				Assert.IsTrue (xml.Contains ("Includes a https://developer.android.com/test.html element."), "{@docRoot} value was not replaced!");
+				Assert.IsTrue (xml.Contains ("<a href=\"https://developer.android.com/reference/com/xamarin/android/test/msbuildtest/JavaSourceJarTest#greet(java.lang.String,%20java.util.Date)\" title=\"Reference documentation\">"), "Java documentation URL was not imported!");
+				Assert.IsTrue (xml.Contains ("<a href=\"https://developers.google.com/terms/site-policies\" title=\"Android Open Source Project\">Android Open Source Project</a>"), "Copyright file was not imported!");
 			}
 		}