[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.3, 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

@@ -1,3 +1,4 @@
+
 # Pipeline for updating and uploading android-api-docs/docs/Mono.Android/en/*
 # https://dev.azure.com/devdiv/DevDiv/_build?definitionId=15262
 

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" />

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!");
 			}
 		}