[generator] Add --with-javadoc-xml=FILE support.

Commit 69e1b80 added `tools/java-source-utils`, which can parse Java
source code and extract Javadoc comments into an XML file:

	$ java -jar "java-source-utils.jar" -v \
		$HOME/android-toolchain/sdk/platforms/android-29/android.jar \
		--output-javadoc=android-javadoc.xml

What can we *do* with the generated `android-javadoc.xml`?

`android-javadoc.xml` contains parameter names, and thus can be used
with `class-parse --docspath`; see commit 806082f.

What we *really* want to do is make the Javadoc information *useful*
to consumers of the binding assembly.  This means that we want a
C# XML Documentation file for the binding assembly.

The most straightforward way to get a C# XML Documentation File is to
emit [C# XML Documentation Comments][0] into the binding source code!

Add a new `generator --with-javadoc-xml=FILE` option.  When specified,
`FILE` will be treated as an XML file containing the output from
`java-source-utils.jar --output-javadoc` (see 69e1b80)`, and all
`<javadoc/>` elements within the XML file will be associated with C#
types and members to emit, based on the `//@jni-signature` and
`//@name` attributes, as appropriate.

When the bindings are written to disk, the Javadoc comments will be
translated to C# XML Documentation comments, in a "best effort" basis.
(THIS WILL BE INCOMPLETE.)

TODO: For "demonstration" purposes, the C# XML Doc comments are simply
a `<format type="text/html"/>` block containing the XML-ized Javadoc
HTML.  This should be improved to mirror javadoc-to-mdoc before merge.

[0]: https://docs.microsoft.com/en-us/dotnet/csharp/codedoc

Author: jonpryor

tools/generator/CodeGenerator.cs

@@ -3,6 +3,7 @@
 using System.IO;
 using System.Linq;
 using System.Xml;
+using System.Xml.Linq;
 using Mono.Cecil;
 using MonoDroid.Generation;
 using Xamarin.AndroidTools.AnnotationSupport;
@@ -178,6 +179,7 @@ static void Run (CodeGeneratorOptions options, DirectoryAssemblyResolver resolve
 			SealedProtectedFixups.Fixup (gens);
 
 			GenerateAnnotationAttributes (gens, annotations_zips);
+			AddJavadoc (gens, options.JavadocXmlFiles);
 
 			//SymbolTable.Dump ();
 
@@ -356,6 +358,78 @@ static void GenerateAnnotationAttributes (List<GenBase> gens, IEnumerable<string
 			}
 		}
 
+		static void AddJavadoc (List<GenBase> gens, IList<string> javadocXmlFiles)
+		{
+			if (javadocXmlFiles == null)
+				return;
+			foreach (var path in javadocXmlFiles) {
+				if (!File.Exists (path))
+					continue;
+
+				XDocument doc = XDocument.Load (path);
+
+				foreach (var type in gens) {
+					AddJavadoc (type, doc);
+				}
+			}
+		}
+
+		static void AddJavadoc (GenBase type, XDocument javadoc)
+		{
+			var typeJavadoc = javadoc.Elements ("api")
+				.Elements ("package")
+				.Where (p => type.PackageName == (string) p.Attribute ("name"))
+				.Elements ()
+				.Where (e => type.JniName == (string) e.Attribute ("jni-signature"))
+				.FirstOrDefault ();
+			if (typeJavadoc == null)
+				return;
+
+			if (string.IsNullOrEmpty (type.Javadoc))
+				type.Javadoc    = typeJavadoc.Element ("javadoc")?.Value;
+
+			foreach (var method in type.Methods) {
+				if (!string.IsNullOrEmpty (method.Javadoc))
+					continue;
+				var methodJavadoc = typeJavadoc
+					.Elements ("method")
+					.Where (m => method.JavaName == (string) m.Attribute ("name") && method.JniSignature == (string) m.Attribute ("jni-signature"))
+					.Elements ("javadoc")
+					.FirstOrDefault ();
+				if (methodJavadoc == null)
+					continue;
+				method.Javadoc    = methodJavadoc.Value;
+			}
+
+			foreach (var field in type.Fields) {
+				if (!string.IsNullOrEmpty (field.Javadoc))
+					continue;
+				var fieldJavadoc = typeJavadoc
+					.Elements ("field")
+					.Where (m => field.JavaName == (string) m.Attribute ("name") && field.JniSignature == (string) m.Attribute ("jni-signature"))
+					.Elements ("javadoc")
+					.FirstOrDefault ();
+				if (fieldJavadoc == null)
+					continue;
+				field.Javadoc       = fieldJavadoc.Value;
+			}
+
+			if (type is ClassGen @class) {
+				foreach (var ctor in @class.Ctors) {
+					if (!string.IsNullOrEmpty (ctor.Javadoc))
+						continue;
+					var ctorJavadoc = typeJavadoc
+						.Elements ("constructor")
+						.Where (c => ctor.JniSignature == (string) c.Attribute ("jni-signature"))
+						.Elements ("javadoc")
+						.FirstOrDefault ();
+					if (ctorJavadoc == null)
+						continue;
+					ctor.Javadoc    = ctorJavadoc.Value;
+				}
+			}
+		}
+
 		static void AddAnnotationTo (AnnotatedItem item, string annotation)
 		{
 			if (item.ManagedInfo.PropertyObject != null)

tools/generator/CodeGeneratorOptions.cs

@@ -15,6 +15,7 @@ public CodeGeneratorOptions ()
 			FixupFiles          = new Collection<string> ();
 			LibraryPaths        = new Collection<string> ();
 			AnnotationsZipFiles = new Collection<string> ();
+			JavadocXmlFiles     = new Collection<string> ();
 		}
 
 		public string               ApiLevel {get; set;}
@@ -24,6 +25,7 @@ public CodeGeneratorOptions ()
 		public Collection<string>   AssemblyReferences {get; private set;}
 		public Collection<string>   FixupFiles {get; private set;}
 		public Collection<string>   LibraryPaths {get; private set;}
+		public Collection<string>   JavadocXmlFiles {get; private set;}
 		public bool                 GlobalTypeNames {get; set;}
 		public bool                 OnlyBindPublicTypes {get; set;}
 		public string               ApiDescriptionFile {get; set;}
@@ -118,6 +120,9 @@ public static CodeGeneratorOptions Parse (string[] args)
 				{ "only-xml-adjuster",
 					"Run only API XML adjuster for class-parse input.",
 					v => opts.OnlyRunApiXmlAdjuster = v != null },
+				{ "with-javadoc-xml=",
+					"{PATH} to `api.xml` containing Javadoc docs in `<javadoc/>` elements",
+					v => opts.JavadocXmlFiles.Add (v) },
 				{ "xml-adjuster-output=",
 					"specify API XML adjuster output XML for class-parse input.",
 					v => opts.ApiXmlAdjusterOutput = v },

tools/generator/Java.Interop.Tools.Generator.CodeGeneration/CodeGenerator.cs

@@ -67,6 +67,8 @@ public void WriteClass (ClassGen @class, string indent, GenerationInfo gen_info)
 				obj_type = gs != null && gs.IsConcrete ? gs.GetGenericType (null) : opt.GetOutputName (@class.base_symbol.FullName);
 			}
 
