From 5fbd7b2211e99d207894831d82071433fc32a766 Mon Sep 17 00:00:00 2001 From: Peter Collins Date: Tue, 11 May 2021 17:43:37 -0400 Subject: [PATCH 1/2] [generator] Handle multiple @return javadoc values Context: https://github.com/xamarin/xamarin-android/pull/5485 In an attempt to generate updated documentation for API 30 I've noticed a minor issue in generator. When a `` element contains multiple @return values, we will generate multiple `` elements in our C# documentation. This results in invalid C# documentation with partially missing return information, and the second `` element value is not displayed in IDE intellisense. This also causes an issue when the xml is processed by `mdoc`. These extra return lines will continue to be appended to the `mdoc` output every time the tool is ran against the invalid `Mono.Android.xml`. --- ...avadocToXmldocGrammar.BlockTagsBnfTerms.cs | 19 +++++++-- .../SourceJavadocToXmldocParserTests.cs | 39 ++++++++++++------- 2 files changed, 40 insertions(+), 18 deletions(-) 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 642e02da6..a28bf9984 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 @@ -114,10 +114,23 @@ internal void CreateRules (SourceJavadocToXmldocGrammar grammar) if (!grammar.ShouldImport (ImportJavadoc.ReturnTag)) { return; } - var r = new XElement ("returns", + // When encountering multiple @return keys in a line, append subsequent @return key content to the original element. + var jdi = FinishParse (context, parseNode); + if (jdi.Returns.Count == 0) { + var r = new XElement ("returns", AstNodeToXmlContent (parseNode.ChildNodes [1])); - FinishParse (context, parseNode).Returns.Add (r); - parseNode.AstNode = r; + FinishParse (context, parseNode).Returns.Add (r); + parseNode.AstNode = r; + + } else { + var r = jdi.Returns.First () as XElement; + if (r != null) { + r.Add (" ", AstNodeToXmlContent (parseNode.ChildNodes [1])); + FinishParse (context, parseNode).Returns.Clear (); + FinishParse (context, parseNode).Returns.Add (r); + parseNode.AstNode = r; + } + } }; SeeDeclaration.Rule = "@see" + BlockValues; diff --git a/tests/Java.Interop.Tools.JavaSource-Tests/SourceJavadocToXmldocParserTests.cs b/tests/Java.Interop.Tools.JavaSource-Tests/SourceJavadocToXmldocParserTests.cs index a5cf7ddcc..0f88478ac 100644 --- a/tests/Java.Interop.Tools.JavaSource-Tests/SourceJavadocToXmldocParserTests.cs +++ b/tests/Java.Interop.Tools.JavaSource-Tests/SourceJavadocToXmldocParserTests.cs @@ -17,21 +17,19 @@ namespace Java.Interop.Tools.JavaSource.Tests [TestFixture] public class SourceJavadocToXmldocParserTests : SourceJavadocToXmldocGrammarFixture { - [Test] - public void TryParse () + [Test, TestCaseSource (nameof (TryParse_Success))] + public void TryParse (ParseResult parseResult) { - foreach (var values in TryParse_Success) { - ParseTree parseTree; - var p = new SourceJavadocToXmldocParser (XmldocStyle.Full); - var n = p.TryParse (values.Javadoc, null, out parseTree); - Assert.IsFalse (parseTree.HasErrors (), DumpMessages (parseTree, p)); - Assert.AreEqual (values.FullXml, GetMemberXml (n), $"while parsing input: ```{values.Javadoc}```"); + ParseTree parseTree; + var p = new SourceJavadocToXmldocParser (XmldocStyle.Full); + var n = p.TryParse (parseResult.Javadoc, null, out parseTree); + Assert.IsFalse (parseTree.HasErrors (), DumpMessages (parseTree, p)); + Assert.AreEqual (parseResult.FullXml, GetMemberXml (n), $"while parsing input: ```{parseResult.Javadoc}```"); - p = new SourceJavadocToXmldocParser (XmldocStyle.IntelliSense); - n = p.TryParse (values.Javadoc, null, out parseTree); - Assert.IsFalse (parseTree.HasErrors (), DumpMessages (parseTree, p)); - Assert.AreEqual (values.IntelliSenseXml, GetMemberXml (n), $"while parsing input: ```{values.Javadoc}```"); - } + p = new SourceJavadocToXmldocParser (XmldocStyle.IntelliSense); + n = p.TryParse (parseResult.Javadoc, null, out parseTree); + Assert.IsFalse (parseTree.HasErrors (), DumpMessages (parseTree, p)); + Assert.AreEqual (parseResult.IntelliSenseXml, GetMemberXml (n), $"while parsing input: ```{parseResult.Javadoc}```"); } static string GetMemberXml (IEnumerable members) @@ -40,7 +38,7 @@ static string GetMemberXml (IEnumerable members) return e.ToString (); } - static readonly ParseResult[] TryParse_Success = new ParseResult[]{ + public static readonly ParseResult[] TryParse_Success = new ParseResult[]{ new ParseResult { Javadoc = "Summary.\n\nP2.\n\n

Hello!

", FullXml = @" @@ -78,6 +76,17 @@ static string GetMemberXml (IEnumerable members) true if something or other; otherwise false. +", + }, + new ParseResult { + Javadoc = "@return {@code true} if something else @return {@code false}.", + FullXml = @" + + true if something else false. +", + IntelliSenseXml = @" + + true if something else false. ", }, new ParseResult { @@ -166,7 +175,7 @@ more description here. }, }; - class ParseResult { + public class ParseResult { public string Javadoc; public string FullXml; public string IntelliSenseXml; From b21e6650550d12e8ed9cab8636b5b9ab7a227cf3 Mon Sep 17 00:00:00 2001 From: Peter Collins Date: Wed, 12 May 2021 12:44:15 -0400 Subject: [PATCH 2/2] Apply feedback --- .../SourceJavadocToXmldocGrammar.BlockTagsBnfTerms.cs | 3 --- 1 file changed, 3 deletions(-) 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 a28bf9984..258e5c473 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 @@ -121,13 +121,10 @@ internal void CreateRules (SourceJavadocToXmldocGrammar grammar) AstNodeToXmlContent (parseNode.ChildNodes [1])); FinishParse (context, parseNode).Returns.Add (r); parseNode.AstNode = r; - } else { var r = jdi.Returns.First () as XElement; if (r != null) { r.Add (" ", AstNodeToXmlContent (parseNode.ChildNodes [1])); - FinishParse (context, parseNode).Returns.Clear (); - FinishParse (context, parseNode).Returns.Add (r); parseNode.AstNode = r; } }