Fix all remaining remarks translation errors

pjcollins · pjcollins · commit b57884cd7af1 · 2022-09-13T19:50:13.000-04:00
All 431 instances of `JavadocImport-Error` that would occur when
generating API docs for Mono.Android.dll have been fixed.
diff --git a/src/Java.Interop.Tools.JavaSource/Java.Interop.Tools.JavaSource/SourceJavadocToXmldocGrammar.BlockTagsBnfTerms.cs b/src/Java.Interop.Tools.JavaSource/Java.Interop.Tools.JavaSource/SourceJavadocToXmldocGrammar.BlockTagsBnfTerms.cs
@@ -102,12 +102,16 @@ internal void CreateRules (SourceJavadocToXmldocGrammar grammar)
 				};
 
 				// Ignore @hide tags
-				HideDeclaration.Rule = "@hide";
+				HideDeclaration.Rule = "@hide"
+					| "@hide" + BlockValues
+					;
 				HideDeclaration.AstConfig.NodeCreator = (context, parseNode) => {
 					FinishParse (context, parseNode);
 				};
 
-				InheritDocDeclaration.Rule = "@inheritDoc";
+				InheritDocDeclaration.Rule = "@inheritDoc"
+					| "@inheritDoc" + BlockValues
+					;
 				InheritDocDeclaration.AstConfig.NodeCreator = (context, parseNode) => {
 					if (!grammar.ShouldImport (ImportJavadoc.InheritDocTag)) {
 						return;
@@ -251,6 +255,7 @@ internal void CreateRules (SourceJavadocToXmldocGrammar grammar)
 					}
 					FinishParse (context, parseNode);
 				};
+
 			}
 
 			public  readonly    NonTerminal AllBlockTerms              = new NonTerminal (nameof (AllBlockTerms), ConcatChildNodes);
@@ -283,6 +288,7 @@ internal void CreateRules (SourceJavadocToXmldocGrammar grammar)
 			public  readonly    NonTerminal ThrowsDeclaration          = new NonTerminal (nameof (ThrowsDeclaration));
 			public  readonly    NonTerminal UnknownTagDeclaration      = new NonTerminal (nameof (UnknownTagDeclaration));
 			public  readonly    NonTerminal VersionDeclaration         = new NonTerminal (nameof (VersionDeclaration));
+
 		}
 	}
 }
diff --git a/src/Java.Interop.Tools.JavaSource/Java.Interop.Tools.JavaSource/SourceJavadocToXmldocGrammar.HtmlBnfTerms.cs b/src/Java.Interop.Tools.JavaSource/Java.Interop.Tools.JavaSource/SourceJavadocToXmldocGrammar.HtmlBnfTerms.cs
@@ -34,6 +34,7 @@ internal void CreateRules (SourceJavadocToXmldocGrammar grammar)
 						| FormCtrlDeclaration
 						*/
 						| InlineHyperLinkDeclaration
+						| AnchorNameDeclaration
 						| grammar.InlineTagsTerms.AllInlineTerms
 						| UnknownHtmlElementStart
 						,
@@ -59,11 +60,11 @@ internal void CreateRules (SourceJavadocToXmldocGrammar grammar)
 					parseNode.AstNode       = "";
 				};
 
-				var fontstyle_tt    = CreateHtmlToCrefElement (grammar, "tt",   "c", InlineDeclarations);
-				var fontstyle_i     = CreateHtmlToCrefElement (grammar, "i",    "i", InlineDeclarations);
+				var fontstyle_tt    = CreateHtmlToCrefElement (grammar, "tt",   "c", InlineDeclarations, optionalEnd: true);
+				var fontstyle_i     = CreateHtmlToCrefElement (grammar, "i",    "i", InlineDeclarations, optionalEnd: true);
 
 				var preText = new PreBlockDeclarationBodyTerminal ();
-				PreBlockDeclaration.Rule = CreateStartElement ("pre", grammar) + preText + CreateEndElement ("pre", grammar);
+				PreBlockDeclaration.Rule = CreateStartElementIgnoreAttribute ("pre") + preText + CreateEndElement ("pre", grammar, optional: true);
 				PreBlockDeclaration.AstConfig.NodeCreator = (context, parseNode) => {
 					if (!grammar.ShouldImport (ImportJavadoc.Remarks)) {
 						parseNode.AstNode   = "";
@@ -125,6 +126,12 @@ internal void CreateRules (SourceJavadocToXmldocGrammar grammar)
 						parseNode.AstNode = astNodeElement;
 					}
 				};
+
+				// Remove obsolete <a name=""></a> HTML content
+				AnchorNameDeclaration.Rule = CreateStartElementIgnoreAttribute ("a", "name") + InlineDeclarations + CreateEndElement ("a", grammar, optional: true);
+				AnchorNameDeclaration.AstConfig.NodeCreator = (context, parseNode) => {
+					FinishParse (context, parseNode);
+				};
 			}
 
 			static IEnumerable<XElement> GetParagraphs (ParseTreeNodeList children)
