Skip to content

[generator] Add --with-javadoc-xml=FILE support. #687

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Jan 4, 2021
Merged

[generator] Add --with-javadoc-xml=FILE support. #687

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 28 additions & 0 deletions src/Java.Interop.Tools.JavaSource/Java.Interop.Tools.JavaSource/IronyExtensions.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
using System;
using System.Collections.Generic;
using System.IO;
using System.Linq;
using System.Text;
using Irony.Ast;
using Irony.Parsing;

namespace Java.Interop.Tools.JavaSource {

static class IronyExtensions {

public static void MakePlusRule (this NonTerminal star, Grammar grammar, BnfTerm delimiter)
{
star.Rule = grammar.MakePlusRule (star, delimiter);
}

public static void MakeStarRule (this NonTerminal star, Grammar grammar, BnfTerm delimiter, BnfTerm of)
{
star.Rule = grammar.MakeStarRule (star, delimiter, of);
}

public static void MakeStarRule (this NonTerminal star, Grammar grammar, BnfTerm of)
{
star.Rule = grammar.MakeStarRule (star, of);
}
}
}
31 changes: 31 additions & 0 deletions src/Java.Interop.Tools.JavaSource/Java.Interop.Tools.JavaSource/JavadocInfo.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,31 @@
using System;
using System.Collections.Generic;
using System.Collections.ObjectModel;
using System.IO;
using System.Linq;
using System.Xml.Linq;

using Irony.Ast;
using Irony.Parsing;

namespace Java.Interop.Tools.JavaSource {

sealed class JavadocInfo {
public readonly ICollection<XNode> Exceptions = new Collection<XNode> ();
public readonly ICollection<XNode> Extra = new Collection<XNode> ();
public readonly ICollection<XNode> Remarks = new Collection<XNode> ();
public readonly ICollection<XNode> Parameters = new Collection<XNode> ();
public readonly ICollection<XNode> Returns = new Collection<XNode> ();

public override string ToString ()
{
return new XElement ("Javadoc",
new XElement (nameof (Parameters), Parameters),
new XElement (nameof (Remarks), Remarks),
new XElement (nameof (Returns), Returns),
new XElement (nameof (Exceptions), Exceptions),
new XElement (nameof (Extra), Extra))
.ToString ();
}
}
}
239 changes: 239 additions & 0 deletions ...avaSource/Java.Interop.Tools.JavaSource/SourceJavadocToXmldocGrammar.BlockTagsBnfTerms.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,239 @@
using System;
using System.Collections.Generic;
using System.IO;
using System.Linq;
using System.Xml.Linq;

using Irony.Ast;
using Irony.Parsing;

