[Java.Interop.Tools.JavaSource] Skip block and inline @cref values (#844

)

Context: #843
Context: xamarin/android-api-docs#23

A handful of "broken" Javadoc to C# Doc conversions have been
disabled for now.  This will hopefully help reduce the number of new
warnings introduced by xamarin/android-api-docs#23, and allow us to
get an initial major documentation update landed in the short term.
Longer term, we will revisit and fix these Javadoc conversion issues.

Additionally, `Javadoc.cs` has been removed from tools/generator as it
appeared to be an unused partial duplicate of `JavadocInfo.cs`.

Finally, the `<tt>` tag is no longer supported in our docs build:

	HTML tag 'tt' isn't allowed. Replace it with approved Markdown or escape the brackets if the content is a placeholder.

It has been replaced with `<code>` when generating Android Doc links.

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

@@ -89,12 +89,14 @@ internal void CreateRules (SourceJavadocToXmldocGrammar grammar)
 					if (!grammar.ShouldImport (ImportJavadoc.ExceptionTag)) {
 						return;
 					}
-					// TODO: convert `nonSpaceTerm` into a proper CREF
+					/* TODO: convert `nonSpaceTerm` into a proper CREF
 					var e = new XElement ("exception",
 							new XAttribute ("cref", string.Join ("", AstNodeToXmlContent (parseNode.ChildNodes [1]))),
 							AstNodeToXmlContent (parseNode.ChildNodes [2]));
 					FinishParse (context, parseNode).Exceptions.Add (e);
 					parseNode.AstNode   = e;
+					*/
+					FinishParse (context, parseNode);
 				};
 
 				ParamDeclaration.Rule = "@param" + nonSpaceTerm + BlockValues;
@@ -135,11 +137,15 @@ internal void CreateRules (SourceJavadocToXmldocGrammar grammar)
 					if (!grammar.ShouldImport (ImportJavadoc.SeeTag)) {
 						return;
 					}
-					// TODO: @see supports multiple forms; see: https://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html#see
+					/* TODO: @see supports multiple forms; see: https://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html#see
+					// Also need to convert to appropriate CREF value, ignore for now
 					var e = new XElement ("seealso",
 							new XAttribute ("cref", string.Join ("", AstNodeToXmlContent (parseNode.ChildNodes [1]))));
 					FinishParse (context, parseNode).Extra.Add (e);
 					parseNode.AstNode   = e;
+					*/
+					FinishParse (context, parseNode);
+
 				};
 
 				SinceDeclaration.Rule = "@since" + BlockValues;
@@ -157,12 +163,14 @@ internal void CreateRules (SourceJavadocToXmldocGrammar grammar)
 					if (!grammar.ShouldImport (ImportJavadoc.ExceptionTag)) {
 						return;
 					}
-					// TODO: convert `nonSpaceTerm` into a proper CREF
+					/* TODO: convert `nonSpaceTerm` into a proper CREF
 					var e = new XElement ("exception",
 							new XAttribute ("cref", string.Join ("", AstNodeToXmlContent (parseNode.ChildNodes [1]))),
 							AstNodeToXmlContent (parseNode.ChildNodes [2]));
 					FinishParse (context, parseNode).Exceptions.Add (e);
 					parseNode.AstNode   = e;
+					*/
+					FinishParse (context, parseNode);
 				};
 
 				// Ignore serialization informatino

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

