diff --git a/pmd-java/etc/grammar/Java.jjt b/pmd-java/etc/grammar/Java.jjt index 605e9528fe..81427c1028 100644 --- a/pmd-java/etc/grammar/Java.jjt +++ b/pmd-java/etc/grammar/Java.jjt @@ -602,7 +602,7 @@ MORE : SPECIAL_TOKEN : { - { comments.add(new FormalComment(matchedToken)); } : DEFAULT + { comments.add(new JavadocComment(matchedToken)); } : DEFAULT } diff --git a/pmd-java/src/main/java/net/sourceforge/pmd/lang/java/ast/Comment.java b/pmd-java/src/main/java/net/sourceforge/pmd/lang/java/ast/Comment.java index 5349bb0fbe..50ce08960f 100644 --- a/pmd-java/src/main/java/net/sourceforge/pmd/lang/java/ast/Comment.java +++ b/pmd-java/src/main/java/net/sourceforge/pmd/lang/java/ast/Comment.java @@ -18,6 +18,9 @@ import net.sourceforge.pmd.util.document.Reportable; * Wraps a comment token to provide some utilities. * This is not a node, it's not part of the tree anywhere, * just convenient. + * + *

This class represents any kind of comment. A specialized subclass + * provides more API for Javadoc comments, see {@link JavadocComment}. */ public class Comment implements Reportable { //TODO maybe move part of this into pmd core diff --git a/pmd-java/src/main/java/net/sourceforge/pmd/lang/java/ast/CommentAssignmentPass.java b/pmd-java/src/main/java/net/sourceforge/pmd/lang/java/ast/CommentAssignmentPass.java index 3457334db5..13b3d50c19 100644 --- a/pmd-java/src/main/java/net/sourceforge/pmd/lang/java/ast/CommentAssignmentPass.java +++ b/pmd-java/src/main/java/net/sourceforge/pmd/lang/java/ast/CommentAssignmentPass.java @@ -19,18 +19,19 @@ import net.sourceforge.pmd.util.document.FileLocation; final class CommentAssignmentPass { - private static final SimpleDataKey FORMAL_COMMENT_KEY = DataMap.simpleDataKey("java.comment"); + private static final SimpleDataKey FORMAL_COMMENT_KEY = DataMap.simpleDataKey("java.comment"); private CommentAssignmentPass() { // utility class } - static @Nullable FormalComment getComment(JavadocCommentOwner commentOwner) { + static @Nullable JavadocComment getComment(JavadocCommentOwner commentOwner) { return commentOwner.getUserMap().get(CommentAssignmentPass.FORMAL_COMMENT_KEY); } - private static void setComment(JavadocCommentOwner commentableNode, FormalComment comment) { + private static void setComment(JavadocCommentOwner commentableNode, JavadocComment comment) { commentableNode.getUserMap().set(FORMAL_COMMENT_KEY, comment); + comment.setOwner(commentableNode); } public static void assignCommentsToDeclarations(ASTCompilationUnit root) { @@ -45,11 +46,11 @@ final class CommentAssignmentPass { for (JavaccToken maybeComment : GenericToken.previousSpecials(firstToken)) { if (maybeComment.kind == JavaTokenKinds.FORMAL_COMMENT) { - FormalComment comment = new FormalComment(maybeComment); + JavadocComment comment = new JavadocComment(maybeComment); // deduplicate the comment int idx = Collections.binarySearch(comments, comment, Comparator.comparing(Comment::getReportLocation, FileLocation.COORDS_COMPARATOR)); assert idx >= 0 : "Formal comment not found? " + comment; - comment = (FormalComment) comments.get(idx); + comment = (JavadocComment) comments.get(idx); setComment(commentableNode, comment); continue outer; diff --git a/pmd-java/src/main/java/net/sourceforge/pmd/lang/java/ast/FormalComment.java b/pmd-java/src/main/java/net/sourceforge/pmd/lang/java/ast/JavadocComment.java similarity index 70% rename from pmd-java/src/main/java/net/sourceforge/pmd/lang/java/ast/FormalComment.java rename to pmd-java/src/main/java/net/sourceforge/pmd/lang/java/ast/JavadocComment.java index 77d9afb4dc..99b4378c38 100644 --- a/pmd-java/src/main/java/net/sourceforge/pmd/lang/java/ast/FormalComment.java +++ b/pmd-java/src/main/java/net/sourceforge/pmd/lang/java/ast/JavadocComment.java @@ -9,13 +9,13 @@ import org.checkerframework.checker.nullness.qual.Nullable; import net.sourceforge.pmd.lang.ast.impl.javacc.JavaccToken; /** - * A wrapper for Javadoc {@link Comment}s. + * A {@link Comment} that has Javadoc content. */ -public class FormalComment extends Comment { +public final class JavadocComment extends Comment { private JavadocCommentOwner owner; - public FormalComment(JavaccToken t) { + JavadocComment(JavaccToken t) { super(t); assert t.kind == JavaTokenKinds.FORMAL_COMMENT; } @@ -24,6 +24,10 @@ public class FormalComment extends Comment { this.owner = owner; } + /** + * Returns the owner of this comment. Null if this comment is + * misplaced. + */ public @Nullable JavadocCommentOwner getOwner() { return owner; } diff --git a/pmd-java/src/main/java/net/sourceforge/pmd/lang/java/ast/JavadocCommentOwner.java b/pmd-java/src/main/java/net/sourceforge/pmd/lang/java/ast/JavadocCommentOwner.java index 32d32af77e..b6cee1615c 100644 --- a/pmd-java/src/main/java/net/sourceforge/pmd/lang/java/ast/JavadocCommentOwner.java +++ b/pmd-java/src/main/java/net/sourceforge/pmd/lang/java/ast/JavadocCommentOwner.java @@ -16,7 +16,7 @@ public interface JavadocCommentOwner extends JavaNode { * Returns the javadoc comment that applies to this declaration. If * there is none, returns null. */ - default @Nullable FormalComment getJavadocComment() { + default @Nullable JavadocComment getJavadocComment() { return CommentAssignmentPass.getComment(this); } diff --git a/pmd-java/src/main/java/net/sourceforge/pmd/lang/java/rule/codestyle/UnnecessaryImportRule.java b/pmd-java/src/main/java/net/sourceforge/pmd/lang/java/rule/codestyle/UnnecessaryImportRule.java index d1a7294ec5..2de392a30c 100644 --- a/pmd-java/src/main/java/net/sourceforge/pmd/lang/java/rule/codestyle/UnnecessaryImportRule.java +++ b/pmd-java/src/main/java/net/sourceforge/pmd/lang/java/rule/codestyle/UnnecessaryImportRule.java @@ -23,8 +23,8 @@ import net.sourceforge.pmd.lang.java.ast.ASTPrimaryExpression; import net.sourceforge.pmd.lang.java.ast.ASTPrimaryPrefix; import net.sourceforge.pmd.lang.java.ast.ASTPrimarySuffix; import net.sourceforge.pmd.lang.java.ast.Comment; -import net.sourceforge.pmd.lang.java.ast.FormalComment; import net.sourceforge.pmd.lang.java.ast.JavaNode; +import net.sourceforge.pmd.lang.java.ast.JavadocComment; import net.sourceforge.pmd.lang.java.ast.TypeNode; import net.sourceforge.pmd.lang.java.ast.internal.ImportWrapper; import net.sourceforge.pmd.lang.java.ast.internal.PrettyPrintingUtil; @@ -97,7 +97,7 @@ public class UnnecessaryImportRule extends AbstractJavaRule { return; } for (Comment comment : node.getComments()) { - if (!(comment instanceof FormalComment)) { + if (!(comment instanceof JavadocComment)) { continue; } for (Pattern p : PATTERNS) { diff --git a/pmd-java/src/test/java/net/sourceforge/pmd/lang/java/ast/CommentAssignmentTest.java b/pmd-java/src/test/java/net/sourceforge/pmd/lang/java/ast/CommentAssignmentTest.java index 1e3bb694aa..bc4849d02d 100644 --- a/pmd-java/src/test/java/net/sourceforge/pmd/lang/java/ast/CommentAssignmentTest.java +++ b/pmd-java/src/test/java/net/sourceforge/pmd/lang/java/ast/CommentAssignmentTest.java @@ -39,7 +39,7 @@ public class CommentAssignmentTest extends BaseNonParserTest { comment = node.getComments().get(1); assertFalse(comment.isSingleLine()); assertTrue(comment.hasJavadocContent()); - assertThat(comment, instanceOf(FormalComment.class)); + assertThat(comment, instanceOf(JavadocComment.class)); assertEquals("a formal comment with blank lines", StringUtils.join(comment.filteredLines(), ' ')); } diff --git a/pmd-java/src/test/java/net/sourceforge/pmd/lang/java/ast/ParserCornersTest.java b/pmd-java/src/test/java/net/sourceforge/pmd/lang/java/ast/ParserCornersTest.java index 939ae31248..6430c1c8c1 100644 --- a/pmd-java/src/test/java/net/sourceforge/pmd/lang/java/ast/ParserCornersTest.java +++ b/pmd-java/src/test/java/net/sourceforge/pmd/lang/java/ast/ParserCornersTest.java @@ -40,7 +40,7 @@ public class ParserCornersTest extends BaseJavaTreeDumpTest { @Test public void testInvalidUnicodeEscape() { expect.expect(MalformedSourceException.class); // previously Error - expect.expectMessage("Source format error in file x/filename.java at line 1, column 1: Invalid unicode escape"); + expect.expectMessage("Source format error in file 'x/filename.java' at line 1, column 1: Invalid unicode escape"); java.parse("\\u00k0", null, "x/filename.java"); }