namespace Java.Interop.Tools.JavaSource {

public partial class SourceJavadocToXmldocGrammar {

// https://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html#javadoctags
public class BlockTagsBnfTerms {

internal BlockTagsBnfTerms ()
{
}

internal void CreateRules (SourceJavadocToXmldocGrammar grammar)
{
AllBlockTerms.Rule = AuthorDeclaration
| ApiSinceDeclaration
| DeprecatedDeclaration
| DeprecatedSinceDeclaration
| ExceptionDeclaration
| ParamDeclaration
| ReturnDeclaration
| SeeDeclaration
| SerialDataDeclaration
| SerialFieldDeclaration
| SinceDeclaration
| ThrowsDeclaration
| UnknownTagDeclaration
| VersionDeclaration
;
BlockValue.Rule = grammar.HtmlTerms.ParsedCharacterData
| grammar.HtmlTerms.InlineDeclaration
;
BlockValues.MakePlusRule (grammar, BlockValue);

AuthorDeclaration.Rule = "@author" + BlockValues;
AuthorDeclaration.AstConfig.NodeCreator = (context, parseNode) => {
if (!grammar.ShouldImport (ImportJavadoc.AuthorTag))
return;
// Ignore; not sure how best to convert to Xmldoc
FinishParse (context, parseNode);
};

ApiSinceDeclaration.Rule = "@apiSince" + BlockValues;
ApiSinceDeclaration.AstConfig.NodeCreator = (context, parseNode) => {
if (!grammar.ShouldImport (ImportJavadoc.SinceTag)) {
return;
}
var p = new XElement ("para", "Added in API level ", AstNodeToXmlContent (parseNode.ChildNodes [1]), ".");
FinishParse (context, parseNode).Remarks.Add (p);
parseNode.AstNode = p;
};

DeprecatedDeclaration.Rule = "@deprecated" + BlockValues;
DeprecatedDeclaration.AstConfig.NodeCreator = (context, parseNode) => {
if (!grammar.ShouldImport (ImportJavadoc.DeprecatedTag)) {
return;
}
var p = new XElement ("para", "This member is deprecated. ", AstNodeToXmlContent (parseNode.ChildNodes [1]));
FinishParse (context, parseNode).Remarks.Add (p);
parseNode.AstNode = p;
};

DeprecatedSinceDeclaration.Rule = "@deprecatedSince" + BlockValues;
DeprecatedSinceDeclaration.AstConfig.NodeCreator = (context, parseNode) => {
if (!grammar.ShouldImport (ImportJavadoc.DeprecatedTag)) {
return;
}
var p = new XElement ("para", "This member was deprecated in API level ", AstNodeToXmlContent (parseNode.ChildNodes [1]), ".");
FinishParse (context, parseNode).Remarks.Add (p);
parseNode.AstNode = p;
};

var nonSpaceTerm = new RegexBasedTerminal ("[^ ]", "[^ ]+") {
AstConfig = new AstNodeConfig {
NodeCreator = (context, parseNode) => parseNode.AstNode = parseNode.Token.Value,
},
};

ExceptionDeclaration.Rule = "@exception" + nonSpaceTerm + BlockValues;
ExceptionDeclaration.AstConfig.NodeCreator = (context, parseNode) => {
if (!grammar.ShouldImport (ImportJavadoc.ExceptionTag)) {
return;
}
// 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;
};

ParamDeclaration.Rule = "@param" + nonSpaceTerm + BlockValues;
ParamDeclaration.AstConfig.NodeCreator = (context, parseNode) => {
if (!grammar.ShouldImport (ImportJavadoc.ParamTag)) {
return;
}
var p = new XElement ("param",
new XAttribute ("name", string.Join ("", AstNodeToXmlContent (parseNode.ChildNodes [1]))),
AstNodeToXmlContent (parseNode.ChildNodes [2]));
FinishParse (context, parseNode).Parameters.Add (p);
parseNode.AstNode = p;
};

ReturnDeclaration.Rule = "@return" + BlockValues;
ReturnDeclaration.AstConfig.NodeCreator = (context, parseNode) => {
if (!grammar.ShouldImport (ImportJavadoc.ReturnTag)) {
return;
}
var r = new XElement ("returns",
AstNodeToXmlContent (parseNode.ChildNodes [1]));
FinishParse (context, parseNode).Returns.Add (r);
parseNode.AstNode = r;
};

SeeDeclaration.Rule = "@see" + BlockValues;
SeeDeclaration.AstConfig.NodeCreator = (context, parseNode) => {
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
var e = new XElement ("seealso",
new XAttribute ("cref", string.Join ("", AstNodeToXmlContent (parseNode.ChildNodes [1]))));
FinishParse (context, parseNode).Extra.Add (e);
parseNode.AstNode = e;
};

SinceDeclaration.Rule = "@since" + BlockValues;
SinceDeclaration.AstConfig.NodeCreator = (context, parseNode) => {
if (!grammar.ShouldImport (ImportJavadoc.SinceTag)) {
return;
}
var p = new XElement ("para", "Added in ", AstNodeToXmlContent (parseNode.ChildNodes [1]), ".");
FinishParse (context, parseNode).Remarks.Add (p);
parseNode.AstNode = p;
};

ThrowsDeclaration.Rule = "@throws" + nonSpaceTerm + BlockValues;
ThrowsDeclaration.AstConfig.NodeCreator = (context, parseNode) => {
if (!grammar.ShouldImport (ImportJavadoc.ExceptionTag)) {
return;
}
// 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;
};

// Ignore serialization informatino
SerialDeclaration.Rule = "@serial" + BlockValues;
SerialDeclaration.AstConfig.NodeCreator = (context, parseNode) => {
if (!grammar.ShouldImport (ImportJavadoc.SerialTag)) {
return;
}
FinishParse (context, parseNode);
};

SerialDataDeclaration.Rule = "@serialData" + BlockValues;
SerialDataDeclaration.AstConfig.NodeCreator = (context, parseNode) => {
if (!grammar.ShouldImport (ImportJavadoc.SerialTag)) {
return;
}
FinishParse (context, parseNode);
};

SerialFieldDeclaration.Rule = "@serialField" + BlockValues;
SerialFieldDeclaration.AstConfig.NodeCreator = (context, parseNode) => {
if (!grammar.ShouldImport (ImportJavadoc.SerialTag)) {
return;
}
FinishParse (context, parseNode);
};

var unknownTagTerminal = new RegexBasedTerminal ("@[unknown]", @"@\S+") {
Priority = TerminalPriority.Low,
};
unknownTagTerminal.AstConfig.NodeCreator = (context, parseNode) =>
parseNode.AstNode = parseNode.Token.Value.ToString ();


UnknownTagDeclaration.Rule = unknownTagTerminal + BlockValues;
UnknownTagDeclaration.AstConfig.NodeCreator = (context, parseNode) => {
if (!grammar.ShouldImport (ImportJavadoc.Remarks)) {
return;
}
Console.WriteLine ($"# Unsupported @block-tag value: {parseNode.ChildNodes [0].AstNode}");
FinishParse (context, parseNode);
};

// Ignore Version
VersionDeclaration.Rule = "@version" + BlockValues;
VersionDeclaration.AstConfig.NodeCreator = (context, parseNode) => {
if (!grammar.ShouldImport (ImportJavadoc.VersionTag)) {
return;
}
FinishParse (context, parseNode);
};
}

public readonly NonTerminal AllBlockTerms = new NonTerminal (nameof (AllBlockTerms), ConcatChildNodes);

public readonly Terminal Cdata = new CharacterDataTerminal ("#CDATA", preserveLeadingWhitespace: true);
/*
public readonly Terminal Cdata = new RegexBasedTerminal (nameof (BlockValue), "[^<]*") {
AstConfig = new AstNodeConfig {
NodeCreator = (context, parseNode) => parseNode.AstNode = parseNode.Token.Value.ToString (),
},
};
*/

public readonly NonTerminal BlockValue = new NonTerminal (nameof (BlockValue), ConcatChildNodes);
public readonly NonTerminal BlockValues = new NonTerminal (nameof (BlockValues), ConcatChildNodes);
public readonly NonTerminal AuthorDeclaration = new NonTerminal (nameof (AuthorDeclaration));
public readonly NonTerminal ApiSinceDeclaration = new NonTerminal (nameof (ApiSinceDeclaration));
public readonly NonTerminal DeprecatedDeclaration = new NonTerminal (nameof (DeprecatedDeclaration));
public readonly NonTerminal DeprecatedSinceDeclaration = new NonTerminal (nameof (DeprecatedSinceDeclaration));
public readonly NonTerminal ExceptionDeclaration = new NonTerminal (nameof (ExceptionDeclaration));
public readonly NonTerminal ParamDeclaration = new NonTerminal (nameof (ParamDeclaration));
public readonly NonTerminal ReturnDeclaration = new NonTerminal (nameof (ReturnDeclaration));
public readonly NonTerminal SeeDeclaration = new NonTerminal (nameof (SeeDeclaration));
public readonly NonTerminal SerialDeclaration = new NonTerminal (nameof (SerialDeclaration));
public readonly NonTerminal SerialDataDeclaration = new NonTerminal (nameof (SerialDataDeclaration));
public readonly NonTerminal SerialFieldDeclaration = new NonTerminal (nameof (SerialFieldDeclaration));
public readonly NonTerminal SinceDeclaration = new NonTerminal (nameof (SinceDeclaration));
public readonly NonTerminal ThrowsDeclaration = new NonTerminal (nameof (ThrowsDeclaration));
public readonly NonTerminal UnknownTagDeclaration = new NonTerminal (nameof (UnknownTagDeclaration));
public readonly NonTerminal VersionDeclaration = new NonTerminal (nameof (VersionDeclaration));
}
}
}
Loading