From c59d66115bd1294d06ee5986c8f035e1b32ca6ba Mon Sep 17 00:00:00 2001
From: Peter Collins <pecolli@microsoft.com>
Date: Fri, 23 Sep 2022 16:43:54 -0400
Subject: [PATCH] [Java.Interop.Tools.JavaSource] Parse {@param} tags

Fixes: https://github.com/xamarin/java.interop/issues/1042

Translates `{@param foo}` into `<paramref>foo</paramref>`, which should
fix ~70 instances of broken summary/remarks/param elements.
---
 .../SourceJavadocToXmldocGrammar.InlineTagsBnfTerms.cs |  8 ++++++++
 ...ceJavadocToXmldocGrammar.InlineTagsBnfTermsTests.cs | 10 ++++++++++
 .../SourceJavadocToXmldocParserTests.cs                |  6 +++---
 3 files changed, 21 insertions(+), 3 deletions(-)

diff --git a/src/Java.Interop.Tools.JavaSource/Java.Interop.Tools.JavaSource/SourceJavadocToXmldocGrammar.InlineTagsBnfTerms.cs b/src/Java.Interop.Tools.JavaSource/Java.Interop.Tools.JavaSource/SourceJavadocToXmldocGrammar.InlineTagsBnfTerms.cs
index e7c74d85c..347dcf4fa 100644
--- a/src/Java.Interop.Tools.JavaSource/Java.Interop.Tools.JavaSource/SourceJavadocToXmldocGrammar.InlineTagsBnfTerms.cs
+++ b/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));
 		}
 	}
 }
diff --git a/tests/Java.Interop.Tools.JavaSource-Tests/SourceJavadocToXmldocGrammar.InlineTagsBnfTermsTests.cs b/tests/Java.Interop.Tools.JavaSource-Tests/SourceJavadocToXmldocGrammar.InlineTagsBnfTermsTests.cs
index a1d36378e..35076a3b6 100644
--- a/tests/Java.Interop.Tools.JavaSource-Tests/SourceJavadocToXmldocGrammar.InlineTagsBnfTermsTests.cs
+++ b/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 ());
+		}
 	}
 }
diff --git a/tests/Java.Interop.Tools.JavaSource-Tests/SourceJavadocToXmldocParserTests.cs b/tests/Java.Interop.Tools.JavaSource-Tests/SourceJavadocToXmldocParserTests.cs
index 650cd4fc1..042b268b0 100644
--- a/tests/Java.Interop.Tools.JavaSource-Tests/SourceJavadocToXmldocParserTests.cs
+++ b/tests/Java.Interop.Tools.JavaSource-Tests/SourceJavadocToXmldocParserTests.cs
@@ -188,7 +188,7 @@ 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()}
@@ -196,7 +196,7 @@ @param options Additional options.
 @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>