Skip to content

Commit f350179

Browse files
pjcollinspjcollins
committed
WIP Inline tag TODOs and common HTML tag parsing
1 parent aac3e9a commit f350179

File tree

13 files changed

+165
-35
lines changed

13 files changed

+165
-35
lines changed

‎src/Java.Interop.Tools.JavaSource/Java.Interop.Tools.JavaSource/SourceJavadocToXmldocGrammar.HtmlBnfTerms.cs

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@
22
using System.Collections.Generic;
33
using System.IO;
44
using System.Linq;
5+
using System.Text;
56
using System.Xml.Linq;
67

78
using Irony.Ast;
@@ -33,6 +34,7 @@ internal void CreateRules (SourceJavadocToXmldocGrammar grammar)
3334
| SpecialDeclaration
3435
| FormCtrlDeclaration
3536
*/
37+
| InlineHyperLinkDeclaration
3638
| grammar.InlineTagsTerms.AllInlineTerms
3739
| UnknownHtmlElementStart
3840
,
@@ -94,6 +96,35 @@ internal void CreateRules (SourceJavadocToXmldocGrammar grammar)
9496
FinishParse (context, parseNode).Remarks.Add (p);
9597
parseNode.AstNode = p;
9698
};
99+
100+
InlineHyperLinkDeclaration.Rule = CreateOpenStartElement ("a", grammar) + InlineDeclarations + CreateEndElement ("a", grammar);
101+
InlineHyperLinkDeclaration.AstConfig.NodeCreator = (context, parseNode) => {
102+
var seeHtmlBuilder = new StringBuilder ();
103+
seeHtmlBuilder.Append ("<see");
104+
GetNodeContent (parseNode.ChildNodes, seeHtmlBuilder);
105+
void GetNodeContent (ParseTreeNodeList nodeList, StringBuilder sb)
106+
{
107+
foreach (var cn in nodeList) {
108+
if (cn.ChildNodes?.Count > 1) {
109+
GetNodeContent (cn.ChildNodes, sb);
110+
} else {
111+
if (!string.IsNullOrEmpty (cn.AstNode?.ToString ())) {
112+
sb.Append (cn.AstNode?.ToString ());
113+
}
114+
}
115+
}
116+
}
117+
seeHtmlBuilder.Append ("</see>");
118+
119+
var aHtmlElementAsString = seeHtmlBuilder.ToString ();
120+
XNode seeElement = new XText (aHtmlElementAsString);
121+
try {
122+
seeElement = XElement.Parse (aHtmlElementAsString);
123+
} catch (Exception e) {
124+
Console.Error.WriteLine ($"# Unable to parse HTML element: {aHtmlElementAsString}");
125+
}
126+
parseNode.AstNode = seeElement;
127+
};
97128
}
98129

99130
static IEnumerable<XElement> GetParagraphs (ParseTreeNodeList children)
@@ -161,6 +192,7 @@ static IEnumerable<XElement> GetParagraphs (ParseTreeNodeList children)
161192
public readonly NonTerminal BlockDeclaration = new NonTerminal (nameof (BlockDeclaration), ConcatChildNodes);
162193
public readonly NonTerminal PBlockDeclaration = new NonTerminal (nameof (PBlockDeclaration), ConcatChildNodes);
163194
public readonly NonTerminal PreBlockDeclaration = new NonTerminal (nameof (PreBlockDeclaration), ConcatChildNodes);
195+
public readonly NonTerminal InlineHyperLinkDeclaration = new NonTerminal (nameof (InlineHyperLinkDeclaration), ConcatChildNodes);
164196