@@ -193,8 +200,9 @@ static IEnumerable<XElement> GetParagraphs (ParseTreeNodeList children)
 			public  readonly    NonTerminal PBlockDeclaration           = new NonTerminal (nameof (PBlockDeclaration), ConcatChildNodes);
 			public  readonly    NonTerminal PreBlockDeclaration         = new NonTerminal (nameof (PreBlockDeclaration), ConcatChildNodes);
 			public  readonly    NonTerminal InlineHyperLinkDeclaration  = new NonTerminal (nameof (InlineHyperLinkDeclaration), ConcatChildNodes);
+			public  readonly    NonTerminal AnchorNameDeclaration       = new NonTerminal (nameof (AnchorNameDeclaration), ConcatChildNodes);
 
-			public	readonly	Terminal	InlineHyperLinkOpenTerm		= new RegexBasedTerminal ("<a href=", @"<a\s*href=") {
+			public  readonly    Terminal    InlineHyperLinkOpenTerm     = new RegexBasedTerminal ("<a href=", @"(?i)<a\s*href\s*=") {
 				AstConfig = new AstNodeConfig {
 					NodeCreator = (context, parseNode) => parseNode.AstNode = "",
 				},
@@ -231,6 +239,20 @@ static NonTerminal CreateStartElement (string startElement, Grammar grammar)
 				return start;
 			}
 
+			static RegexBasedTerminal CreateStartElementIgnoreAttribute (string startElement, string attribute)
+			{
+				return new RegexBasedTerminal ($"<{startElement} attribute", $@"(?i)<{startElement}\s*{attribute}[^>]*>") {
+					AstConfig = new AstNodeConfig {
+						NodeCreator = (context, parseNode) => parseNode.AstNode = "",
+					},
+				};
+			}
+
+			static RegexBasedTerminal CreateStartElementIgnoreAttribute (string startElement)
+			{
+				return CreateStartElementIgnoreAttribute (startElement, "");
+			}
+
 			static NonTerminal CreateEndElement (string endElement, Grammar grammar, bool optional = false)
 			{
 				var end	    = new NonTerminal (endElement, nodeCreator: (context, parseNode) => parseNode.AstNode = "") {
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
@@ -28,6 +28,7 @@ internal void CreateRules (SourceJavadocToXmldocGrammar grammar)
 					| LiteralDeclaration
 					| SeeDeclaration
 					| ValueDeclaration
+					| IgnorableDeclaration
 					;
 
 				CodeDeclaration.Rule = grammar.ToTerm ("{@code") + InlineValue + "}";
@@ -54,12 +55,24 @@ internal void CreateRules (SourceJavadocToXmldocGrammar grammar)
 					parseNode.AstNode = new XText ("To be added");
 				};
 
-				LinkDeclaration.Rule = grammar.ToTerm ("{@link") + InlineValue + "}";
+				// Some {@link tags are missing a closing bracket, still attempt to match a target value
+				LinkDeclaration.Rule = grammar.ToTerm ("{@link") + InlineValue + "}"
+					| new RegexBasedTerminal ("BrokenLinkTargetValue", "(?!.*}){@link [^ \n\r\t,.]*") {
+						AstConfig = new AstNodeConfig {
+							NodeCreator = (context, parseNode) => parseNode.AstNode = parseNode.Token.Value,
+						},
+					};
+				;
 				LinkDeclaration.AstConfig.NodeCreator = (context, parseNode) => {
 					// TODO: *everything*; {@link target label}, but target can contain spaces!
 					// Also need to convert to appropriate CREF value, use code text for now.
-					var target = parseNode.ChildNodes [1].AstNode;
-					parseNode.AstNode = new XElement ("c", target);
+					if (parseNode.ChildNodes.Count > 1) {
+						var target = parseNode.ChildNodes [1].AstNode;
+						parseNode.AstNode = new XElement ("c", target);
+					} else {
+						var target = parseNode.ChildNodes [0].AstNode;
+						parseNode.AstNode = new XElement ("c", target.ToString ().Replace ("{@link ", ""));
+					}
 				};
 
 				LinkplainDeclaration.Rule = grammar.ToTerm ("{@linkplain") + InlineValue + "}";
@@ -97,6 +110,15 @@ internal void CreateRules (SourceJavadocToXmldocGrammar grammar)
 						parseNode.AstNode = new XText ("To be added");
 					}
 				};
+
+				// Inline content may contain reserved characters with no tags or special parsing rules, do not throw when encountering them
+				IgnorableDeclaration.Rule = grammar.ToTerm ("@ ")
+					| grammar.ToTerm ("{")
+					| grammar.ToTerm ("}")
+					;
+				IgnorableDeclaration.AstConfig.NodeCreator = (context, parseNode) => {
+					parseNode.AstNode = new XText (parseNode.ChildNodes [0].Term.Name.Trim ());
+				};
 			}
 
 			public  readonly    NonTerminal AllInlineTerms              = new NonTerminal (nameof (AllInlineTerms), ConcatChildNodes);
