-
-
Notifications
You must be signed in to change notification settings - Fork 3.6k
/
SingleLineJavadocCheck.java
211 lines (194 loc) · 7.38 KB
/
SingleLineJavadocCheck.java
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
///////////////////////////////////////////////////////////////////////////////////////////////
// checkstyle: Checks Java source code and other text files for adherence to a set of rules.
// Copyright (C) 2001-2023 the original author or authors.
//
// This library is free software; you can redistribute it and/or
// modify it under the terms of the GNU Lesser General Public
// License as published by the Free Software Foundation; either
// version 2.1 of the License, or (at your option) any later version.
//
// This library is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
// Lesser General Public License for more details.
//
// You should have received a copy of the GNU Lesser General Public
// License along with this library; if not, write to the Free Software
// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
///////////////////////////////////////////////////////////////////////////////////////////////
package com.puppycrawl.tools.checkstyle.checks.javadoc;
import java.util.Set;
import com.puppycrawl.tools.checkstyle.StatelessCheck;
import com.puppycrawl.tools.checkstyle.api.DetailAST;
import com.puppycrawl.tools.checkstyle.api.DetailNode;
import com.puppycrawl.tools.checkstyle.api.JavadocTokenTypes;
import com.puppycrawl.tools.checkstyle.utils.JavadocUtil;
import com.puppycrawl.tools.checkstyle.utils.TokenUtil;
/**
* <p>
* Checks that a Javadoc block can fit in a single-line and doesn't contain block tags.
* Javadoc comment that contains at least one block tag should be formatted in a few lines.
* </p>
* <ul>
* <li>
* Property {@code ignoreInlineTags} - Control whether
* <a href="https://docs.oracle.com/javase/8/docs/technotes/tools/windows/javadoc.html#CHDBEFIF">
* inline tags</a> must be ignored.
* Type is {@code boolean}.
* Default value is {@code true}.
* </li>
* <li>
* Property {@code ignoredTags} - Specify
* <a href="https://docs.oracle.com/javase/8/docs/technotes/tools/windows/javadoc.html#CHDBEFIF">
* block tags</a> which are ignored by the check.
* Type is {@code java.lang.String[]}.
* Default value is {@code ""}.
* </li>
* <li>
* Property {@code violateExecutionOnNonTightHtml} - Control when to print violations
* if the Javadoc being examined by this check violates the tight html rules defined at
* <a href="https://checkstyle.org/writingjavadocchecks.html#Tight-HTML_rules">Tight-HTML Rules</a>.
* Type is {@code boolean}.
* Default value is {@code false}.
* </li>
* </ul>
* <p>
* Parent is {@code com.puppycrawl.tools.checkstyle.TreeWalker}
* </p>
* <p>
* Violation Message Keys:
* </p>
* <ul>
* <li>
* {@code javadoc.missed.html.close}
* </li>
* <li>
* {@code javadoc.parse.rule.error}
* </li>
* <li>
* {@code javadoc.wrong.singleton.html.tag}
* </li>
* <li>
* {@code singleline.javadoc}
* </li>
* </ul>
*
* @since 6.0
*/
@StatelessCheck
public class SingleLineJavadocCheck extends AbstractJavadocCheck {
/**
* A key is pointing to the warning message text in "messages.properties"
* file.
*/
public static final String MSG_KEY = "singleline.javadoc";
/**
* Specify
* <a href="https://docs.oracle.com/javase/8/docs/technotes/tools/windows/javadoc.html#CHDBEFIF">
* block tags</a> which are ignored by the check.
*/
private Set<String> ignoredTags = Set.of();
/**
* Control whether
* <a href="https://docs.oracle.com/javase/8/docs/technotes/tools/windows/javadoc.html#CHDBEFIF">
* inline tags</a> must be ignored.
*/
private boolean ignoreInlineTags = true;
/**
* Setter to specify
* <a href="https://docs.oracle.com/javase/8/docs/technotes/tools/windows/javadoc.html#CHDBEFIF">
* block tags</a> which are ignored by the check.
*
* @param tags to be ignored by check.
* @since 6.8
*/
public void setIgnoredTags(String... tags) {
ignoredTags = Set.of(tags);
}
/**
* Setter to control whether
* <a href="https://docs.oracle.com/javase/8/docs/technotes/tools/windows/javadoc.html#CHDBEFIF">
* inline tags</a> must be ignored.
*
* @param ignoreInlineTags whether inline tags must be ignored.
* @since 6.8
*/
public void setIgnoreInlineTags(boolean ignoreInlineTags) {
this.ignoreInlineTags = ignoreInlineTags;
}
@Override
public int[] getDefaultJavadocTokens() {
return new int[] {
JavadocTokenTypes.JAVADOC,
};
}
@Override
public int[] getRequiredJavadocTokens() {
return getAcceptableJavadocTokens();
}
@Override
public void visitJavadocToken(DetailNode ast) {
if (isSingleLineJavadoc(getBlockCommentAst())
&& (hasJavadocTags(ast) || !ignoreInlineTags && hasJavadocInlineTags(ast))) {
log(ast.getLineNumber(), MSG_KEY);
}
}
/**
* Checks if comment is single-line comment.
*
* @param blockCommentStart the AST tree in which a block comment starts
* @return true, if comment is single-line comment.
*/
private static boolean isSingleLineJavadoc(DetailAST blockCommentStart) {
final DetailAST blockCommentEnd = blockCommentStart.getLastChild();
return TokenUtil.areOnSameLine(blockCommentStart, blockCommentEnd);
}
/**
* Checks if comment has javadoc tags which are not ignored. Also works
* on custom tags. As block tags can be interpreted only at the beginning of a line,
* only the first instance is checked.
*
* @param javadocRoot javadoc root node.
* @return true, if comment has javadoc tags which are not ignored.
* @see <a href=
* "https://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html#blockandinlinetags">
* Block and inline tags</a>
*/
private boolean hasJavadocTags(DetailNode javadocRoot) {
final DetailNode javadocTagSection =
JavadocUtil.findFirstToken(javadocRoot, JavadocTokenTypes.JAVADOC_TAG);
return javadocTagSection != null && !isTagIgnored(javadocTagSection);
}
/**
* Checks if comment has in-line tags which are not ignored.
*
* @param javadocRoot javadoc root node.
* @return true, if comment has in-line tags which are not ignored.
* @see <a href=
* "https://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html#javadoctags">
* JavadocTags</a>
*/
private boolean hasJavadocInlineTags(DetailNode javadocRoot) {
DetailNode javadocTagSection =
JavadocUtil.findFirstToken(javadocRoot, JavadocTokenTypes.JAVADOC_INLINE_TAG);
boolean foundTag = false;
while (javadocTagSection != null) {
if (!isTagIgnored(javadocTagSection)) {
foundTag = true;
break;
}
javadocTagSection = JavadocUtil.getNextSibling(
javadocTagSection, JavadocTokenTypes.JAVADOC_INLINE_TAG);
}
return foundTag;
}
/**
* Checks if list of ignored tags contains javadocTagSection's javadoc tag.
*
* @param javadocTagSection to check javadoc tag in.
* @return true, if ignoredTags contains javadocTagSection's javadoc tag.
*/
private boolean isTagIgnored(DetailNode javadocTagSection) {
return ignoredTags.contains(JavadocUtil.getTagName(javadocTagSection));
}
}