165197
public readonly Terminal UnknownHtmlElementStart = new UnknownHtmlElementStartTerminal (nameof (UnknownHtmlElementStart)) {
166198
AstConfig = new AstNodeConfig {
@@ -193,6 +225,14 @@ static NonTerminal CreateStartElement (string startElement, Grammar grammar)
193225
return start;
194226
}
195227

228+
static NonTerminal CreateOpenStartElement (string startElement, Grammar grammar)
229+
{
230+
var start = new NonTerminal ("<" + startElement, nodeCreator: (context, parseNode) => parseNode.AstNode = "") {
231+
Rule = grammar.ToTerm ("<" + startElement) | "<" + startElement.ToUpperInvariant (),
232+
};
233+
return start;
234+
}
235+
196236
static NonTerminal CreateEndElement (string endElement, Grammar grammar, bool optional = false)
197237
{
198238
var end = new NonTerminal (endElement, nodeCreator: (context, parseNode) => parseNode.AstNode = "") {

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

Lines changed: 11 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -36,12 +36,21 @@ internal void CreateRules (SourceJavadocToXmldocGrammar grammar)
3636

3737
DocRootDeclaration.Rule = grammar.ToTerm ("{@docRoot}");
3838
DocRootDeclaration.AstConfig.NodeCreator = (context, parseNode) => {
39-
parseNode.AstNode = new XText ("[TODO: @docRoot]");
39+
var docRoot = grammar.XmldocSettings.DocRootValue;
40+
if (!string.IsNullOrEmpty (docRoot)) {
41+
if (!docRoot.EndsWith ("/", StringComparison.OrdinalIgnoreCase)) {
42+
docRoot += "/";
43+
}
44+
} else {
45+
docRoot = "{@docRoot}";
46+
}
47+
parseNode.AstNode = new XText (docRoot);
4048
};
4149

4250
InheritDocDeclaration.Rule = grammar.ToTerm ("{@inheritDoc}");
4351
InheritDocDeclaration.AstConfig.NodeCreator = (context, parseNode) => {
44-
parseNode.AstNode = new XText ("[TODO: @inheritDoc]");
52+
// TODO: Iterate through parents for corresponding docs
53+
parseNode.AstNode = "";
4554
};
4655

4756
LinkDeclaration.Rule = grammar.ToTerm ("{@link") + InlineValue + "}";

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

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -16,15 +16,15 @@ public partial class SourceJavadocToXmldocGrammar : Grammar {
1616
public readonly InlineTagsBnfTerms InlineTagsTerms;
1717
public readonly HtmlBnfTerms HtmlTerms;
1818

19-
public readonly XmldocStyle XmldocStyle;
19+
public readonly XmldocSettings XmldocSettings;
2020

21-
public SourceJavadocToXmldocGrammar (XmldocStyle style)
21+
public SourceJavadocToXmldocGrammar (XmldocSettings settings)
2222
{
2323
BlockTagsTerms = new BlockTagsBnfTerms ();
2424
InlineTagsTerms = new InlineTagsBnfTerms ();
2525
HtmlTerms = new HtmlBnfTerms ();
2626

27-
XmldocStyle = style;
27+
XmldocSettings = settings;
2828

2929
BlockTagsTerms.CreateRules (this);
3030
InlineTagsTerms.CreateRules (this);
@@ -55,7 +55,7 @@ public SourceJavadocToXmldocGrammar (XmldocStyle style)
5555

5656
internal bool ShouldImport (ImportJavadoc value)
5757
{
58-
var v = (ImportJavadoc) XmldocStyle;
58+
var v = (ImportJavadoc) XmldocSettings.Style;
5959
return v.HasFlag (value);
6060
}
6161

‎src/Java.Interop.Tools.JavaSource/Java.Interop.Tools.JavaSource/SourceJavadocToXmldocParser.cs

Lines changed: 12 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -56,19 +56,19 @@ public enum XmldocStyle {
5656

5757
public class SourceJavadocToXmldocParser : Irony.Parsing.Parser {
5858

59-
public SourceJavadocToXmldocParser (XmldocStyle style = XmldocStyle.Full)
60-
: base (CreateGrammar (style))
59+
public SourceJavadocToXmldocParser (XmldocSettings settings)
60+
: base (CreateGrammar (settings))
6161
{
62-
XmldocStyle = style;
62+
XmldocSettings = settings;
6363
}
6464

65-
public XmldocStyle XmldocStyle { get; }
65+
public XmldocSettings XmldocSettings { get; }
6666

67-
public XElement[]? ExtraRemarks { get; set; }
6867

69-
static Grammar CreateGrammar (XmldocStyle style)
68+
69+
static Grammar CreateGrammar (XmldocSettings settings)
7070
{
71-
return new SourceJavadocToXmldocGrammar (style) {
71+
return new SourceJavadocToXmldocGrammar (settings) {
7272
LanguageFlags = LanguageFlags.Default | LanguageFlags.CreateAst,
7373
};
7474
}
@@ -102,13 +102,13 @@ IEnumerable<XNode> CreateParseIterator (ParseTree parseTree)
102102
var summary = CreateSummaryNode (info);
103103
if (summary != null)
104104
yield return summary;
105-
var style = (ImportJavadoc) XmldocStyle;
105+
var style = (ImportJavadoc) XmldocSettings.Style;
106106
if (style.HasFlag (ImportJavadoc.Remarks) &&
107-
(info.Remarks.Count > 0 || ExtraRemarks?.Length > 0)) {
108-
yield return new XElement ("remarks", info.Remarks, ExtraRemarks);
107+
(info.Remarks.Count > 0 || XmldocSettings.ExtraRemarks?.Length > 0)) {
108+
yield return new XElement ("remarks", info.Remarks, XmldocSettings.ExtraRemarks);
109109
}
110-
else if (style.HasFlag (ImportJavadoc.ExtraRemarks) && ExtraRemarks?.Length > 0) {
111-
yield return new XElement ("remarks", ExtraRemarks);
110+
else if (style.HasFlag (ImportJavadoc.ExtraRemarks) && XmldocSettings.ExtraRemarks?.Length > 0) {
111+
yield return new XElement ("remarks", XmldocSettings.ExtraRemarks);
112112
}
113113
foreach (var n in info.Returns) {
114114
yield return n;

‎src/Java.Interop.Tools.JavaSource/Java.Interop.Tools.JavaSource/XmldocSettings.cs

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
using System;
2+
using System.Xml.Linq;
3+
4+
namespace Java.Interop.Tools.JavaSource
5+
{
6+
public class XmldocSettings
7+
{
8+
public string DocRootValue { get; set; } = string.Empty;
9+
public XElement []? ExtraRemarks { get; set; }
10+
public XmldocStyle Style { get; set; } = XmldocStyle.Full;
11+
}
12+
}

‎tests/Java.Interop.Tools.JavaSource-Tests/SourceJavadocToXmldocGrammar.HtmlBnfTermsTests.cs

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -47,5 +47,17 @@ public void PreBlockDeclaration ()
4747
r.Root.AstNode.ToString ());
4848

4949
}
50+
51+
[Test]
52+
public void HyperLinkDeclaration ()
53+
{
54+
var p = CreateParser (g => g.HtmlTerms.InlineHyperLinkDeclaration);
55+
56+
var r = p.Parse ("<a href=\"https://developer.android.com/guide/topics/manifest/application-element.html\">application</a>");
57+
Assert.IsFalse (r.HasErrors (), DumpMessages (r, p));
58+
Console.WriteLine (r.Root.AstNode.ToString ());
59+
Assert.AreEqual ("<see href=\"https://developer.android.com/guide/topics/manifest/application-element.html\">application</see>",
60+
r.Root.AstNode.ToString ());
61+
}
5062
}
5163
}

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

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -31,7 +31,7 @@ public void DocRootDeclaration ()
3131

3232
var r = p.Parse ("{@docRoot}");
3333
Assert.IsFalse (r.HasErrors (), DumpMessages (r, p));
34-
Assert.AreEqual ("[TODO: @docRoot]", r.Root.AstNode.ToString ());
34+
Assert.AreEqual (DocRootPrefixExpected, r.Root.AstNode.ToString ());
3535
}
3636

3737
[Test]
@@ -41,7 +41,7 @@ public void InheritDocDeclaration ()
4141

4242
var r = p.Parse ("{@inheritDoc}");
4343
Assert.IsFalse (r.HasErrors (), DumpMessages (r, p));
44-
Assert.AreEqual ("[TODO: @inheritDoc]", r.Root.AstNode.ToString ());
44+
Assert.AreEqual (string.Empty, r.Root.AstNode.ToString ());
4545
}
4646

4747
[Test]

‎tests/Java.Interop.Tools.JavaSource-Tests/SourceJavadocToXmldocGrammarFixture.cs

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -17,9 +17,16 @@ namespace Java.Interop.Tools.JavaSource.Tests
1717
[TestFixture]
1818
public class SourceJavadocToXmldocGrammarFixture {
1919

20+
protected const string DocRootPrefixActual = "https://developer.android.com";
21+
protected const string DocRootPrefixExpected = DocRootPrefixActual + "/";
22+
2023
public static Parser CreateParser (Func<SourceJavadocToXmldocGrammar, NonTerminal> root)
2124
{
22-
var g = new SourceJavadocToXmldocGrammar (XmldocStyle.Full) {
25+
var g = new SourceJavadocToXmldocGrammar (new XmldocSettings {
26+
Style = XmldocStyle.Full,
27+
DocRootValue = DocRootPrefixActual,
28+
})
29+
{
2330
LanguageFlags = LanguageFlags.Default | LanguageFlags.CreateAst,
2431
};
2532
g.Root = root (g);

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

Lines changed: 31 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -21,12 +21,19 @@ public class SourceJavadocToXmldocParserTests : SourceJavadocToXmldocGrammarFixt
2121
public void TryParse (ParseResult parseResult)
2222
{
2323
ParseTree parseTree;
24-
var p = new SourceJavadocToXmldocParser (XmldocStyle.Full);
24+
var p = new SourceJavadocToXmldocParser (new XmldocSettings {
25+
Style = XmldocStyle.Full,
26+
DocRootValue = DocRootPrefixActual,
27+
});
2528
var n = p.TryParse (parseResult.Javadoc, null, out parseTree);
2629
Assert.IsFalse (parseTree.HasErrors (), DumpMessages (parseTree, p));
30+
var xml = GetMemberXml (n);
2731
Assert.AreEqual (parseResult.FullXml, GetMemberXml (n), $"while parsing input: ```{parseResult.Javadoc}```");
2832

29-
p = new SourceJavadocToXmldocParser (XmldocStyle.IntelliSense);
33+
p = new SourceJavadocToXmldocParser (new XmldocSettings {
34+
Style = XmldocStyle.IntelliSense,
35+
DocRootValue = DocRootPrefixActual,
36+
});
3037
n = p.TryParse (parseResult.Javadoc, null, out parseTree);
3138
Assert.IsFalse (parseTree.HasErrors (), DumpMessages (parseTree, p));
3239
Assert.AreEqual (parseResult.IntelliSenseXml, GetMemberXml (n), $"while parsing input: ```{parseResult.Javadoc}```");
@@ -168,6 +175,28 @@ more description here.</para>
168175
</member>",
169176
IntelliSenseXml = @"<member>
170177
<summary>Summary.</summary>
178+
</member>",
179+
},
180+
new ParseResult {
181+
Javadoc = @"See <a href=""http://man7.org/linux/man-pages/man2/accept.2.html"">accept(2)</a>. Insert
182+
more description here.
183+
How about another link <a href=""http://man7.org/linux/man-pages/man2/accept.2.html"">accept(2)</a>
184+
@param manifest The value of the <a
185+
href=""{@docRoot}guide/topics/manifest/manifest-element.html#vcode"">{@code
186+
android:versionCode}</a> manifest attribute.
187+
",
188+
FullXml = $@"<member>
189+
<param name=""manifest"">The value of the <see href=""{DocRootPrefixExpected}guide/topics/manifest/manifest-element.html#vcode""><c>android:versionCode</c></see> manifest attribute.</param>
190+
<summary>See <see href=""http://man7.org/linux/man-pages/man2/accept.2.html"">accept(2)</see>.</summary>
191+
<remarks>
192+
<para>See <see href=""http://man7.org/linux/man-pages/man2/accept.2.html"">accept(2)</see>. Insert
193+
more description here.
194+
How about another link <see href=""http://man7.org/linux/man-pages/man2/accept.2.html"">accept(2)</see></para>
195+
</remarks>
196+
</member>",
197+
IntelliSenseXml = $@"<member>
198+
<param name=""manifest"">The value of the <see href=""{DocRootPrefixExpected}guide/topics/manifest/manifest-element.html#vcode""><c>android:versionCode</c></see> manifest attribute.</param>
199+
<summary>See <see href=""http://man7.org/linux/man-pages/man2/accept.2.html"">accept(2)</see>.</summary>
171200
</member>",
172201
},
173202
};

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

Lines changed: 13 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,7 @@ public sealed class JavadocInfo {
2525
public XElement[] Copyright { get; set; }
2626

2727
public XmldocStyle XmldocStyle { get; set; }
28+
public string DocRootReplacement { get; set; }
2829

2930
string MemberDescription;
3031

@@ -44,13 +45,15 @@ public static JavadocInfo CreateInfo (XElement element, XmldocStyle style, bool
4445
var extras = GetExtra (element, style, declaringJniType, declaringMemberName, declaringMemberJniSignature, appendCopyrightExtra);
4546
XElement[] extra = extras.Extras;
4647
XElement[] copyright = extras.Copyright;
48+
string docRoot = extras.DocRoot;
4749

4850
if (string.IsNullOrEmpty (javadoc) && extra == null)
4951
return null;
5052

5153
var info = new JavadocInfo () {
5254
ExtraRemarks = extra,
5355
Copyright = copyright,
56+
DocRootReplacement = docRoot,
5457
Javadoc = javadoc,
5558
MemberDescription = declaringMemberName == null
5659
? declaringJniType
@@ -83,10 +86,10 @@ public static JavadocInfo CreateInfo (XElement element, XmldocStyle style, bool
8386
return (declaringJniType, declaringMemberName, declaringMemberJniSignature);
8487
}
8588

86-
static (XElement[] Extras, XElement[] Copyright) GetExtra (XElement element, XmldocStyle style, string declaringJniType, string declaringMemberName, string declaringMemberJniSignature, bool appendCopyrightExtra)
89+
static (XElement[] Extras, XElement[] Copyright, string DocRoot) GetExtra (XElement element, XmldocStyle style, string declaringJniType, string declaringMemberName, string declaringMemberJniSignature, bool appendCopyrightExtra)
8790
{
8891
if (!style.HasFlag (XmldocStyle.IntelliSenseAndExtraRemarks))
89-
return (null, null);
92+
return (null, null, null);
9093

9194
XElement javadocMetadata = null;
9295
while (element != null) {
@@ -99,10 +102,12 @@ public static JavadocInfo CreateInfo (XElement element, XmldocStyle style, bool
99102

100103
List<XElement> extra = null;
101104
IEnumerable<XElement> copyright = null;
105+
string docRoot = null;
102106
if (javadocMetadata != null) {
103107
var link = javadocMetadata.Element ("link");
104108
var urlPrefix = (string) link.Attribute ("prefix");
105109
var linkStyle = (string) link.Attribute ("style");
110+
docRoot = (string) link.Attribute ("docroot");
106111
var kind = ParseApiLinkStyle (linkStyle);
107112

108113
XElement docLink = null;
@@ -116,7 +121,7 @@ public static JavadocInfo CreateInfo (XElement element, XmldocStyle style, bool
116121
extra.AddRange (copyright);
117122
}
118123
}
119-
return (extra?.ToArray (), copyright?.ToArray ());
124+
return (extra?.ToArray (), copyright?.ToArray (), docRoot);
120125
}
121126

122127
static ApiLinkStyle ParseApiLinkStyle (string style)
@@ -147,9 +152,11 @@ public IEnumerable<XNode> ParseJavadoc ()
147152
IEnumerable<XNode> nodes = null;
148153

149154
try {
150-
var parser = new SourceJavadocToXmldocParser (XmldocStyle) {
151-
ExtraRemarks = ExtraRemarks,
152-
};
155+
var parser = new SourceJavadocToXmldocParser (new XmldocSettings {
156+
Style = XmldocStyle,
157+
ExtraRemarks = ExtraRemarks,
158+
DocRootValue = DocRootReplacement,
159+
});
153160
nodes = parser.TryParse (Javadoc, fileName: null, out tree);
154161
}
155162
catch (Exception e) {

‎tools/java-source-utils/src/main/java/com/microsoft/android/App.java

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -68,7 +68,7 @@ static void generateParamsTxt(String filename, JniPackagesInfo packages) throws
6868

6969
static void generateXml(JavaSourceUtilsOptions options, JniPackagesInfo packages) throws Throwable {
7070
try (final JavadocXmlGenerator javadocXmlGen = new JavadocXmlGenerator(options.outputJavadocXml)) {
71-
javadocXmlGen.writeCopyrightInfo(options.docCopyrightFile, options.docUrlPrefix, options.docUrlStyle);
71+
javadocXmlGen.writeCopyrightInfo(options.docCopyrightFile, options.docUrlPrefix, options.docUrlStyle, options.docRootUrl);
7272
javadocXmlGen.writePackages(packages);
7373
}
7474
}

0 commit comments

Comments
 (0)