[java-source-utils] Properly represent unresolved types (#758)

Context: #687 (comment)

Commit 69e1b80 stated:

> We don't want to *require* that everything be resolvable -- it's painful, and
> possibly impossible, e.g. w/ internal types -- so instead we should "demark"
> the unresolvable types.
>
> `.params.txt` output will use `.*` as a type prefix, e.g.
>
>     method(.*UnresolvableType foo, int bar);
>
> `docs.xml` will output `L.*UnresolvableType;`.

…except this didn't actually happen:
`java-source.utils.jar --output-javadoc` didn't have an `L` prefix
and `;` suffix for the JNI type representation.  Additionally, it
would include generic type parameters!

Thus, a declaration such as:

	static UnknownType<String, Integer> method(AnotherUnknownType<Class> p);

would result in:

	<method name="method" jni-return=".*UnknownType&lt;String, Integer&gt;" jni-signature="(.*AnotherUnknownType&lt;Class&gt;).*UnkonwnType&lt;String, Integer&gt;">

which was not at all intended, and causes subsequent issued in PR #687
as the JNI signature parser would break when encountering `.`.

Update `java-source-utils.jar` & `//*/@jni-signature` so that
[unresolved types are properly represented][0]: `//*/@jni-type` and
`//*/@jni-signature` shouldn't contain generic type parameters, and
should also (somewhat) "conform" to JNI convention, with a leading `L`
and trailing `;`, emitting:

	<method name="method" jni-return="L.*UnknownType;" jni-signature="(L.*AnotherUnknownType;)L.*UnknownType;">

Additionally, update `JavaType.java` to cause it to have "orphaned"
Javadoc comments; this change was forgotten in c1bc5c8.

[0]: #687 (comment)

Author: jonpryor

tests/Xamarin.Android.Tools.Bytecode-Tests/java/com/xamarin/JavaType.java

@@ -6,6 +6,7 @@
 /**
  * JNI sig: Lcom/xamarin/JavaEnum;
  */
+// Disconnective comment?
 enum JavaEnum {
 	/** FIRST; JNI sig: Lcom/xamarin/JavaEnum; */
 	FIRST,
@@ -161,6 +162,7 @@ public int compareTo (JavaType<E> value) {
 	}
 
 	/** JNI sig: func.(Ljava/lang/StringBuilder;)Ljava/util/List; */
+	// Comment to "disconnect" Javadoc from the member
 	public List<String> func (StringBuilder value) {
 		return null;
 	}

tools/java-source-utils/src/main/java/com/microsoft/android/JniPackagesInfoFactory.java

@@ -361,7 +361,7 @@ static String getJavaType(JniTypeInfo typeInfo, JniMethodInfo methodInfo, Type t
 			final ResolvedType rt = type.resolve();
 			return rt.describe();
 		} catch (final Throwable thr) {
-			return ".*" + type.asString();
+			return getUnresolvedJavaType(type);
 		}
 	}
 
@@ -389,7 +389,8 @@ static String getJniType(JniTypeInfo typeInfo, JniMethodInfo methodInfo, Type ty
 		}
 		catch (final Exception thr) {
 		}
-		return ".*" + type.asString();
+
+		return getUnresolvedJniType(type);
 	}
 
 	static String getJniType(JniTypeInfo typeInfo, JniMethodInfo methodInfo, ArrayType type) {
@@ -412,7 +413,7 @@ static String getPrimitiveJniType(String javaType) {
 			case "short":   return "S";
 			case "void":    return "V";
 		}
-		throw new Error("Don't know JNI type for `" + javaType + "`!");
+		throw new Error("Don't know JNI type for primitive type `" + javaType + "`!");
 	}
 
 	static String getJniType(ResolvedType type) {
@@ -453,4 +454,42 @@ static String getJniType(ResolvedReferenceType type) {
 		name.append(";");
 		return name.toString();
 	}
+
+	static String getUnresolvedJavaType(Type type) {
+		final   StringBuilder   jniType     = new StringBuilder();
+
+		jniType.append(".*");
+
+		if (type.isClassOrInterfaceType()) {
+			// Special-case class-or-interface declarations so that we skip type parameters.
+			type.ifClassOrInterfaceType(c -> {
+				c.getScope().ifPresent(s -> jniType.append(s.asString()).append("."));
+				jniType.append(c.getName().asString());
+			});
+		} else {
+			jniType.append(type.asString());
+		}
+
+		return jniType.toString();
+	}
+
+	static String getUnresolvedJniType(Type type) {
+		final   StringBuilder   jniType     = new StringBuilder();
+
+		jniType.append("L.*");
+
+		if (type.isClassOrInterfaceType()) {
+			// Special-case class-or-interface declarations so that we skip type parameters.
+			type.ifClassOrInterfaceType(c -> {
+				c.getScope().ifPresent(s -> jniType.append(s.asString()).append("."));
+				jniType.append(c.getName().asString());
+			});
+		} else {
+			jniType.append(type.asString());
+		}
+
+		jniType.append(";");
+
+		return jniType.toString();
+	}
 }

tools/java-source-utils/src/test/java/com/microsoft/android/JavadocXmlGeneratorTest.java

@@ -109,6 +109,11 @@ public void testWritePackages_JavaType_java() throws Throwable {
 		testWritePackages("../../../com/xamarin/JavaType.java", "JavaType.xml");
 	}
 
+	@Test
+	public void testWritePackages_UnresolvedTypes_txt() throws Throwable {
+		testWritePackages("../../../UnresolvedTypes.txt", "../../../UnresolvedTypes.xml");
+	}
+
 	private static void testWritePackages(final String resourceJava, final String resourceXml) throws Throwable {
 		final   JavaParser              parser          = JniPackagesInfoFactoryTest.createParser();
 		final   JniPackagesInfoFactory  factory         = new JniPackagesInfoFactory(parser);

tools/java-source-utils/src/test/resources/UnresolvedTypes.txt

@@ -0,0 +1,11 @@
+package example;
+
+public class UnresolvedTypes {
+	/**
+	 * Method using unresolvable types.  As such, we make do.
+	 *
+	 * JNI Sig: method.(L.*example.name.UnresolvedParameterType;)L.*UnresolvedReturnType;
+	 */
+	public static UnresolvedReturnType<String, Integer> method(example.name.UnresolvedParameterType<Class> parameter) {
+	}
+}

tools/java-source-utils/src/test/resources/UnresolvedTypes.xml

@@ -0,0 +1,13 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<api api-source="java-source-utils">
+  <package jni-name="example" name="example">
+    <class jni-signature="Lexample/UnresolvedTypes;" name="UnresolvedTypes">
+      <method jni-return="L.*UnresolvedReturnType;" jni-signature="(L.*example.name.UnresolvedParameterType;)L.*UnresolvedReturnType;" name="method" return=".*UnresolvedReturnType">
+        <parameter jni-type="L.*example.name.UnresolvedParameterType;" name="parameter" type=".*example.name.UnresolvedParameterType"/>
+        <javadoc><![CDATA[Method using unresolvable types.  As such, we make do.
+
+JNI Sig: method.(L.*example.name.UnresolvedParameterType;)L.*UnresolvedReturnType;]]></javadoc>
+      </method>
+    </class>
+  </package>
+</api>