Skip to content

Commit

Permalink
Issue #853: ignore unknown tags when generating javadoc comments.
Browse files Browse the repository at this point in the history 
	Change on 2017/05/03 by tball <tball@google.com>

-------------
Created by MOE: https://github.com/google/moe
MOE_MIGRATED_REVID=154983589
  • Loading branch information
@tomball @kstanger
tomball authored and kstanger committed May 3, 2017
1 parent 890bed3 commit 1d42342
Show file tree
Hide file tree
Showing 6 changed files with 137 additions and 88 deletions.
2 changes: 1 addition & 1 deletion translator/src/main/java/com/google/devtools/j2objc/ast/DebugASTDump.java
View file
Expand Up @@ -227,7 +227,7 @@ public boolean visit(SuperMethodReference node) {

@Override
public boolean visit(TagElement node) {
String tagName = node.getTagName();
String tagName = node.getTagKind().toString();
sb.print(' ');
sb.print(tagName != null ? tagName : "null");
return true;
Expand Down
73 changes: 52 additions & 21 deletions translator/src/main/java/com/google/devtools/j2objc/ast/TagElement.java
View file
Expand Up @@ -21,28 +21,59 @@
*/
public class TagElement extends TreeNode {

public static final String TAG_AUTHOR = "@author";
public static final String TAG_CODE = "@code";
public static final String TAG_DEPRECATED = "@deprecated";
public static final String TAG_EXCEPTION = "@exception";
public static final String TAG_LINK = "@link";
public static final String TAG_LINKPLAIN = "@linkplain";
public static final String TAG_LITERAL = "@literal";
public static final String TAG_PARAM = "@param";
public static final String TAG_RETURN = "@return";
public static final String TAG_SEE = "@see";
public static final String TAG_SINCE = "@since";
public static final String TAG_THROWS = "@throws";
public static final String TAG_VERSION = "@version";

private String tagName;
/**
* The kinds of TagElements.
*/
public enum TagKind {
AUTHOR("@author"),
CODE("@code"),
DEPRECATED("@deprecated"),
EXCEPTION("@exception"),
LINK("@link"),
LINKPLAIN("@linkplain"),
LITERAL("@literal"),
PARAM("@param"),
RETURN("@return"),
SEE("@see"),
SINCE("@since"),
THROWS("@throw"),
VERSION("@version"),

// Tag elements that don't have a tag name.
DESCRIPTION(""),
UNKNOWN("");

private final String tagName;

TagKind(String name) {
tagName = name;
}

public static TagKind parse(String tagName) {
for (TagKind tk : values()) {
if (tagName.equals(tk.tagName)) {
return tk;
}
}
return UNKNOWN;
}

@Override
public String toString() {
return tagName;
}
}

private TagKind tagKind;
private ChildList<TreeNode> fragments = ChildList.create(TreeNode.class, this);

public TagElement() {}
public TagElement() {
this.tagKind = TagKind.UNKNOWN;
}

public TagElement(TagElement other) {
super(other);
tagName = other.getTagName();
this.tagKind = other.getTagKind();
fragments.copyFrom(other.getFragments());
}

Expand All @@ -51,12 +82,12 @@ public Kind getKind() {
return Kind.TAG_ELEMENT;
}

public String getTagName() {
return tagName;
public TagKind getTagKind() {
return tagKind;
}

public TagElement setTagName(String tagName) {
this.tagName = tagName;
public TagElement setTagKind(TagKind tagKind) {
this.tagKind = tagKind;
return this;
}

Expand Down
102 changes: 53 additions & 49 deletions translator/src/main/java/com/google/devtools/j2objc/gen/JavadocGenerator.java
View file
Expand Up @@ -19,17 +19,16 @@
import com.google.devtools.j2objc.ast.Name;
import com.google.devtools.j2objc.ast.SimpleName;
import com.google.devtools.j2objc.ast.TagElement;
import com.google.devtools.j2objc.ast.TagElement.TagKind;
import com.google.devtools.j2objc.ast.TextElement;
import com.google.devtools.j2objc.ast.TreeNode;
import com.google.devtools.j2objc.util.ElementUtil;
import com.google.devtools.j2objc.util.NameTable;

import java.text.BreakIterator;
import java.util.HashMap;
import java.util.List;
import java.util.Locale;
import java.util.Map;

import javax.lang.model.element.Element;
import javax.lang.model.element.VariableElement;

Expand Down Expand Up @@ -85,8 +84,7 @@ private void printDocComment(Javadoc javadoc) {

List<TagElement> tags = javadoc.getTags();
for (TagElement tag : tags) {
if (tag.getTagName() == null) {
// Description section.
if (tag.getTagKind() == TagKind.DESCRIPTION) {
String description = printTagFragments(tag.getFragments());

// Extract first sentence from description.
Expand Down Expand Up @@ -126,61 +124,67 @@ private void printDocLine(String line) {
}

private String printTag(TagElement tag) {
String tagName = tag.getTagName();
if (tagName != null) {
// Remove @param tags for parameterized types, such as "@param <T> the type".
// TODO(tball): update when (if) Xcode supports Objective C type parameter documenting.
if (tagName.equals(TagElement.TAG_PARAM) && hasTypeParam(tag.getFragments())) {
return "";
}
TagKind kind = tag.getTagKind();

// Xcode 7 compatible tags.
if (tagName.equals(TagElement.TAG_AUTHOR)
|| tagName.equals(TagElement.TAG_EXCEPTION)
|| tagName.equals(TagElement.TAG_PARAM)
|| tagName.equals(TagElement.TAG_RETURN)
|| tagName.equals(TagElement.TAG_SINCE)
|| tagName.equals(TagElement.TAG_THROWS)
|| tagName.equals(TagElement.TAG_VERSION)) {
// Skip
String comment = printTagFragments(tag.getFragments()).trim();
return comment.isEmpty() ? "" : String.format("%s %s", tagName, comment);
}
// Remove @param tags for parameterized types, such as "@param <T> the type".
// TODO(tball): update when (if) Xcode supports Objective C type parameter documenting.
if (kind == TagKind.PARAM && hasTypeParam(tag.getFragments())) {
return "";
}

if (tagName.equals(TagElement.TAG_DEPRECATED)) {
// Deprecated annotation translated instead.
return "";
}
// Xcode 7 compatible tags.
if (kind == TagKind.AUTHOR
|| kind == TagKind.EXCEPTION
|| kind == TagKind.PARAM
|| kind == TagKind.RETURN
|| kind == TagKind.SINCE
|| kind == TagKind.THROWS
|| kind == TagKind.VERSION) {
// Skip
String comment = printTagFragments(tag.getFragments()).trim();
return comment.isEmpty() ? "" : String.format("%s %s", kind, comment);
}

if (tagName.equals(TagElement.TAG_SEE)) {
String comment = printTagFragments(tag.getFragments()).trim();
return comment.isEmpty() ? "" : "- seealso: " + comment;
}
if (kind == TagKind.DEPRECATED) {
// Deprecated annotation translated instead.
return "";
}

if (tagName.equals(TagElement.TAG_CODE)) {
String text = printTagFragments(tag.getFragments());
if (spanningPreTag) {
return text;
}
return String.format("<code>%s</code>", text.trim());
}
if (kind == TagKind.SEE) {
String comment = printTagFragments(tag.getFragments()).trim();
return comment.isEmpty() ? "" : "- seealso: " + comment;
}

if (tagName.equals(TagElement.TAG_LINK)) {
return formatLinkTag(tag, "<code>%s</code>");
if (kind == TagKind.CODE) {
String text = printTagFragments(tag.getFragments());
if (spanningPreTag) {
return text;
}
return String.format("<code>%s</code>", text.trim());
}

if (tagName.equals(TagElement.TAG_LINKPLAIN)) {
return formatLinkTag(tag, "%s");
}
if (kind == TagKind.LINK) {
return formatLinkTag(tag, "<code>%s</code>");
}

if (tagName.equals(TagElement.TAG_LITERAL)) {
String text = printTagFragments(tag.getFragments()).trim();
if (spanningPreTag) {
return text;
}
return escapeHtmlText(text);
if (kind == TagKind.LINKPLAIN) {
return formatLinkTag(tag, "%s");
}

if (kind == TagKind.LITERAL) {
String text = printTagFragments(tag.getFragments()).trim();
if (spanningPreTag) {
return text;
}
return escapeHtmlText(text);
}

if (kind == TagKind.UNKNOWN) {
// Skip unknown tags. If --doc-comment-warnings was specified, a warning was
// already created.
return "";
}

return printTagFragments(tag.getFragments());
}

Expand Down
35 changes: 19 additions & 16 deletions translator/src/main/java/com/google/devtools/j2objc/javac/JavadocConverter.java
View file
Expand Up @@ -20,6 +20,7 @@
import com.google.devtools.j2objc.ast.SimpleName;
import com.google.devtools.j2objc.ast.SourcePosition;
import com.google.devtools.j2objc.ast.TagElement;
import com.google.devtools.j2objc.ast.TagElement.TagKind;
import com.google.devtools.j2objc.ast.TextElement;
import com.google.devtools.j2objc.ast.TreeNode;
import com.google.devtools.j2objc.util.ErrorUtil;
Expand Down Expand Up @@ -95,7 +96,9 @@ static Javadoc convertJavadoc(Element element, String source, JavacEnvironment e
JavadocConverter converter = new JavadocConverter(element, docComment, source, docTrees,
path.getCompilationUnit(), reportWarnings);
Javadoc result = new Javadoc();
TagElement newTag = new TagElement(); // First tag has no name.

// First tag is the description.
TagElement newTag = new TagElement().setTagKind(TagElement.TagKind.DESCRIPTION);
converter.scan(docComment.getFirstSentence(), newTag);
converter.scan(docComment.getBody(), newTag);
if (!newTag.getFragments().isEmpty()) {
Expand All @@ -118,7 +121,7 @@ static Javadoc convertJavadoc(Element element, String source, JavacEnvironment e

@Override
public Void visitAuthor(AuthorTree node, TagElement tag) {
setTagValues(tag, TagElement.TAG_AUTHOR, node, node.getName());
setTagValues(tag, TagElement.TagKind.AUTHOR, node, node.getName());
return null;
}

Expand All @@ -130,7 +133,7 @@ public Void visitComment(CommentTree node, TagElement tag) {

@Override
public Void visitDeprecated(DeprecatedTree node, TagElement tag) {
setTagValues(tag, TagElement.TAG_DEPRECATED, node, node.getBody());
setTagValues(tag, TagElement.TagKind.DEPRECATED, node, node.getBody());
return null;
}

Expand Down Expand Up @@ -173,7 +176,7 @@ public Void visitIdentifier(IdentifierTree node, TagElement tag) {

@Override
public Void visitLink(LinkTree node, TagElement tag) {
TagElement newTag = new TagElement().setTagName("@" + node.getTagName());
TagElement newTag = new TagElement().setTagKind(TagKind.parse("@" + node.getTagName()));
setPos(node, newTag);
if (node.getLabel().isEmpty()) {
scan(node.getReference(), newTag);
Expand All @@ -187,8 +190,8 @@ public Void visitLink(LinkTree node, TagElement tag) {
@Override
public Void visitLiteral(LiteralTree node, TagElement tag) {
TagElement newTag = new TagElement();
String tagName = node.getKind() == DocTree.Kind.CODE ? "@code" : "@literal";
setTagValues(newTag, tagName, node, node.getBody());
TagKind tagKind = node.getKind() == DocTree.Kind.CODE ? TagKind.CODE : TagKind.LITERAL;
setTagValues(newTag, tagKind, node, node.getBody());
tag.addFragment(newTag);
return null;
}
Expand All @@ -201,7 +204,7 @@ public Void visitParam(ParamTree node, TagElement tag) {
}
List<? extends VariableElement> params = element instanceof ExecutableElement
? ((ExecutableElement) element).getParameters() : Collections.emptyList();
tag.setTagName(TagElement.TAG_PARAM);
tag.setTagKind(TagElement.TagKind.PARAM);
String name = identifier.toString();
VariableElement param = null;
for (VariableElement p : params) {
Expand Down Expand Up @@ -249,23 +252,23 @@ public Void visitReference(ReferenceTree node, TagElement tag) {

@Override
public Void visitReturn(ReturnTree node, TagElement tag) {
tag.setTagName(TagElement.TAG_RETURN);
tag.setTagKind(TagElement.TagKind.RETURN);
setPos(node, tag);
scan(node.getDescription(), tag);
return null;
}

@Override
public Void visitSee(SeeTree node, TagElement tag) {
tag.setTagName(TagElement.TAG_SEE);
tag.setTagKind(TagElement.TagKind.SEE);
setPos(node, tag);
scan(node.getReference(), tag);
return null;
}

@Override
public Void visitSince(SinceTree node, TagElement tag) {
setTagValues(tag, TagElement.TAG_SINCE, node, node.getBody());
setTagValues(tag, TagElement.TagKind.SINCE, node, node.getBody());
return null;
}

Expand Down Expand Up @@ -299,31 +302,31 @@ public Void visitText(TextTree node, TagElement tag) {

@Override
public Void visitThrows(ThrowsTree node, TagElement tag) {
setTagValues(tag, TagElement.TAG_THROWS, node, node.getExceptionName());
setTagValues(tag, TagElement.TagKind.THROWS, node, node.getExceptionName());
scan(node.getDescription(), tag);
return null;
}

@Override
public Void visitVersion(VersionTree node, TagElement tag) {
setTagValues(tag, TagElement.TAG_VERSION, node, node.getBody());
setTagValues(tag, TagElement.TagKind.VERSION, node, node.getBody());
return null;
}

/**
* Updates a tag element with values from the javadoc node.
*/
private TagElement setTagValues(TagElement tag, String tagName, DocTree javadocNode,
private TagElement setTagValues(TagElement tag, TagKind tagKind, DocTree javadocNode,
DocTree body) {
tag.setTagName(tagName);
tag.setTagKind(tagKind);
setPos(javadocNode, tag);
scan(body, tag);
return tag;
}

private TagElement setTagValues(TagElement tag, String tagName, DocTree javadocNode,
private TagElement setTagValues(TagElement tag, TagKind tagKind, DocTree javadocNode,
List<? extends DocTree> body) {
tag.setTagName(tagName);
tag.setTagKind(tagKind);
setPos(javadocNode, tag);
scan(body, tag);
return tag;
Expand Down
3 changes: 2 additions & 1 deletion translator/src/main/java/com/google/devtools/j2objc/jdt/TreeConverter.java
View file
Expand Up @@ -99,6 +99,7 @@
import com.google.devtools.j2objc.ast.SwitchStatement;
import com.google.devtools.j2objc.ast.SynchronizedStatement;
import com.google.devtools.j2objc.ast.TagElement;
import com.google.devtools.j2objc.ast.TagElement.TagKind;
import com.google.devtools.j2objc.ast.TextElement;
import com.google.devtools.j2objc.ast.ThisExpression;
import com.google.devtools.j2objc.ast.ThrowStatement;
Expand Down Expand Up @@ -1188,7 +1189,7 @@ private static TreeNode convertSuperMethodInvocation(

private static TreeNode convertTagElement(org.eclipse.jdt.core.dom.TagElement node) {
TagElement newNode = new TagElement()
.setTagName(node.getTagName());
.setTagKind(TagKind.parse(node.getTagName()));
for (Object fragment : node.fragments()) {
newNode.addFragment(TreeConverter.convert(fragment));
}
Expand Down

0 comments on commit 1d42342

Please sign in to comment.