@@ -47,18 +47,17 @@ internal void CreateRules (SourceJavadocToXmldocGrammar grammar)
 				LinkDeclaration.Rule = grammar.ToTerm ("{@link") + InlineValue + "}";
 				LinkDeclaration.AstConfig.NodeCreator = (context, parseNode) => {
 					// TODO: *everything*; {@link target label}, but target can contain spaces!
-					// Also need to convert to appropriate CREF value
+					// Also need to convert to appropriate CREF value, use code text for now.
 					var target = parseNode.ChildNodes [1].AstNode;
-					var x = new XElement ("c");
-					parseNode.AstNode = new XElement ("c", new XElement ("see", new XAttribute ("cref", target)));
+					parseNode.AstNode = new XElement ("c", target);
 				};
 
 				LinkplainDeclaration.Rule = grammar.ToTerm ("{@linkplain") + InlineValue + "}";
 				LinkplainDeclaration.AstConfig.NodeCreator = (context, parseNode) => {
 					// TODO: *everything*; {@link target label}, but target can contain spaces!
-					// Also need to convert to appropriate CREF value
-					var target = parseNode.ChildNodes [1].AstNode;
-					parseNode.AstNode = new XElement ("see", new XAttribute ("cref", target));
+					// Also need to convert to appropriate CREF value, use text for now.
+					var target = parseNode.ChildNodes [1].AstNode.ToString ();
+					parseNode.AstNode = new XText (target);
 				};
 
 				LiteralDeclaration.Rule = grammar.ToTerm ("{@literal") + InlineValue + "}";

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

@@ -51,7 +51,9 @@ public void ExceptionDeclaration ()
 
 			var r = p.Parse ("@exception Throwable Just Because.\n");
 			Assert.IsFalse (r.HasErrors (), "@exception: " + DumpMessages (r, p));
-			Assert.AreEqual ("<exception cref=\"Throwable\">Just Because.</exception>", r.Root.AstNode.ToString ());
+			Assert.IsNull (r.Root.AstNode, "@exception should be ignored, but node was not null.");
+			// TODO: Re-enable when we can generate valid crefs
+			//Assert.AreEqual ("<exception cref=\"Throwable\">Just Because.</exception>", r.Root.AstNode.ToString ());
 		}
 
 		[Test]
@@ -97,7 +99,9 @@ public void SeeDeclaration ()
 
 			var r = p.Parse ("@see \"Insert Book Name Here\"");
 			Assert.IsFalse (r.HasErrors (), "@see: " + DumpMessages (r, p));
-			Assert.AreEqual ("<seealso cref=\"&quot;Insert Book Name Here&quot;\" />", r.Root.AstNode.ToString ());
+			Assert.IsNull (r.Root.AstNode, "@see should be ignored, but node was not null.");
+			// TODO: Re-enable when we can generate valid crefs
+			//Assert.AreEqual ("<seealso cref=\"&quot;Insert Book Name Here&quot;\" />", r.Root.AstNode.ToString ());
 		}
 
 		[Test]
@@ -117,11 +121,15 @@ public void ThrowsDeclaration ()
 
 			var r = p.Parse ("@throws Throwable the {@code Exception} raised by this method");
 			Assert.IsFalse (r.HasErrors (), "@throws: " + DumpMessages (r, p));
-			Assert.AreEqual ("<exception cref=\"Throwable\">the <c>Exception</c> raised by this method</exception>", r.Root.AstNode.ToString ());
+			Assert.IsNull (r.Root.AstNode, "@throws should be ignored, but node with code block was not null.");
+			// TODO: Re-enable when we can generate valid crefs
+			//Assert.AreEqual ("<exception cref=\"Throwable\">the <c>Exception</c> raised by this method</exception>", r.Root.AstNode.ToString ());
 
 			r = p.Parse ("@throws Throwable something <i>or other</i>!");
 			Assert.IsFalse (r.HasErrors (), "@throws: " + DumpMessages (r, p));
-			Assert.AreEqual ("<exception cref=\"Throwable\">something <i>or other</i>!</exception>", r.Root.AstNode.ToString ());
+			Assert.IsNull (r.Root.AstNode, "@throws should be ignored, but node was not null.");
+			// TODO: Re-enable when we can generate valid crefs
+			//Assert.AreEqual ("<exception cref=\"Throwable\">something <i>or other</i>!</exception>", r.Root.AstNode.ToString ());
 		}
 
 		[Test]

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

