[Java.Interop.Tools.JavaSource] Parse {@param} tags (#1045)

Fixes: #1042

Translates Javadoc `{@param foo}` into C# `<paramref>foo</paramref>`,
which should fix ~70 instances of broken summary/remarks/param elements.

Author: pjcollins

src/Java.Interop.Tools.JavaSource/Java.Interop.Tools.JavaSource/SourceJavadocToXmldocGrammar.InlineTagsBnfTerms.cs

@@ -30,6 +30,7 @@ internal void CreateRules (SourceJavadocToXmldocGrammar grammar)
 					| SeeDeclaration
 					| ValueDeclaration
 					| IgnorableDeclaration
+					| InlineParamDeclaration
 					;
 
 				CodeDeclaration.Rule = grammar.ToTerm ("{@code") + InlineValue + "}";
@@ -116,6 +117,12 @@ internal void CreateRules (SourceJavadocToXmldocGrammar grammar)
 				IgnorableDeclaration.AstConfig.NodeCreator = (context, parseNode) => {
 					parseNode.AstNode = new XText (parseNode.ChildNodes [0].Term.Name.Trim ());
 				};
+
+				InlineParamDeclaration.Rule = grammar.ToTerm ("{@param") + InlineValue + "}";
+				InlineParamDeclaration.AstConfig.NodeCreator = (context, parseNode) => {
+					var target = parseNode.ChildNodes [1].AstNode;
+					parseNode.AstNode = new XElement ("paramref", target);
+				};
 			}
 
 			public  readonly    NonTerminal AllInlineTerms              = new NonTerminal (nameof (AllInlineTerms), ConcatChildNodes);
@@ -151,6 +158,7 @@ internal void CreateRules (SourceJavadocToXmldocGrammar grammar)
 
 			public  readonly    NonTerminal IgnorableDeclaration        = new NonTerminal (nameof (IgnorableDeclaration));
 
+			public  readonly    NonTerminal InlineParamDeclaration      = new NonTerminal (nameof (InlineParamDeclaration));
 		}
 	}
 }

tests/Java.Interop.Tools.JavaSource-Tests/SourceJavadocToXmldocGrammar.InlineTagsBnfTermsTests.cs

@@ -98,5 +98,15 @@ public void ValueDeclaration ()
 			Assert.IsFalse (r.HasErrors (), DumpMessages (r, p));
 			Assert.AreEqual ("<c>#field</c>", r.Root.AstNode.ToString ());
 		}
+
+		[Test]
+		public void InlineParamDeclaration ()
+		{
+			var p = CreateParser (g => g.InlineTagsTerms.InlineParamDeclaration);
+
+			var r = p.Parse ("{@param phoneNumberString}");
+			Assert.IsFalse (r.HasErrors (), DumpMessages (r, p));
+			Assert.AreEqual ("<paramref>phoneNumberString</paramref>", r.Root.AstNode.ToString ());
+		}
 	}
 }

tests/Java.Interop.Tools.JavaSource-Tests/SourceJavadocToXmldocParserTests.cs

@@ -188,15 +188,15 @@ more description {e.g. something} here.  Include @ character.
 How about another link <a href=""http://man7.org/linux/man-pages/man2/accept.2.html"">accept(2)</a>
 @param manifest The value of the <a
 HREF = ""{@docRoot}guide/topics/manifest/manifest-element.html#vcode"">{@code
-android:versionCode}</a> manifest attribute.
+android:versionCode}</a> manifest attribute.  See {@param empty}.
 @param empty
 @param options Additional options.
 See {@link foo()}
 bar()} for more details.
 @return the return value
 ",
 				FullXml = $@"<member>
-  <param name=""manifest"">The value of the <see href=""{DocRootPrefixExpected}guide/topics/manifest/manifest-element.html#vcode""><c>android:versionCode</c></see> manifest attribute.</param>
+  <param name=""manifest"">The value of the <see href=""{DocRootPrefixExpected}guide/topics/manifest/manifest-element.html#vcode""><c>android:versionCode</c></see> manifest attribute.  See <paramref>empty</paramref>.</param>
   <param name=""empty"">empty</param>
   <param name=""options"">Additional options.
 See <c>foo()</c>
@@ -210,7 +210,7 @@ more description {{e.g. something}} here.  Include @ character.
   <returns>the return value</returns>
 </member>",
 				IntelliSenseXml = $@"<member>
-  <param name=""manifest"">The value of the <see href=""{DocRootPrefixExpected}guide/topics/manifest/manifest-element.html#vcode""><c>android:versionCode</c></see> manifest attribute.</param>
+  <param name=""manifest"">The value of the <see href=""{DocRootPrefixExpected}guide/topics/manifest/manifest-element.html#vcode""><c>android:versionCode</c></see> manifest attribute.  See <paramref>empty</paramref>.</param>
   <param name=""empty"">empty</param>
   <param name=""options"">Additional options.
 See <c>foo()</c>