From ffb3d0a1bf608de0fe5109e2e654f9a0e283b561 Mon Sep 17 00:00:00 2001 From: Peter Collins Date: Wed, 19 May 2021 14:21:05 -0400 Subject: [PATCH] [Java.Interop.Tools.JavaSource] Remove block and inline @cref values Context: https://github.com/xamarin/java.interop/issues/843 Context: https://github.com/xamarin/android-api-docs/pull/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 https://github.com/xamarin/android-api-docs/pull/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`. --- ...avadocToXmldocGrammar.BlockTagsBnfTerms.cs | 14 +++- ...vadocToXmldocGrammar.InlineTagsBnfTerms.cs | 11 ++- ...cToXmldocGrammar.BlockTagsBnfTermsTests.cs | 12 ++- ...ToXmldocGrammar.InlineTagsBnfTermsTests.cs | 4 +- .../SourceJavadocToXmldocParserTests.cs | 9 +-- .../Javadoc.cs | 79 ------------------- 6 files changed, 29 insertions(+), 100 deletions(-) delete mode 100644 tools/generator/Java.Interop.Tools.Generator.ObjectModel/Javadoc.cs 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 index 258e5c473..ea43046e8 100644 --- 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 @@ -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 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 7eef65c1b..6c3255326 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 @@ -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 + "}"; diff --git a/tests/Java.Interop.Tools.JavaSource-Tests/SourceJavadocToXmldocGrammar.BlockTagsBnfTermsTests.cs b/tests/Java.Interop.Tools.JavaSource-Tests/SourceJavadocToXmldocGrammar.BlockTagsBnfTermsTests.cs index f5cde828a..566563f6f 100644 --- a/tests/Java.Interop.Tools.JavaSource-Tests/SourceJavadocToXmldocGrammar.BlockTagsBnfTermsTests.cs +++ b/tests/Java.Interop.Tools.JavaSource-Tests/SourceJavadocToXmldocGrammar.BlockTagsBnfTermsTests.cs @@ -51,7 +51,8 @@ public void ExceptionDeclaration () var r = p.Parse ("@exception Throwable Just Because.\n"); Assert.IsFalse (r.HasErrors (), "@exception: " + DumpMessages (r, p)); - Assert.AreEqual ("Just Because.", r.Root.AstNode.ToString ()); + Assert.IsNull (r.Root.AstNode, "@exception should be ignored, but node was not null."); + //Assert.AreEqual ("Just Because.", r.Root.AstNode.ToString ()); } [Test] @@ -97,7 +98,8 @@ public void SeeDeclaration () var r = p.Parse ("@see \"Insert Book Name Here\""); Assert.IsFalse (r.HasErrors (), "@see: " + DumpMessages (r, p)); - Assert.AreEqual ("", r.Root.AstNode.ToString ()); + Assert.IsNull (r.Root.AstNode, "@see should be ignored, but node was not null."); + //Assert.AreEqual ("", r.Root.AstNode.ToString ()); } [Test] @@ -117,11 +119,13 @@ 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 ("the Exception raised by this method", r.Root.AstNode.ToString ()); + Assert.IsNull (r.Root.AstNode, "@throws should be ignored, but node with code block was not null."); + //Assert.AreEqual ("the Exception raised by this method", r.Root.AstNode.ToString ()); r = p.Parse ("@throws Throwable something or other!"); Assert.IsFalse (r.HasErrors (), "@throws: " + DumpMessages (r, p)); - Assert.AreEqual ("something or other!", r.Root.AstNode.ToString ()); + Assert.IsNull (r.Root.AstNode, "@throws should be ignored, but node was not null."); + //Assert.AreEqual ("something or other!", r.Root.AstNode.ToString ()); } [Test] diff --git a/tests/Java.Interop.Tools.JavaSource-Tests/SourceJavadocToXmldocGrammar.InlineTagsBnfTermsTests.cs b/tests/Java.Interop.Tools.JavaSource-Tests/SourceJavadocToXmldocGrammar.InlineTagsBnfTermsTests.cs index f59bb058d..06dcd7390 100644 --- a/tests/Java.Interop.Tools.JavaSource-Tests/SourceJavadocToXmldocGrammar.InlineTagsBnfTermsTests.cs +++ b/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.ToString (SaveOptions.DisableFormatting)); + Assert.AreEqual ("#ctor", 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 ("", r.Root.AstNode.ToString ()); + Assert.AreEqual ("#ctor", 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 index 0f88478ac..e0480ab83 100644 --- a/tests/Java.Interop.Tools.JavaSource-Tests/SourceJavadocToXmldocParserTests.cs +++ b/tests/Java.Interop.Tools.JavaSource-Tests/SourceJavadocToXmldocParserTests.cs @@ -111,7 +111,6 @@ more description here. What about hard paragraphs? Added in API level 1. - ", IntelliSenseXml = @" something @@ -135,14 +134,14 @@ more description here. new ParseResult { Javadoc = "Something {@link #method}: description, \"declaration\" or \"another declaration\".\n\n@apiSince 1\n", FullXml = @" - Something : description, ""<code>declaration</code>"" or ""<code>another declaration</code>"". + Something #method: description, ""<code>declaration</code>"" or ""<code>another declaration</code>"". - Something : description, ""<code>declaration</code>"" or ""<code>another declaration</code>"". + Something #method: description, ""<code>declaration</code>"" or ""<code>another declaration</code>"". Added in API level 1. ", IntelliSenseXml = @" - Something : description, ""<code>declaration</code>"" or ""<code>another declaration</code>"". + Something #method: description, ""<code>declaration</code>"" or ""<code>another declaration</code>"". ", }, new ParseResult { @@ -166,11 +165,9 @@ more description here. Summary. - insert description here. ", IntelliSenseXml = @" Summary. - insert description here. ", }, }; diff --git a/tools/generator/Java.Interop.Tools.Generator.ObjectModel/Javadoc.cs b/tools/generator/Java.Interop.Tools.Generator.ObjectModel/Javadoc.cs deleted file mode 100644 index 28c2702db..000000000 --- a/tools/generator/Java.Interop.Tools.Generator.ObjectModel/Javadoc.cs +++ /dev/null @@ -1,79 +0,0 @@ -using System; -using System.Collections.Generic; -using System.IO; -using System.Xml.Linq; - -using Irony.Parsing; - -using Java.Interop.Tools.JavaSource; - -namespace MonoDroid.Generation -{ - public static class Javadoc { - - public static void AddJavadocs (ICollection comments, string javadoc) - { - if (string.IsNullOrWhiteSpace (javadoc)) - return; - - javadoc = javadoc.Trim (); - - ParseTree tree = null; - - try { - var parser = new SourceJavadocToXmldocParser (); - var nodes = parser.TryParse (javadoc, fileName: null, out tree); - foreach (var node in (nodes ?? new XNode [0])) { - AddNode (comments, node); - } - } - catch (Exception e) { - Console.Error.WriteLine ($"## Exception translating remarks: {e.ToString ()}"); - } - - if (tree != null && tree.HasErrors ()) { - Console.Error.WriteLine ($"## Unable to translate remarks:"); - Console.Error.WriteLine ("```"); - Console.Error.WriteLine (javadoc); - Console.Error.WriteLine ("```"); - PrintMessages (tree, Console.Error); - Console.Error.WriteLine (); - } - } - - static void AddNode (ICollection comments, XNode node) - { - if (node == null) - return; - var contents = node.ToString (); - - var lines = new StringReader (contents); - string line; - while ((line = lines.ReadLine ()) != null) { - comments.Add ($"/// {line}"); - } - } - - static void PrintMessages (ParseTree tree, TextWriter writer) - { - var lines = GetLines (tree.SourceText); - foreach (var m in tree.ParserMessages) { - writer.WriteLine ($"{m.Level} {m.Location}: {m.Message}"); - writer.WriteLine (lines [m.Location.Line]); - writer.Write (new string (' ', m.Location.Column)); - writer.WriteLine ("^"); - } - } - - static List GetLines (string text) - { - var lines = new List(); - var reader = new StringReader (text); - string line; - while ((line = reader.ReadLine()) != null) { - lines.Add (line); - } - return lines; - } - } -}