@@ -52,7 +52,7 @@ public void LinkDeclaration ()
 			var r = p.Parse ("{@link #ctor}");
 			Assert.IsFalse (r.HasErrors (), DumpMessages (r, p));
 			var c = (XElement) r.Root.AstNode;
-			Assert.AreEqual ("<c><see cref=\"#ctor\" /></c>", c.ToString (SaveOptions.DisableFormatting));
+			Assert.AreEqual ("<c>#ctor</c>", c.ToString (SaveOptions.DisableFormatting));
 		}
 
 		[Test]
@@ -62,7 +62,7 @@ public void LinkplainDeclaration ()
 
 			var r = p.Parse ("{@linkplain #ctor}");
 			Assert.IsFalse (r.HasErrors (), DumpMessages (r, p));
-			Assert.AreEqual ("<see cref=\"#ctor\" />", r.Root.AstNode.ToString ());
+			Assert.AreEqual ("#ctor", r.Root.AstNode.ToString ());
 		}
 
 		[Test]

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

@@ -111,7 +111,6 @@ more description here.</para>
     <para>What about <i>hard</i> paragraphs?</para>
     <para>Added in API level 1.</para>
   </remarks>
-  <seealso cref=""#method()"" />
 </member>",
 				IntelliSenseXml = @"<member>
   <param name=""a"">something</param>
@@ -135,14 +134,14 @@ more description here.</para>
 			new ParseResult {
 				Javadoc = "Something {@link #method}: description, \"<code>declaration</code>\" or \"<code>another declaration</code>\".\n\n@apiSince 1\n",
 				FullXml = @"<member>
-  <summary>Something <c><see cref=""#method"" /></c>: description, ""&lt;code&gt;declaration&lt;/code&gt;"" or ""&lt;code&gt;another declaration&lt;/code&gt;"".</summary>
+  <summary>Something <c>#method</c>: description, ""&lt;code&gt;declaration&lt;/code&gt;"" or ""&lt;code&gt;another declaration&lt;/code&gt;"".</summary>
   <remarks>
-    <para>Something <c><see cref=""#method"" /></c>: description, ""&lt;code&gt;declaration&lt;/code&gt;"" or ""&lt;code&gt;another declaration&lt;/code&gt;"".</para>
+    <para>Something <c>#method</c>: description, ""&lt;code&gt;declaration&lt;/code&gt;"" or ""&lt;code&gt;another declaration&lt;/code&gt;"".</para>
     <para>Added in API level 1.</para>
   </remarks>
 </member>",
 				IntelliSenseXml = @"<member>
-  <summary>Something <c><see cref=""#method"" /></c>: description, ""&lt;code&gt;declaration&lt;/code&gt;"" or ""&lt;code&gt;another declaration&lt;/code&gt;"".</summary>
+  <summary>Something <c>#method</c>: description, ""&lt;code&gt;declaration&lt;/code&gt;"" or ""&lt;code&gt;another declaration&lt;/code&gt;"".</summary>
 </member>",
 			},
 			new ParseResult {
@@ -166,11 +165,9 @@ more description here.</para>
   <remarks>
     <para>Summary.</para>
   </remarks>
-  <exception cref=""Throwable"">insert <i>description</i> here.</exception>
 </member>",
 				IntelliSenseXml = @"<member>
   <summary>Summary.</summary>
-  <exception cref=""Throwable"">insert <i>description</i> here.</exception>
 </member>",
 			},
 		};

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

@@ -256,7 +256,7 @@ static XElement CreateAndroidDocLinkUri (string prefix, string declaringJniType,
 						new XAttribute ("href", new Uri (url.ToString ()).AbsoluteUri),
 						new XAttribute ("title", "Reference documentation"),
 						"Java documentation for ",
-						new XElement ("tt", java.ToString ()),
+						new XElement ("code", java.ToString ()),
 						"."));
 			return new XElement ("para", format);
 		}