[Xamarin.Android.Build.Tasks] Add @(JavaSourceJar) for Bindings (#1091)

`@(JavaSourceJar)` works like `@(JavaDocJar)`, but in slightly more
complicated way.

`@(JavaDocJar)` only extracts the `.jar` contents and passes
`index.html` as `@(JavaDocIndex)`, while `@(JavaSourceJar)` extracts
the `.jar`, then runs `javadoc` to generate JavaDoc documentation,
then passes the generated `index.html` as `@(JavaDocIndex)`.

This fix involves `@(JavaDocIndex)` path fixes that incorrectly
passed file name as directory name (regression from
[Java.Interop/806082f][ji-80]), as well as `javadoc-to-mdoc` fix to
not try to substring beyond string length within `HtmlLoader` to
detect documentation type.

[ji-80]: https://github.com/xamarin/Java.Interop/commit/806082f

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

@@ -0,0 +1,61 @@
+using System;
+using System.Linq;
+using System.IO;
+using Microsoft.Build.Framework;
+using Microsoft.Build.Utilities;
+using System.Text;
+using System.Collections.Generic;
+using Xamarin.Android.Tools;
+using Xamarin.Android.Tools.Aidl;
+
+namespace Xamarin.Android.Tasks
+{
+
+	public class JavaDoc : JavaToolTask
+	{
+		public string [] SourceDirectories { get; set; }
+
+		public string [] DestinationDirectories { get; set; }
+
+		protected override string ToolName {
+			get { return OS.IsWindows ? "javadoc.exe" : "javadoc"; }
+		}
+
+		public override bool Execute ()
+		{
+			Log.LogDebugMessage ("JavaDoc Task");
+			Log.LogDebugTaskItems ("  SourceDirectories: ", SourceDirectories);
+			Log.LogDebugTaskItems ("  DestinationDirectories: ", DestinationDirectories);
+
+			foreach (var dir in DestinationDirectories)
+				if (!Directory.Exists (dir))
+					Directory.CreateDirectory (dir);
+
+			bool retval = true;
+			foreach (var pair in SourceDirectories.Zip (DestinationDirectories, (src, dst) => new { Source = src, Destination = dst })) {
+				context_src = pair.Source;
+				context_dst = pair.Destination;
+				retval &= base.Execute ();
+			}
+			return retval;
+		}
+
+		string context_src;
+		string context_dst;
+
+		protected override string GenerateCommandLineCommands ()
+		{
+			var cmd = new CommandLineBuilder ();
+
+			cmd.AppendSwitch ("-d");
+			cmd.AppendFileNameIfNotNull (context_dst);
+			cmd.AppendSwitch ("-sourcepath");
+			cmd.AppendFileNameIfNotNull (context_src);
+			cmd.AppendSwitch ("-subpackages");
+			cmd.AppendSwitch (".");
+
+			return cmd.ToString ();
+		}
+	}
+	
+}

src/Xamarin.Android.Build.Tasks/Tests/Xamarin.Android.Build.Tests/BindingBuildTest.cs

@@ -1,15 +1,13 @@
-using System;
+using System;
 using Xamarin.ProjectTools;
 using NUnit.Framework;
 using System.IO;
 using System.Linq;
 using System.Collections.Generic;
 
-namespace Xamarin.Android.Build.Tests
+namespace Xamarin.Android.Build.Tests {
-{
 	[Parallelizable (ParallelScope.Children)]
-	public class BindingBuildTest : BaseTest
+	public class BindingBuildTest : BaseTest {
-	{
 #pragma warning disable 414
 		static object [] ClassParseOptions = new object [] {
 			new object[] {
@@ -388,5 +386,65 @@ namespace Foo {
 				Assert.IsTrue (bindingBuilder.Build (binding), "binding build should have succeeded");
 			}
 		}
+
+		[Test]
+		public void JavaSourceJar ()
+		{
+#if false // Java source with javadoc
+			package com.xamarin.android.test.msbuildtest;
+
+public class JavaSourceJarTest
+{
+    /**
+     * Returns greeting message.
+     * <p>
+     * Returns "Morning, ", "Hello, " or "Evening, " with name argument,
+     * depending on the argument hour.
+     * </p>
+     * @param name name to display.
+     * @param date time to determine the greeting message.
+     * @return the resulting message.
+     */
+    public String greet (String name, java.util.Date date)
+    {
+        String head = date.getHours () < 11 ? "Morning, " :
+            date.getHours () < 17 ? "Hello, " : "Evening, ";
+        return head + name;
+    }
+}
+#endif
+			var binding = new XamarinAndroidBindingProject () {
+				AndroidClassParser = "class-parse",
+			};
+			binding.SetProperty ("DocumentationFile", "UnnamedProject.xml");
+			string sourcesJarBase64 = @"UEsDBBQACAgIAC2gP0wAAAAAAAAAAAAAAAAJAAQATUVUQS1JTkYv/soAAAMAUEsHCAAAAAACAAAAAAAAAFBLAwQUAAgICAAtoD9MAAAAAAAAAAAAAAAAFAAAAE1FVEEtSU5GL01BTklGRVNULk1G803My0xLLS7RDUstKs7Mz7NSMNQz4OVyLkpNLElN0XWqBAlY6BnEG5oaKmj4FyUm56QqOOcXFeQXJZYA1WvycvFyAQBQSwcIlldz8EQAAABFAAAAUEsDBBQACAgIACqgP0wAAAAAAAAAAAAAAAA7AAAAY29tL3hhbWFyaW4vYW5kcm9pZC90ZXN0L21zYnVpbGR0ZXN0L0phdmFTb3VyY2VKYXJUZXN0LmphdmF1kc1uwjAMx+99CosTsCqI0yRgG4dNQki7jL2Aaaw2Wz4qJ2WbJt59SSgfQsyq4kb+2X/babH6xJqgckZ8o0FWVqCV7JQUgXwQxm87pWX6nxdF2221qqDS6D2scYcb13FFa+T3CBS/BUSbjMfZwxjeKHRsPdRMFJStwZD3UU8cgUX7eM0OXh3byJYwiN+KtHbRg2MYvOyoj8CXCg1YNATIdWfIhvJYSFJLViY1ZyE0ZwKa2O1ZenLWXrbIaA718hEcSOVbjT/iipEYYlj1DAVioyxlnX+nXHKeLUNMvtO3qEn2/YY3gROSK8Kwv6XOSviIaxddUFo8p1ZSP6Oceth+sp5vCCU8ZELUFFZxeg/DESxgOoWny0XD7JSb7FbGfco4vcbs8jHmp+R+zix8l/s9xPbFvvgDUEsHCDlC8jY2AQAAawIAAFBLAQIUABQACAgIAC2gP0wAAAAAAgAAAAAAAAAJAAQAAAAAAAAAAAAAAAAAAABNRVRBLUlORi/+ygAAUEsBAhQAFAAICAgALaA/TJZXc/BEAAAARQAAABQAAAAAAAAAAAAAAAAAPQAAAE1FVEEtSU5GL01BTklGRVNULk1GUEsBAhQAFAAICAgAKqA/TDlC8jY2AQAAawIAADsAAAAAAAAAAAAAAAAAwwAAAGNvbS94YW1hcmluL2FuZHJvaWQvdGVzdC9tc2J1aWxkdGVzdC9KYXZhU291cmNlSmFyVGVzdC5qYXZhUEsFBgAAAAADAAMA5gAAAGICAAAAAA==";
+			string classesjarBase64 = @"
+UEsDBBQACAgIAO+EP0wAAAAAAAAAAAAAAAAJAAQATUVUQS1JTkYv/soAAAMAUEsHCAAAAAACAAAAAAAAAFBLAwQUAAgIC
+ADvhD9MAAAAAAAAAAAAAAAAFAAAAE1FVEEtSU5GL01BTklGRVNULk1G803My0xLLS7RDUstKs7Mz7NSMNQz4OVyLkpNLE
+lN0XWqBAlY6BnEG5oaKmj4FyUm56QqOOcXFeQXJZYA1WvycvFyAQBQSwcIlldz8EQAAABFAAAAUEsDBBQACAgIALOEP0w
+AAAAAAAAAAAAAAAA8AAAAY29tL3hhbWFyaW4vYW5kcm9pZC90ZXN0L21zYnVpbGR0ZXN0L0phdmFTb3VyY2VKYXJUZXN0
+LmNsYXNzbVHZSsNAFD1j2yStaW3rvlvX1i0g4osiuKLi8lARfHPaDCWaJiWdit/ji6/6UkHBD/CjxDupIloDucuZO+fMn
+Hn/eHkDsIpCAp3oS6AfAwYGDQwZGNYxkoCmUA2jKozpGNcxwaBtOJ4jNxki+cIFQ3THtwVD17HjidNGtSSCc15yCYlVAi
+Ekw1r++JrfcsvlXsUqysDxKustpCEd19rlUqwX2kcYkkXJyzcnvBYS6sgxJIp+IyiLfUcJ9B3RnhZwxINzUZfLisWEiaS
+OSRNTmGaIn/iBR4SLdHT9QLiur6r43q34Rvv/am83HNcWgYkZzJqYQ54uUfar1h2vclq3uGcHvmNbkiStar2kxsO67UAM
+6R/ys9K1KP+GWnoMqd9+MBgVIQ+IqR7afEiu81pNeDbD0j92ttv3dQVy0ZD+t0pP/h+fkYN6fvV1gCnvKKaoG6XMKMfmn
+8GeqKBHpqiFYIRiGpmv0SvaGqW8sthER7rzHkY28oDusMuoLvqAWDZ2+grt8hn6UhPGAv1NxB9DWcWbIk4QYxeyGEc3Rc
+BAJJXc0qmjw4eTvZ9QSwcINzBZxakBAAC1AgAAUEsBAhQAFAAICAgA74Q/TAAAAAACAAAAAAAAAAkABAAAAAAAAAAAAAA
+AAAAAAE1FVEEtSU5GL/7KAABQSwECFAAUAAgICADvhD9Mlldz8EQAAABFAAAAFAAAAAAAAAAAAAAAAAA9AAAATUVUQS1J
+TkYvTUFOSUZFU1QuTUZQSwECFAAUAAgICACzhD9MNzBZxakBAAC1AgAAPAAAAAAAAAAAAAAAAADDAAAAY29tL3hhbWFya
+W4vYW5kcm9pZC90ZXN0L21zYnVpbGR0ZXN0L0phdmFTb3VyY2VKYXJUZXN0LmNsYXNzUEsFBgAAAAADAAMA5wAAANYCAA
+AAAA==";
+			using (var bindingBuilder = CreateDllBuilder ("temp/JavaSourceJar", false, false)) {
+				binding.Jars.Add (new AndroidItem.EmbeddedJar ("javasourcejartest.jar") {
+					BinaryContent = () => Convert.FromBase64String (classesjarBase64)
+				});
+				binding.OtherBuildItems.Add (new BuildItem ("JavaSourceJar", "javasourcejartest-sources.jar") {
+					BinaryContent = () => Convert.FromBase64String (sourcesJarBase64)
+				});
+				bindingBuilder.Build (binding);
+				string xml = Path.Combine (bindingBuilder.Output.GetIntermediaryAsText ("docs/Com.Xamarin.Android.Test.Msbuildtest/JavaSourceJarTest.xml"));
+				Assert.IsTrue (xml.Contains ("<param name=\"name\"> - name to display.</param>"), "missing doc");
+			}
+		}
 	}
 }

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

@@ -24,6 +24,7 @@ Copyright (C) 2012 Xamarin Inc. All rights reserved.
   <UsingTask TaskName="Xamarin.Android.Tasks.CreateLibraryResourceArchive" AssemblyFile="Xamarin.Android.Build.Tasks.dll" />
   <UsingTask TaskName="Xamarin.Android.Tasks.CreateTemporaryDirectory" AssemblyFile="Xamarin.Android.Build.Tasks.dll" />
   <UsingTask TaskName="Xamarin.Android.Tasks.GetAdditionalResourcesFromAssemblies" AssemblyFile="Xamarin.Android.Build.Tasks.dll" />
+  <UsingTask TaskName="Xamarin.Android.Tasks.JavaDoc" AssemblyFile="Xamarin.Android.Build.Tasks.dll" />
   <UsingTask TaskName="Xamarin.Android.Tasks.ReadAdditionalResourcesFromAssemblyCache" AssemblyFile="Xamarin.Android.Build.Tasks.dll" />
   <UsingTask TaskName="Xamarin.Android.Tasks.RemoveDirFixed" AssemblyFile="Xamarin.Android.Build.Tasks.dll" />
   <UsingTask TaskName="Xamarin.Android.Tasks.ResolveAssemblies" AssemblyFile="Xamarin.Android.Build.Tasks.dll" />
@@ -78,6 +79,7 @@ Copyright (C) 2012 Xamarin Inc. All rights reserved.
     <AvailableItemName Include="LibraryProjectZip" />
     <AvailableItemName Include="JavaDocIndex" />
     <AvailableItemName Include="JavaDocJar" />
+    <AvailableItemName Include="JavaSourceJar" />
   </ItemGroup>
 
   <Import Project="$(MSBuildBinPath)\Microsoft.CSharp.Targets" />
@@ -238,6 +240,12 @@ Copyright (C) 2012 Xamarin Inc. All rights reserved.
         Condition="!HasTrailingSlash('$(_JavaSdkDirectory)')" />
     </CreateProperty>
 
+	<CreateProperty Value="$(_JavaSdkDirectory)\bin">
+		<Output TaskParameter="Value" PropertyName="JavaToolPath"
+				Condition="'$(JavaToolPath)' == ''"
+		/>
+	</CreateProperty>
+
     <Message Text="MonoAndroid Tools: $(_MonoAndroidToolsDirectory)"/>
     <Message Text="Android NDK: $(_AndroidNdkDirectory)"/>
     <Message Text="Android SDK: $(_AndroidSdkDirectory)"/>
@@ -342,6 +350,7 @@ Copyright (C) 2012 Xamarin Inc. All rights reserved.
 		;_ExtractLibraryProjectImports
 		;_GetLibraryImports
 		;_ExtractJavaDocJars
+		;_GenerateJavaDocFromSourceJars
 	</ExportJarToXmlDependsOnTargets>
 </PropertyGroup>
 
@@ -359,6 +368,27 @@ Copyright (C) 2012 Xamarin Inc. All rights reserved.
 		
   </Target>
 
+  <Target Name="_GenerateJavaDocFromSourceJars"
+		Inputs="@(JavaSourceJar)"
+		Outputs="@(JavaSourceJar->'$(IntermediateOutputPath)javadocs\%(FileName).stamp')"
+		>
+		
+    <Unzip Sources="@(JavaSourceJar)" DestinationDirectories="@(JavaSourceJar->'$(IntermediateOutputPath)javasources\%(FileName)')" />
+	
+    <JavaDoc
+        ToolPath="$(JavaToolPath)"
+        SourceDirectories="@(JavaSourceJar->'$(IntermediateOutputPath)javasources\%(FileName)')"
+        DestinationDirectories="@(JavaSourceJar->'$(IntermediateOutputPath)javadocs\%(FileName)')"
+        />
+	
+    <Touch Files="@(JavaSourceJar->'$(IntermediateOutputPath)javasources\%(FileName).stamp')" AlwaysCreate="True" />
+		
+    <CreateItem Include="@(JavaSourceJar->'$(IntermediateOutputPath)javadocs\%(FileName)\index.html')">
+      <Output TaskParameter="Include" ItemName="JavaDocIndex" />
+    </CreateItem>
+		
+  </Target>
+
   <Target Name="ExportJarToXml"
           DependsOnTargets="$(ExportJarToXmlDependsOnTargets)"
           Inputs="@(EmbeddedJar);@(EmbeddedReferenceJar);@(InputJar);@(ReferenceJar);$(MSBuildAllProjects);@(_AdditionalJavaLibraryReferences)"
@@ -369,7 +399,7 @@ Copyright (C) 2012 Xamarin Inc. All rights reserved.
     </CreateItem>
 
     <ItemGroup>
-      <_AndroidDocumentationPath Include="@(JavaDocIndex)" />
+      <_AndroidDocumentationPath Include="@(JavaDocIndex->'%(RootDir)\%(Directory)')" />
       <_AndroidDocumentationPath Include="$(JavaDocPaths)" />
       <_AndroidDocumentationPath Include="$(Java7DocPaths)" />
       <_AndroidDocumentationPath Include="$(Java8DocPaths)" />
@@ -553,6 +583,8 @@ Copyright (C) 2012 Xamarin Inc. All rights reserved.
     <RemoveDirFixed Directories="$(IntermediateOutputPath)docs" Condition="Exists ('$(IntermediateOutputPath)docs')" />
 
     <RemoveDirFixed Directories="$(IntermediateOutputPath)javadocs" Condition="Exists ('$(IntermediateOutputPath)javadocs')" />
+
+    <RemoveDirFixed Directories="$(IntermediateOutputPath)javasources" Condition="Exists ('$(IntermediateOutputPath)javasources')" />
   </Target>
   
   <Target Name="CleanLibraryProjectIntermediaries">

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

@@ -495,6 +495,7 @@
       <Link>desugar_deploy.jar</Link>
       <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
     </None>
+    <Compile Include="Tasks\JavaDoc.cs" />
   </ItemGroup>
   <ItemGroup>
     <_MonoAndroidEnum Include="$(AndroidGeneratedClassDirectory)\Android.Content.PM.LaunchMode.cs" />

src/Xamarin.Android.Tools.JavadocImporter/HtmlLoader.cs

@@ -111,13 +111,13 @@ namespace Xamarin.Android.Tools.JavaDocToMdoc
 		{
 			kind = JavaDocKind.DroidDoc;
 			string rawHTML = ReadHtmlFile (path);
-			if (rawHTML.Substring (0, 5000).IndexOf ("<body class=\"gc-documentation develop reference api ", StringComparison.Ordinal) > 0)
+			if (rawHTML.Substring (0, Math.Min (rawHTML.Length, 5000)).IndexOf ("<body class=\"gc-documentation develop reference api ", StringComparison.Ordinal) > 0)
 				kind = JavaDocKind.DroidDoc2;
-			if (rawHTML.Substring (0, 500).IndexOf ("Generated by javadoc (build 1.6", StringComparison.Ordinal) > 0)
+			if (rawHTML.Substring (0, Math.Min (rawHTML.Length, 500)).IndexOf ("Generated by javadoc (build 1.6", StringComparison.Ordinal) > 0)
 				kind = JavaDocKind.Java6;
-			if (rawHTML.Substring (0, 500).IndexOf ("Generated by javadoc (version 1.7", StringComparison.Ordinal) > 0)
+			if (rawHTML.Substring (0, Math.Min (rawHTML.Length, 500)).IndexOf ("Generated by javadoc (version 1.7", StringComparison.Ordinal) > 0)
 				kind = JavaDocKind.Java7;
-			if (rawHTML.Substring (0, 500).IndexOf ("Generated by javadoc (1.8", StringComparison.Ordinal) > 0)
+			if (rawHTML.Substring (0, Math.Min (rawHTML.Length, 500)).IndexOf ("Generated by javadoc (1.8", StringComparison.Ordinal) > 0)
 				kind = JavaDocKind.Java8;
 			if (kind == JavaDocKind.DroidDoc) {
 				throw new NotSupportedException ("Old DroidDoc is not supported anymore.");