1 | // License: GPL. For details, see LICENSE file.
|
---|
2 | package org.openstreetmap.josm;
|
---|
3 |
|
---|
4 | import com.puppycrawl.tools.checkstyle.JavadocDetailNodeParser;
|
---|
5 | import com.puppycrawl.tools.checkstyle.api.AbstractCheck;
|
---|
6 | import com.puppycrawl.tools.checkstyle.api.DetailAST;
|
---|
7 | import com.puppycrawl.tools.checkstyle.api.DetailNode;
|
---|
8 | import com.puppycrawl.tools.checkstyle.api.JavadocTokenTypes;
|
---|
9 | import com.puppycrawl.tools.checkstyle.api.TokenTypes;
|
---|
10 | import com.puppycrawl.tools.checkstyle.utils.JavadocUtils;
|
---|
11 |
|
---|
12 | /**
|
---|
13 | * Checks that there is Javadoc for every top level class, interface or enum.
|
---|
14 | */
|
---|
15 | public class TopLevelJavadocCheck extends AbstractCheck
|
---|
16 | {
|
---|
17 | private boolean foundTopLevelClass;
|
---|
18 |
|
---|
19 | @Override
|
---|
20 | public int[] getDefaultTokens()
|
---|
21 | {
|
---|
22 | return new int[]{TokenTypes.CLASS_DEF, TokenTypes.INTERFACE_DEF, TokenTypes.ENUM_DEF};
|
---|
23 | }
|
---|
24 |
|
---|
25 | @Override
|
---|
26 | public boolean isCommentNodesRequired() {
|
---|
27 | return true;
|
---|
28 | }
|
---|
29 |
|
---|
30 | @Override
|
---|
31 | public void beginTree(DetailAST rootAST) {
|
---|
32 | foundTopLevelClass = false;
|
---|
33 | }
|
---|
34 |
|
---|
35 | @Override
|
---|
36 | public void finishTree(DetailAST rootAST) {
|
---|
37 | if (!foundTopLevelClass) {
|
---|
38 | this.log(rootAST.getLineNo(), "assertion failure: unable to find toplevel class or interface");
|
---|
39 | }
|
---|
40 | }
|
---|
41 |
|
---|
42 | private boolean hasJavadoc(DetailAST ast) {
|
---|
43 | DetailAST blockCommentBegin = ast.findFirstToken(TokenTypes.BLOCK_COMMENT_BEGIN);
|
---|
44 | if (blockCommentBegin == null) {
|
---|
45 | DetailAST modifiers = ast.findFirstToken(TokenTypes.MODIFIERS);
|
---|
46 | if (modifiers == null)
|
---|
47 | return false;
|
---|
48 | blockCommentBegin = modifiers.findFirstToken(TokenTypes.BLOCK_COMMENT_BEGIN);
|
---|
49 | if (blockCommentBegin == null) {
|
---|
50 | DetailAST annotation = modifiers.findFirstToken(TokenTypes.ANNOTATION);
|
---|
51 | if (annotation == null)
|
---|
52 | return false;
|
---|
53 | blockCommentBegin = annotation.findFirstToken(TokenTypes.BLOCK_COMMENT_BEGIN);
|
---|
54 | if (blockCommentBegin == null)
|
---|
55 | return false;
|
---|
56 | }
|
---|
57 | }
|
---|
58 | if (!JavadocUtils.isJavadocComment(blockCommentBegin))
|
---|
59 | return false;
|
---|
60 | DetailNode javadocTree = new JavadocDetailNodeParser().parseJavadocAsDetailNode(blockCommentBegin).getTree();
|
---|
61 | return hasProperText(javadocTree);
|
---|
62 | }
|
---|
63 |
|
---|
64 | private boolean hasProperText(DetailNode javadoc) {
|
---|
65 | for (DetailNode child : javadoc.getChildren()) {
|
---|
66 | if (child.getType() == JavadocTokenTypes.TEXT) {
|
---|
67 | if (!child.getText().trim().isEmpty())
|
---|
68 | return true;
|
---|
69 | } else if (child.getType() == JavadocTokenTypes.HTML_ELEMENT) {
|
---|
70 | return true;
|
---|
71 | }
|
---|
72 | }
|
---|
73 | return false;
|
---|
74 | }
|
---|
75 |
|
---|
76 | @Override
|
---|
77 | public void visitToken(DetailAST ast)
|
---|
78 | {
|
---|
79 | DetailAST parent = ast.getParent();
|
---|
80 | if (parent == null || parent.getType() == TokenTypes.EOF) {
|
---|
81 | foundTopLevelClass = true;
|
---|
82 | if (!hasJavadoc(ast)) {
|
---|
83 | this.log(ast.getLineNo(), "no/incomplete Javadoc for top level class or interface");
|
---|
84 | }
|
---|
85 | }
|
---|
86 | }
|
---|
87 | }
|
---|