Skip to content

Commit

Permalink
[Java.Interop.Tools.JavaSource] Remove block and inline @cref values
Browse files Browse the repository at this point in the history 
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`.
  • Loading branch information
@pjcollins
pjcollins committed May 19, 2021
1 parent 412e974 commit ffb3d0a
Show file tree
Hide file tree
Showing 6 changed files with 29 additions and 100 deletions.
14 changes: 11 additions & 3 deletions ...avaSource/Java.Interop.Tools.JavaSource/SourceJavadocToXmldocGrammar.BlockTagsBnfTerms.cs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down Expand Up @@ -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;
Expand All @@ -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
Expand Down
11 changes: 5 additions & 6 deletions ...vaSource/Java.Interop.Tools.JavaSource/SourceJavadocToXmldocGrammar.InlineTagsBnfTerms.cs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 + "}";
Expand Down
12 changes: 8 additions & 4 deletions ...ava.Interop.Tools.JavaSource-Tests/SourceJavadocToXmldocGrammar.BlockTagsBnfTermsTests.cs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 ("<exception cref=\"Throwable\">Just Because.</exception>", r.Root.AstNode.ToString ());
Assert.IsNull (r.Root.AstNode, "@exception should be ignored, but node was not null.");
//Assert.AreEqual ("<exception cref=\"Throwable\">Just Because.</exception>", r.Root.AstNode.ToString ());
}

[Test]
Expand Down Expand Up @@ -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 ("<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.");
//Assert.AreEqual ("<seealso cref=\"&quot;Insert Book Name Here&quot;\" />", r.Root.AstNode.ToString ());
}

[Test]
Expand All @@ -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 ("<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.");
//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.");
//Assert.AreEqual ("<exception cref=\"Throwable\">something <i>or other</i>!</exception>", r.Root.AstNode.ToString ());
}

[Test]
Expand Down
4 changes: 2 additions & 2 deletions ...va.Interop.Tools.JavaSource-Tests/SourceJavadocToXmldocGrammar.InlineTagsBnfTermsTests.cs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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]
Expand All @@ -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]
Expand Down
9 changes: 3 additions & 6 deletions tests/Java.Interop.Tools.JavaSource-Tests/SourceJavadocToXmldocParserTests.cs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Expand All @@ -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 {
Expand All @@ -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>",
},
};
Expand Down
79 changes: 0 additions & 79 deletions tools/generator/Java.Interop.Tools.Generator.ObjectModel/Javadoc.cs
View file

This file was deleted.

0 comments on commit ffb3d0a

Please sign in to comment.