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

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
 

src/Mono.Android/Mono.Android.targets

@@ -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/Xamarin.Android.Build.Tasks/MSBuild/Xamarin/Android/Xamarin.Android.Bindings.ClassParse.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/Tasks/JavaSourceUtils.cs

@@ -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/Tests/Xamarin.Android.Build.Tests/BindingBuildTest.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!");
 			}
 		}
 

src/Xamarin.Android.Build.Tasks/Tests/Xamarin.Android.Build.Tests/Utilities/ResourceData.cs

@@ -16,13 +16,15 @@ static class ResourceData
 		static Lazy<byte []> library1Aar = new Lazy<byte []> (() => GetResourceData ("library1.aar"));
 		static Lazy<byte []> library2Aar = new Lazy<byte []> (() => GetResourceData ("library2.aar"));
 		static Lazy<byte []> apacheHttpClient_cs = new Lazy<byte []> (() => GetResourceData ("ApacheHttpClient.cs"));
+		static Lazy<byte []> javadocCopyright = new Lazy<byte []> (() => GetResourceData ("javadoc-copyright.xml"));
 
 		public  static  byte[]  JavaSourceJarTestJar            => javaSourceJarTestJar.Value;
 		public  static  byte[]  JavaSourceJarTestSourcesJar     => javaSourceJarTestSourcesJar.Value;
 		public  static  byte[]  JavaSourceJarTestJavadocJar     => javaSourceJarTestJavadocJar.Value;
 		public  static  byte [] Library1Aar => library1Aar.Value;
 		public  static  byte [] Library2Aar => library2Aar.Value;
 		public  static  byte [] ApacheHttpClient_cs => apacheHttpClient_cs.Value;
+		public  static  byte [] JavadocCopyright => javadocCopyright.Value;
 
 		static byte[] GetResourceData (string name)
 		{

src/Xamarin.Android.Build.Tasks/Tests/Xamarin.Android.Build.Tests/Xamarin.Android.Build.Tests.csproj

@@ -61,6 +61,7 @@
     <EmbeddedResource Include="Resources\*">
       <LogicalName>%(FileName)%(Extension)</LogicalName>
     </EmbeddedResource>
+    <EmbeddedResource Include="$(XamarinAndroidSourcePath)\src\Mono.Android\javadoc-copyright.xml" LogicalName="javadoc-copyright.xml" />
   </ItemGroup>
 
 </Project>

src/Xamarin.Android.Build.Tasks/Tests/Xamarin.Android.Build.Tests/java/com/microsoft/android/test/msbuildtest/JavaSourceJarTest.java

@@ -6,7 +6,7 @@ public class JavaSourceJarTest
      * Returns greeting message.
      * <p>
      * Returns "Morning, ", "Hello, " or "Evening, " with name argument,
-     * depending on the argument hour.
+     * depending on the argument hour. Includes a {@docRoot}test.html element.
      * </p>
      * @param name name to display.
      * @param date time to determine the greeting message.