+			Javadoc.WriteJavadocs (writer, indent, @class.Javadoc);
+
 			writer.WriteLine ("{0}// Metadata.xml XPath class reference: path=\"{1}\"", indent, @class.MetadataXPathReference);
 
 			if (@class.IsDeprecated)
@@ -412,6 +414,8 @@ public bool WriteFields (List<Field> fields, string indent, GenBase gen, HashSet
 
 		internal virtual void WriteField (Field field, string indent, GenBase type)
 		{
+			Javadoc.WriteJavadocs (writer, indent, field.Javadoc);
+
 			if (field.IsEnumified)
 				writer.WriteLine ("[global::Android.Runtime.GeneratedEnum]");
 			if (field.NeedsProperty) {
@@ -520,6 +524,8 @@ public void WriteInterfaceDeclaration (InterfaceGen @interface, string indent, G
 				sb.Append (opt.GetOutputName (isym.FullName));
 			}
 
+			Javadoc.WriteJavadocs (writer, indent, @interface.Javadoc);
+
 			writer.WriteLine ("{0}// Metadata.xml XPath interface reference: path=\"{1}\"", indent, @interface.MetadataXPathReference);
 
 			if (@interface.IsDeprecated)
@@ -1436,6 +1442,7 @@ public void WriteMethod (Method method, string indent, GenBase type, bool genera
 			}
 			string ret = opt.GetTypeReferenceName (method.RetVal);
 			WriteMethodIdField (method, indent);
+			Javadoc.WriteJavadocs (writer, indent, method.Javadoc);
 			if (method.DeclaringType.IsGeneratable)
 				writer.WriteLine ("{0}// Metadata.xml XPath method reference: path=\"{1}\"", indent, method.GetMetadataXPathReference (method.DeclaringType));
 			if (method.Deprecated != null)

tools/generator/Java.Interop.Tools.Generator.Importers/XmlApiImporter.cs

@@ -109,6 +109,7 @@ public static Field CreateField (GenBase declaringType, XElement elem)
 				IsFinal = elem.XGetAttribute ("final") == "true",
 				IsStatic = elem.XGetAttribute ("static") == "true",
 				JavaName = elem.XGetAttribute ("name"),
+				JniSignature = elem.XGetAttribute ("jni-signature"),
 				NotNull = elem.XGetAttribute ("not-null") == "true",
 				SetterParameter = CreateParameter (elem),
 				TypeName = elem.XGetAttribute ("type"),

tools/generator/Java.Interop.Tools.Generator.ObjectModel/Field.cs

@@ -24,6 +24,9 @@ public class Field : ApiVersionsSupport.IApiAvailability
 		public string TypeName { get; set; }
 		public string Value { get; set; }
 		public string Visibility { get; set; }
+		public string JniSignature { get; set; }
+
+		public string Javadoc { get; set; }
 
 		internal string GetMethodPrefix => TypeNameUtilities.GetCallPrefix (Symbol);
 

tools/generator/Java.Interop.Tools.Generator.ObjectModel/GenBase.cs

@@ -35,6 +35,8 @@ protected GenBase (GenBaseSupport support)
 
 		public string ReturnCast => string.Empty;
 
+		public string Javadoc { get; set; }
+
 		// This means Ctors/Methods/Properties/Fields has not been populated yet.
 		// If this type is retrieved from the SymbolTable, it will call PopulateAction
 		// to fill in members before returning it to the user.

tools/generator/Java.Interop.Tools.Generator.ObjectModel/Javadoc.cs

@@ -0,0 +1,79 @@
+using System;
+using System.Collections.Generic;
+using System.IO;
+
+using HtmlAgilityPack;
+
+namespace MonoDroid.Generation
+{
+	public static class Javadoc {
+
+		public static void WriteJavadocs (TextWriter writer, string indent, string javadoc)
+		{
+			if (javadoc == null || string.IsNullOrWhiteSpace (javadoc))
+				return;
+
+			javadoc         = javadoc.Trim ();
+
+			WriteSummary (writer, indent, javadoc);
+			WriteRemarks (writer, indent, javadoc);
+		}
+
+		static void WriteSummary (TextWriter writer, string indent, string javadoc)
+		{
+			var summary     = javadoc;
+			int dotIndex    = javadoc.IndexOf ('.');
+			if (dotIndex > 0) {
+				summary = javadoc.Substring (0, dotIndex+1);
+			}
+
+			writer.WriteLine ($"{indent}/// <summary>");
+			using var r = new StringReader (summary);
+			string line;
+			while ((line = r.ReadLine ()) != null) {
+				writer.WriteLine ($"{indent}///   {line}");
+			}
+			writer.WriteLine ($"{indent}/// </summary>");
+		}
+
+		static void WriteRemarks (TextWriter writer, string indent, string javadoc)
+		{
+			// TODO: better translate HTML to C# XML Doc Comments
+			string javadocXml = null;
+
+			try {
+				var doc = new HtmlDocument() {
+					OptionAutoCloseOnEnd    = true,
+					OptionFixNestedTags     = true,
+					OptionOutputAsXml       = true,
+				};
+				doc.LoadHtml (javadoc);
+
+				var javadocXmlOutput    = new StringWriter ();
+				doc.Save (javadocXmlOutput);
+
+				javadocXml = javadocXmlOutput.ToString ();
+			}
+			catch (Exception e) {
+				Console.Error.WriteLine ("## Unable to translate remarks:");
+				Console.Error.WriteLine (e.ToString ());
+				Console.Error.WriteLine (javadoc);
+				Console.Error.WriteLine ();
+				return;
+			}
+
+			var lines = new StringReader (javadocXml);
+
+			writer.WriteLine ($"{indent}/// <remarks>");
+			writer.WriteLine ($"{indent}///   <format type=\"text/html\">");
+
+			string line;
+			while ((line = lines.ReadLine ()) != null) {
+				writer.WriteLine ($"{indent}///     {line}");
+			}
+
+			writer.WriteLine ($"{indent}///   </format>");
+			writer.WriteLine ($"{indent}/// </remarks>");
+		}
+	}
+}

tools/generator/Java.Interop.Tools.Generator.ObjectModel/MethodBase.cs

@@ -24,6 +24,8 @@ protected MethodBase (GenBase declaringType)
 		public ParameterList Parameters { get; } = new ParameterList ();
 		public string Visibility { get; set; }
 
+		public string Javadoc { get; set; }
+
 		public string [] AutoDetectEnumifiedOverrideParameters (AncestorDescendantCache cache)
 		{
 			if (Parameters.All (p => p.Type != "int"))