@@ -129,6 +151,9 @@ internal void CreateRules (SourceJavadocToXmldocGrammar grammar)
 
 			// https://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html#value
 			public  readonly    NonTerminal ValueDeclaration            = new NonTerminal (nameof (ValueDeclaration));
+
+			public  readonly    NonTerminal IgnorableDeclaration        = new NonTerminal (nameof (IgnorableDeclaration));
+
 		}
 	}
 }
diff --git a/tests/Java.Interop.Tools.JavaSource-Tests/SourceJavadocToXmldocGrammar.BlockTagsBnfTermsTests.cs b/tests/Java.Interop.Tools.JavaSource-Tests/SourceJavadocToXmldocGrammar.BlockTagsBnfTermsTests.cs
@@ -65,6 +65,11 @@ public void InheritDocDeclaration ()
 			Assert.IsFalse (r.HasErrors (), "@inheritDoc: " + DumpMessages (r, p));
 			// TODO: Enable after adding support for @inheritDoc
 			Assert.IsNull (r.Root.AstNode, "@inheritDoc should be ignored, but node was not null.");
+
+			r = p.Parse ("@inheritDoc With extra");
+			Assert.IsFalse (r.HasErrors (), "@inheritDoc with trailing content " + DumpMessages (r, p));
+			// TODO: Enable after adding support for @inheritDoc
+			Assert.IsNull (r.Root.AstNode, "@inheritDoc with trailing content should be ignored, but node was not null.");
 		}
 
 		[Test]
@@ -75,6 +80,9 @@ public void HideDeclaration ()
 			var r = p.Parse ("@hide");
 			Assert.IsFalse (r.HasErrors (), "@hide: " + DumpMessages (r, p));
 			Assert.IsNull (r.Root.AstNode, "@hide should be ignored, but node was not null.");
+			r = p.Parse ("@hide Method is broken");
+			Assert.IsFalse (r.HasErrors (), "@hide with trailing content: " + DumpMessages (r, p));
+			Assert.IsNull (r.Root.AstNode, "@hide with trailing content should be ignored, but node was not null.");
 		}
 
 		[Test]
diff --git a/tests/Java.Interop.Tools.JavaSource-Tests/SourceJavadocToXmldocGrammar.HtmlBnfTermsTests.cs b/tests/Java.Interop.Tools.JavaSource-Tests/SourceJavadocToXmldocGrammar.HtmlBnfTermsTests.cs
@@ -46,6 +46,10 @@ public void PreBlockDeclaration ()
 			Assert.AreEqual ("<code lang=\"text/java\">this @contains &lt;arbitrary/&gt; text.</code>",
 					r.Root.AstNode.ToString ());
 
+			r = p.Parse ("<pre class=\"prettyprint\">ColorSpace cs = ColorSpace.get(ColorSpace.Named.DCI_P3);");
+			Assert.IsFalse (r.HasErrors (), DumpMessages (r, p));
+			Assert.AreEqual ($"<code lang=\"text/java\">ColorSpace cs = ColorSpace.get(ColorSpace.Named.DCI_P3);</code>",
+					r.Root.AstNode.ToString ());
 		}
 
 		[Test]
diff --git a/tests/Java.Interop.Tools.JavaSource-Tests/SourceJavadocToXmldocParserTests.cs b/tests/Java.Interop.Tools.JavaSource-Tests/SourceJavadocToXmldocParserTests.cs
diff --git a/tools/generator/Java.Interop.Tools.Generator.ObjectModel/JavadocInfo.cs b/tools/generator/Java.Interop.Tools.Generator.ObjectModel/JavadocInfo.cs

Original file line number	Diff line number	Diff line change
`@@ -46,6 +46,10 @@ public void PreBlockDeclaration ()`
`46`	`46`	`Assert.AreEqual ("<code lang=\"text/java\">this @contains <arbitrary/> text.</code>",`
`47`	`47`	`r.Root.AstNode.ToString ());`
`48`	`48`
	`49`	`+ r = p.Parse ("<pre class=\"prettyprint\">ColorSpace cs = ColorSpace.get(ColorSpace.Named.DCI_P3);");`
	`50`	`+ Assert.IsFalse (r.HasErrors (), DumpMessages (r, p));`
	`51`	`+ Assert.AreEqual ($"<code lang=\"text/java\">ColorSpace cs = ColorSpace.get(ColorSpace.Named.DCI_P3);</code>",`
	`52`	`+ r.Root.AstNode.ToString ());`
`49`	`53`	`}`
`50`	`54`
`51`	`55`	`[Test]`