[generator] Fix parameter string in ref doc links (#935)

Fixes: #931Fixes: #932
We have a handful of issues in the https://developer.android.com/
links that are generated for various type members with complex
parameters. Collections, varargs, and generics are some examples of
items that are not translated correctly when generating the parameter
portion of the reference documentation URL.
The XML generated by `java-source-utils` when processing
`android-stubs-src.jar` contains `<parameter/>` elements under all
methods. The `<parameter/>` elements contain attributes with
additional type data; for instance:
<method jni-return="Landroid/animation/ObjectAnimator;" jni-signature="(Ljava/lang/Object;Landroid/util/Property;Landroid/util/Property;Landroid/graphics/Path;)Landroid/animation/ObjectAnimator;" name="ofFloat" return="android.animation.ObjectAnimator">
<parameter jni-type="Ljava/lang/Object;" name="target" type="T"/>
<parameter jni-type="Landroid/util/Property;" name="xProperty" type="android.util.Property&lt;T, java.lang.Float&gt;"/>
<parameter jni-type="Landroid/util/Property;" name="yProperty" type="android.util.Property&lt;T, java.lang.Float&gt;"/>
<parameter jni-type="Landroid/graphics/Path;" name="path" type="android.graphics.Path"/>
<javadoc>
<![CDATA[Constructs and returns an ObjectAnimator that animates coordinates along a <code>Path</code>
using two properties. A <code>Path</code></> animation moves in two dimensions, animating
coordinates <code>(x, y)</code> together to follow the line. In this variation, the
coordinates are floats that are set to separate properties, <code>xProperty</code> and
<code>yProperty</code>.
@PARAM target The object whose properties are to be animated.
@PARAM xProperty The property for the x coordinate being animated.
@PARAM yProperty The property for the y coordinate being animated.
@PARAM path The <code>Path</code> to animate values along.
@return An ObjectAnimator object that is set up to animate along <code>path</code>.]]>
</javadoc>
</method>
Rather than processing the `//method/@jni-signature` attribute of the
method, use the `//method/parameter/@type` attribute values to create
more reliable type information for our reference documentation links.
With these changes in place, instead of e.g.
https://developer.android.com/reference/android/accounts/AccountManager#addAccount(java.lang.String,%20java.lang.String,%20java.lang.String[],%20android.os.Bundle,%20android.app.Activity,%20android.accounts.AccountManagerCallback,%20android.os.Handler)
which doesn't anchor to the intended method documentation, we now emit
https://developer.android.com/reference/android/accounts/AccountManager#addAccount(java.lang.String,%20java.lang.String,%20java.lang.String[],%20android.os.Bundle,%20android.app.Activity,%20android.accounts.AccountManagerCallback%3Candroid.os.Bundle%3E,%20android.os.Handler)
which *does* anchor to the intended method documentation.

Author: pjcollins

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

@@ -39,9 +39,9 @@ public static JavadocInfo CreateInfo (XElement element, XmldocStyle style, bool
 vardesc=GetMemberDescription(element);
 stringdeclaringJniType=desc.DeclaringJniType;
 stringdeclaringMemberName=desc.DeclaringMemberName;
-vardeclaringMemberJniSignature=desc.DeclaringMemberJniSignature;
+vardeclaringMemberParamString=desc.DeclaringMemberParameterString;
 
-varextras=GetExtra(element,style,declaringJniType,declaringMemberName,declaringMemberJniSignature,appendCopyrightExtra);
+varextras=GetExtra(element,style,declaringJniType,declaringMemberName,declaringMemberParamString,appendCopyrightExtra);
 XElement[]extra=extras.Extras;
 XElement[]copyright=extras.Copyright;
 
@@ -54,13 +54,13 @@ public static JavadocInfo CreateInfo (XElement element, XmldocStyle style, bool
 Javadoc=javadoc,
 MemberDescription=declaringMemberName==null
 ?declaringJniType
-:$"{declaringJniType}.{declaringMemberName}.{declaringMemberJniSignature}",
+:$"{declaringJniType}.{declaringMemberName}{declaringMemberParamString}",
 XmldocStyle=style,
 };
 returninfo;
 }
 
-static(stringDeclaringJniType,stringDeclaringMemberName,stringDeclaringMemberJniSignature)GetMemberDescription(XElementelement)
+static(stringDeclaringJniType,stringDeclaringMemberName,stringDeclaringMemberParameterString)GetMemberDescription(XElementelement)
 {
 boolisType=element.Name.LocalName=="class"||
 element.Name.LocalName=="interface";
@@ -76,14 +76,26 @@ public static JavadocInfo CreateInfo (XElement element, XmldocStyle style, bool
 stringdeclaringMemberName=isType
 ?null
 :(string)element.Attribute("name")??declaringJniType.Substring(declaringJniType.LastIndexOf('/')+1);
+
 stringdeclaringMemberJniSignature=isType
 ?null
 :(string)element.Attribute("jni-signature");
 
-return(declaringJniType,declaringMemberName,declaringMemberJniSignature);
+
+stringdeclaringMemberParameterString=null;
+if(!isType&&(declaringMemberJniSignature?.StartsWith("(",StringComparison.Ordinal)??false)){
+varparameterTypes=element.Elements("parameter")?.Select(e =>e.Attribute("type")?.Value)?.ToList();
+if(parameterTypes?.Any()??false){
+declaringMemberParameterString=$"({string.Join(", ",parameterTypes)})";
+}else{
+declaringMemberParameterString="()";
+}
+}
+
+return(declaringJniType,declaringMemberName,declaringMemberParameterString);
 }
 
-static(XElement[]Extras,XElement[]Copyright)GetExtra(XElementelement,XmldocStylestyle,stringdeclaringJniType,stringdeclaringMemberName,stringdeclaringMemberJniSignature,boolappendCopyrightExtra)
+static(XElement[]Extras,XElement[]Copyright)GetExtra(XElementelement,XmldocStylestyle,stringdeclaringJniType,stringdeclaringMemberName,stringdeclaringMemberParameterString,boolappendCopyrightExtra)
 {
 if(!style.HasFlag(XmldocStyle.IntelliSenseAndExtraRemarks))
 return(null,null);
@@ -107,7 +119,7 @@ public static JavadocInfo CreateInfo (XElement element, XmldocStyle style, bool
 
 XElementdocLink=null;
 if(!string.IsNullOrEmpty(urlPrefix)){
-docLink=CreateDocLinkUrl(kind,urlPrefix,declaringJniType,declaringMemberName,declaringMemberJniSignature);
+docLink=CreateDocLinkUrl(kind,urlPrefix,declaringJniType,declaringMemberName,declaringMemberParameterString);
 }
 extra=newList<XElement>();
 extra.Add(docLink);
@@ -217,26 +229,26 @@ static List<string> GetLines (string text)
 [ApiLinkStyle.DeveloperAndroidComReference_2020Nov]=CreateAndroidDocLinkUri,
 };
 
-staticXElementCreateDocLinkUrl(ApiLinkStylestyle,stringprefix,stringdeclaringJniType,stringdeclaringMemberName,stringdeclaringMemberJniSignature)
+staticXElementCreateDocLinkUrl(ApiLinkStylestyle,stringprefix,stringdeclaringJniType,stringdeclaringMemberName,stringdeclaringMemberParameterString)
 {
-;
 if(style==ApiLinkStyle.None||prefix==null||declaringJniType==null)
 returnnull;
 if(UrlCreators.TryGetValue(style,outvarcreator)){
-returncreator(prefix,declaringJniType,declaringMemberName,declaringMemberJniSignature);
+returncreator(prefix,declaringJniType,declaringMemberName,declaringMemberParameterString);
 }
 returnnull;
 }
 
-staticXElementCreateAndroidDocLinkUri(stringprefix,stringdeclaringJniType,stringdeclaringMemberName,stringdeclaringMemberJniSignature)
+staticXElementCreateAndroidDocLinkUri(stringprefix,stringdeclaringJniType,stringdeclaringMemberName,stringdeclaringMemberParameterString)
 {
 // URL is:
 // * {prefix}
 // * declaring type in JNI format
 // * when `declaringJniMemberName` != null, `#{declaringJniMemberName}`
 // * for methods & constructors, a `(`, the arguments in *Java* syntax -- separated by `, ` -- and `)`
 //
-// Example: https://developer.android.com/reference/android/app/Application#registerOnProvideAssistDataListener(android.app.Application.OnProvideAssistDataListener)
+// Example: "https://developer.android.com/reference/android/app/Application#registerOnProvideAssistDataListener(android.app.Application.OnProvideAssistDataListener)"
+// Example: "https://developer.android.com/reference/android/animation/ObjectAnimator#ofFloat(T,%20android.util.Property%3CT,%20java.lang.Float%3E,%20float...)"
 
 varjava=newStringBuilder(declaringJniType)
 .Replace("/",".")
@@ -250,13 +262,9 @@ static XElement CreateAndroidDocLinkUri (string prefix, string declaringJniType,
 if(declaringMemberName!=null){
 java.Append(".").Append(declaringMemberName);
 url.Append("#").Append(declaringMemberName);
-if(declaringMemberJniSignature?.StartsWith("(",StringComparison.Ordinal)??false){
-java.Append("(");
-url.Append("(");
-AppendJavaParameterTypes(java,declaringMemberJniSignature);
-AppendJavaParameterTypes(url,declaringMemberJniSignature);
-java.Append(")");
-url.Append(")");
+if(declaringMemberParameterString!=null){
+java.Append(declaringMemberParameterString);
+url.Append(declaringMemberParameterString);
 }
 }
 varformat=newXElement("format",
@@ -270,85 +278,5 @@ static XElement CreateAndroidDocLinkUri (string prefix, string declaringJniType,
 returnnewXElement("para",format);
 }
 
-staticStringBuilderAppendJavaParameterTypes(StringBuilderbuilder,stringdeclaringMemberJniSignature)
-{
-if(string.IsNullOrEmpty(declaringMemberJniSignature)||declaringMemberJniSignature[0]!='(')
-returnbuilder;
-
-intstartLen=builder.Length;
-
-for(inti=1;i<declaringMemberJniSignature.Length;++i){
-if(declaringMemberJniSignature[i]==')')
-break;
-AppendComma();
-AppendJavaParameterType(builder,declaringMemberJniSignature,refi);
-}
-
-returnbuilder;
-
-voidAppendComma()
-{
-if(startLen==builder.Length)
-return;
-builder.Append(", ");
-}
-}
-
-staticvoidAppendJavaParameterType(StringBuilderbuilder,stringdeclaringMemberJniSignature,refinti)
-{
-switch(declaringMemberJniSignature[i]){
-case'[':{
-++i;
-AppendJavaParameterType(builder,declaringMemberJniSignature,refi);
-builder.Append("[]");
-break;
-}
-case'B':{
-builder.Append("byte");
-break;
-}
-case'C':{
-builder.Append("char");
-break;
-}
-case'D':{
-builder.Append("double");
-break;
-}
-case'F':{
-builder.Append("float");
-break;
-}
-case'I':{
-builder.Append("int");
-break;
-}
-case'J':{
-builder.Append("long");
-break;
-}
-case'L':{
-intend=declaringMemberJniSignature.IndexOf(';',i);
-if(end<0)
-thrownewInvalidOperationException($"INTERNAL ERROR: Invalid JNI signature '{declaringMemberJniSignature}': no ';' to end 'L' at index {i}!");
-vartype=declaringMemberJniSignature.Substring(i+1,end-i-1)
-.Replace('/','.')
-.Replace('$','.');
-builder.Append(type);
-i=end;
-break;
-}
-case'S':{
-builder.Append("short");
-break;
-}
-case'Z':{
-builder.Append("boolean");
-break;
-}
-default:
-thrownewNotSupportedException($"INTERNAL ERROR: Don't know what to do with '{declaringMemberJniSignature[i]}' in '{declaringMemberJniSignature}'!");
-}
-}
 }
 }