1 | |
|
2 | |
|
3 | |
|
4 | |
|
5 | |
|
6 | |
|
7 | |
|
8 | |
|
9 | |
|
10 | |
|
11 | |
|
12 | |
|
13 | |
|
14 | |
|
15 | |
|
16 | |
|
17 | |
|
18 | |
|
19 | |
package com.puppycrawl.tools.checkstyle.checks.javadoc; |
20 | |
|
21 | |
import com.google.common.collect.ImmutableSortedSet; |
22 | |
import com.puppycrawl.tools.checkstyle.api.Check; |
23 | |
import com.puppycrawl.tools.checkstyle.api.DetailAST; |
24 | |
import com.puppycrawl.tools.checkstyle.api.FastStack; |
25 | |
import com.puppycrawl.tools.checkstyle.api.FileContents; |
26 | |
import com.puppycrawl.tools.checkstyle.api.JavadocTagInfo; |
27 | |
import com.puppycrawl.tools.checkstyle.api.Scope; |
28 | |
import com.puppycrawl.tools.checkstyle.api.ScopeUtils; |
29 | |
import com.puppycrawl.tools.checkstyle.api.TextBlock; |
30 | |
import com.puppycrawl.tools.checkstyle.api.TokenTypes; |
31 | |
import com.puppycrawl.tools.checkstyle.checks.CheckUtils; |
32 | |
import java.util.List; |
33 | |
import java.util.Set; |
34 | |
import java.util.regex.Pattern; |
35 | |
|
36 | |
|
37 | |
|
38 | |
|
39 | |
|
40 | |
|
41 | |
|
42 | |
|
43 | |
|
44 | 14 | public class JavadocStyleCheck |
45 | |
extends Check |
46 | |
{ |
47 | |
|
48 | |
private static final String UNCLOSED_HTML = "javadoc.unclosedhtml"; |
49 | |
|
50 | |
|
51 | |
private static final String EXTRA_HTML = "javadoc.extrahtml"; |
52 | |
|
53 | |
|
54 | 1 | private static final Set<String> SINGLE_TAGS = ImmutableSortedSet.of("p", |
55 | |
"br", "li", "dt", "dd", "td", "hr", "img", "tr", "th", "td"); |
56 | |
|
57 | |
|
58 | |
|
59 | |
|
60 | |
|
61 | 1 | private static final Set<String> ALLOWED_TAGS = ImmutableSortedSet.of( |
62 | |
"a", "abbr", "acronym", "address", "area", "b", "bdo", "big", |
63 | |
"blockquote", "br", "caption", "cite", "code", "colgroup", "del", |
64 | |
"div", "dfn", "dl", "em", "fieldset", "h1", "h2", "h3", "h4", "h5", |
65 | |
"h6", "hr", "i", "img", "ins", "kbd", "li", "ol", "p", "pre", "q", |
66 | |
"samp", "small", "span", "strong", "style", "sub", "sup", "table", |
67 | |
"tbody", "td", "tfoot", "th", "thead", "tr", "tt", "ul"); |
68 | |
|
69 | |
|
70 | 14 | private Scope mScope = Scope.PRIVATE; |
71 | |
|
72 | |
|
73 | |
private Scope mExcludeScope; |
74 | |
|
75 | |
|
76 | 14 | private String mEndOfSentenceFormat = "([.?!][ \t\n\r\f<])|([.?!]$)"; |
77 | |
|
78 | |
|
79 | |
private Pattern mEndOfSentencePattern; |
80 | |
|
81 | |
|
82 | |
|
83 | |
|
84 | |
|
85 | 14 | private boolean mCheckFirstSentence = true; |
86 | |
|
87 | |
|
88 | |
|
89 | |
|
90 | 14 | private boolean mCheckHtml = true; |
91 | |
|
92 | |
|
93 | |
|
94 | |
|
95 | |
private boolean mCheckEmptyJavadoc; |
96 | |
|
97 | |
@Override |
98 | |
public int[] getDefaultTokens() |
99 | |
{ |
100 | 14 | return new int[] { |
101 | |
TokenTypes.INTERFACE_DEF, |
102 | |
TokenTypes.CLASS_DEF, |
103 | |
TokenTypes.ANNOTATION_DEF, |
104 | |
TokenTypes.ENUM_DEF, |
105 | |
TokenTypes.METHOD_DEF, |
106 | |
TokenTypes.CTOR_DEF, |
107 | |
TokenTypes.VARIABLE_DEF, |
108 | |
TokenTypes.ENUM_CONSTANT_DEF, |
109 | |
TokenTypes.ANNOTATION_FIELD_DEF, |
110 | |
TokenTypes.PACKAGE_DEF, |
111 | |
}; |
112 | |
} |
113 | |
|
114 | |
@Override |
115 | |
public void visitToken(DetailAST aAST) |
116 | |
{ |
117 | 356 | if (shouldCheck(aAST)) { |
118 | 277 | final FileContents contents = getFileContents(); |
119 | |
|
120 | |
|
121 | |
|
122 | 277 | final TextBlock cmt = |
123 | |
contents.getJavadocBefore(aAST.getFirstChild().getLineNo()); |
124 | |
|
125 | 277 | checkComment(aAST, cmt); |
126 | |
} |
127 | 356 | } |
128 | |
|
129 | |
|
130 | |
|
131 | |
|
132 | |
|
133 | |
|
134 | |
private boolean shouldCheck(final DetailAST aAST) |
135 | |
{ |
136 | 356 | if (aAST.getType() == TokenTypes.PACKAGE_DEF) { |
137 | 14 | return getFileContents().inPackageInfo(); |
138 | |
} |
139 | |
|
140 | 342 | if (ScopeUtils.inCodeBlock(aAST)) { |
141 | 0 | return false; |
142 | |
} |
143 | |
|
144 | |
final Scope declaredScope; |
145 | 342 | if (aAST.getType() == TokenTypes.ENUM_CONSTANT_DEF) { |
146 | 18 | declaredScope = Scope.PUBLIC; |
147 | |
} |
148 | |
else { |
149 | 324 | declaredScope = ScopeUtils.getScopeFromMods( |
150 | |
aAST.findFirstToken(TokenTypes.MODIFIERS)); |
151 | |
} |
152 | |
|
153 | 342 | final Scope scope = |
154 | |
ScopeUtils.inInterfaceOrAnnotationBlock(aAST) |
155 | |
? Scope.PUBLIC : declaredScope; |
156 | 342 | final Scope surroundingScope = ScopeUtils.getSurroundingScope(aAST); |
157 | |
|
158 | 342 | return scope.isIn(mScope) |
159 | |
&& ((surroundingScope == null) || surroundingScope.isIn(mScope)) |
160 | |
&& ((mExcludeScope == null) |
161 | |
|| !scope.isIn(mExcludeScope) |
162 | |
|| ((surroundingScope != null) |
163 | |
&& !surroundingScope.isIn(mExcludeScope))); |
164 | |
} |
165 | |
|
166 | |
|
167 | |
|
168 | |
|
169 | |
|
170 | |
|
171 | |
|
172 | |
|
173 | |
|
174 | |
|
175 | |
private void checkComment(final DetailAST aAST, final TextBlock aComment) |
176 | |
{ |
177 | 277 | if (aComment == null) { |
178 | |
|
179 | |
|
180 | |
|
181 | |
|
182 | 15 | if (getFileContents().inPackageInfo()) { |
183 | 1 | log(aAST.getLineNo(), "javadoc.missing"); |
184 | |
} |
185 | 15 | return; |
186 | |
} |
187 | |
|
188 | 262 | if (mCheckFirstSentence) { |
189 | 190 | checkFirstSentence(aAST, aComment); |
190 | |
} |
191 | |
|
192 | 262 | if (mCheckHtml) { |
193 | 154 | checkHtml(aAST, aComment); |
194 | |
} |
195 | |
|
196 | 262 | if (mCheckEmptyJavadoc) { |
197 | 99 | checkEmptyJavadoc(aComment); |
198 | |
} |
199 | 262 | } |
200 | |
|
201 | |
|
202 | |
|
203 | |
|
204 | |
|
205 | |
|
206 | |
|
207 | |
|
208 | |
|
209 | |
|
210 | |
|
211 | |
private void checkFirstSentence(final DetailAST aAST, TextBlock aComment) |
212 | |
{ |
213 | 190 | final String commentText = getCommentText(aComment.getText()); |
214 | |
|
215 | 190 | if ((commentText.length() != 0) |
216 | |
&& !getEndOfSentencePattern().matcher(commentText).find() |
217 | |
&& !("{@inheritDoc}".equals(commentText) |
218 | |
&& JavadocTagInfo.INHERIT_DOC.isValidOn(aAST))) |
219 | |
{ |
220 | 38 | log(aComment.getStartLineNo(), "javadoc.noperiod"); |
221 | |
} |
222 | 190 | } |
223 | |
|
224 | |
|
225 | |
|
226 | |
|
227 | |
|
228 | |
|
229 | |
private void checkEmptyJavadoc(TextBlock aComment) |
230 | |
{ |
231 | 99 | final String commentText = getCommentText(aComment.getText()); |
232 | |
|
233 | 99 | if (commentText.length() == 0) { |
234 | 14 | log(aComment.getStartLineNo(), "javadoc.empty"); |
235 | |
} |
236 | 99 | } |
237 | |
|
238 | |
|
239 | |
|
240 | |
|
241 | |
|
242 | |
|
243 | |
private String getCommentText(String[] aComments) |
244 | |
{ |
245 | 289 | final StringBuffer buffer = new StringBuffer(); |
246 | 1390 | for (final String line : aComments) { |
247 | 1221 | final int textStart = findTextStart(line); |
248 | |
|
249 | 1221 | if (textStart != -1) { |
250 | 741 | if (line.charAt(textStart) == '@') { |
251 | |
|
252 | 120 | break; |
253 | |
} |
254 | 621 | buffer.append(line.substring(textStart)); |
255 | 621 | trimTail(buffer); |
256 | 621 | buffer.append('\n'); |
257 | |
} |
258 | |
} |
259 | |
|
260 | 289 | return buffer.toString().trim(); |
261 | |
} |
262 | |
|
263 | |
|
264 | |
|
265 | |
|
266 | |
|
267 | |
|
268 | |
|
269 | |
|
270 | |
|
271 | |
private int findTextStart(String aLine) |
272 | |
{ |
273 | 1221 | int textStart = -1; |
274 | 10121 | for (int i = 0; i < aLine.length(); i++) { |
275 | 9641 | if (!Character.isWhitespace(aLine.charAt(i))) { |
276 | 1962 | if (aLine.regionMatches(i, "/**", 0, "/**".length())) { |
277 | 289 | i += 2; |
278 | |
} |
279 | 1673 | else if (aLine.regionMatches(i, "*/", 0, 2)) { |
280 | 144 | i++; |
281 | |
} |
282 | 1529 | else if (aLine.charAt(i) != '*') { |
283 | 741 | textStart = i; |
284 | 741 | break; |
285 | |
} |
286 | |
} |
287 | |
} |
288 | 1221 | return textStart; |
289 | |
} |
290 | |
|
291 | |
|
292 | |
|
293 | |
|
294 | |
|
295 | |
private void trimTail(StringBuffer aBuffer) |
296 | |
{ |
297 | 721 | for (int i = aBuffer.length() - 1; i >= 0; i--) { |
298 | 721 | if (Character.isWhitespace(aBuffer.charAt(i))) { |
299 | 75 | aBuffer.deleteCharAt(i); |
300 | |
} |
301 | 646 | else if ((i > 0) |
302 | |
&& (aBuffer.charAt(i - 1) == '*') |
303 | |
&& (aBuffer.charAt(i) == '/')) |
304 | |
{ |
305 | 25 | aBuffer.deleteCharAt(i); |
306 | 25 | aBuffer.deleteCharAt(i - 1); |
307 | 25 | i--; |
308 | 35 | while (aBuffer.charAt(i - 1) == '*') { |
309 | 10 | aBuffer.deleteCharAt(i - 1); |
310 | 10 | i--; |
311 | |
} |
312 | |
} |
313 | |
else { |
314 | |
break; |
315 | |
} |
316 | |
} |
317 | 621 | } |
318 | |
|
319 | |
|
320 | |
|
321 | |
|
322 | |
|
323 | |
|
324 | |
|
325 | |
|
326 | |
|
327 | |
|
328 | |
private void checkHtml(final DetailAST aAST, final TextBlock aComment) |
329 | |
{ |
330 | 154 | final int lineno = aComment.getStartLineNo(); |
331 | 154 | final FastStack<HtmlTag> htmlStack = FastStack.newInstance(); |
332 | 154 | final String[] text = aComment.getText(); |
333 | 154 | final List<String> typeParameters = |
334 | |
CheckUtils.getTypeParameterNames(aAST); |
335 | |
|
336 | 154 | TagParser parser = null; |
337 | 154 | parser = new TagParser(text, lineno); |
338 | |
|
339 | 315 | while (parser.hasNextTag()) { |
340 | 166 | final HtmlTag tag = parser.nextTag(); |
341 | |
|
342 | 166 | if (tag.isIncompleteTag()) { |
343 | 5 | log(tag.getLineno(), "javadoc.incompleteTag", |
344 | |
text[tag.getLineno() - lineno]); |
345 | 5 | return; |
346 | |
} |
347 | 161 | if (tag.isClosedTag()) { |
348 | |
|
349 | 12 | continue; |
350 | |
} |
351 | 149 | if (!tag.isCloseTag()) { |
352 | |
|
353 | 106 | if (isAllowedTag(tag)) { |
354 | 55 | htmlStack.push(tag); |
355 | |
} |
356 | |
} |
357 | |
else { |
358 | |
|
359 | 43 | if (isExtraHtml(tag.getId(), htmlStack)) { |
360 | |
|
361 | 16 | log(tag.getLineno(), |
362 | |
tag.getPosition(), |
363 | |
EXTRA_HTML, |
364 | |
tag); |
365 | |
} |
366 | |
else { |
367 | |
|
368 | |
|
369 | 27 | checkUnclosedTags(htmlStack, tag.getId()); |
370 | |
} |
371 | |
} |
372 | 149 | } |
373 | |
|
374 | |
|
375 | 149 | String lastFound = ""; |
376 | 149 | for (final HtmlTag htag : htmlStack) { |
377 | 23 | if (!isSingleTag(htag) |
378 | |
&& !htag.getId().equals(lastFound) |
379 | |
&& !typeParameters.contains(htag.getId())) |
380 | |
{ |
381 | 14 | log(htag.getLineno(), htag.getPosition(), UNCLOSED_HTML, htag); |
382 | 14 | lastFound = htag.getId(); |
383 | |
} |
384 | |
} |
385 | 149 | } |
386 | |
|
387 | |
|
388 | |
|
389 | |
|
390 | |
|
391 | |
|
392 | |
|
393 | |
|
394 | |
|
395 | |
|
396 | |
private void checkUnclosedTags(FastStack<HtmlTag> aHtmlStack, String aToken) |
397 | |
{ |
398 | 27 | final FastStack<HtmlTag> unclosedTags = FastStack.newInstance(); |
399 | 27 | HtmlTag lastOpenTag = aHtmlStack.pop(); |
400 | 32 | while (!aToken.equalsIgnoreCase(lastOpenTag.getId())) { |
401 | |
|
402 | |
|
403 | 5 | if (isSingleTag(lastOpenTag)) { |
404 | 2 | lastOpenTag = aHtmlStack.pop(); |
405 | |
} |
406 | |
else { |
407 | 3 | unclosedTags.push(lastOpenTag); |
408 | 3 | lastOpenTag = aHtmlStack.pop(); |
409 | |
} |
410 | |
} |
411 | |
|
412 | |
|
413 | 27 | String lastFound = ""; |
414 | 27 | for (final HtmlTag htag : unclosedTags) { |
415 | 3 | lastOpenTag = htag; |
416 | 3 | if (lastOpenTag.getId().equals(lastFound)) { |
417 | 0 | continue; |
418 | |
} |
419 | 3 | lastFound = lastOpenTag.getId(); |
420 | 3 | log(lastOpenTag.getLineno(), |
421 | |
lastOpenTag.getPosition(), |
422 | |
UNCLOSED_HTML, |
423 | |
lastOpenTag); |
424 | |
} |
425 | 27 | } |
426 | |
|
427 | |
|
428 | |
|
429 | |
|
430 | |
|
431 | |
|
432 | |
|
433 | |
private boolean isSingleTag(HtmlTag aTag) |
434 | |
{ |
435 | |
|
436 | |
|
437 | |
|
438 | |
|
439 | 28 | return SINGLE_TAGS.contains(aTag.getId().toLowerCase()); |
440 | |
} |
441 | |
|
442 | |
|
443 | |
|
444 | |
|
445 | |
|
446 | |
|
447 | |
|
448 | |
private boolean isAllowedTag(HtmlTag aTag) |
449 | |
{ |
450 | 106 | return ALLOWED_TAGS.contains(aTag.getId().toLowerCase()); |
451 | |
} |
452 | |
|
453 | |
|
454 | |
|
455 | |
|
456 | |
|
457 | |
|
458 | |
|
459 | |
|
460 | |
|
461 | |
|
462 | |
private boolean isExtraHtml(String aToken, FastStack<HtmlTag> aHtmlStack) |
463 | |
{ |
464 | 43 | boolean isExtra = true; |
465 | 43 | for (final HtmlTag td : aHtmlStack) { |
466 | |
|
467 | |
|
468 | |
|
469 | |
|
470 | 30 | if (aToken.equalsIgnoreCase(td.getId())) { |
471 | 27 | isExtra = false; |
472 | 27 | break; |
473 | |
} |
474 | |
} |
475 | |
|
476 | 43 | return isExtra; |
477 | |
} |
478 | |
|
479 | |
|
480 | |
|
481 | |
|
482 | |
|
483 | |
public void setScope(String aFrom) |
484 | |
{ |
485 | 4 | mScope = Scope.getInstance(aFrom); |
486 | 4 | } |
487 | |
|
488 | |
|
489 | |
|
490 | |
|
491 | |
|
492 | |
public void setExcludeScope(String aScope) |
493 | |
{ |
494 | 1 | mExcludeScope = Scope.getInstance(aScope); |
495 | 1 | } |
496 | |
|
497 | |
|
498 | |
|
499 | |
|
500 | |
|
501 | |
public void setEndOfSentenceFormat(String aFormat) |
502 | |
{ |
503 | 1 | mEndOfSentenceFormat = aFormat; |
504 | 1 | } |
505 | |
|
506 | |
|
507 | |
|
508 | |
|
509 | |
|
510 | |
|
511 | |
private Pattern getEndOfSentencePattern() |
512 | |
{ |
513 | 164 | if (mEndOfSentencePattern == null) { |
514 | 11 | mEndOfSentencePattern = Pattern.compile(mEndOfSentenceFormat); |
515 | |
} |
516 | 164 | return mEndOfSentencePattern; |
517 | |
} |
518 | |
|
519 | |
|
520 | |
|
521 | |
|
522 | |
|
523 | |
|
524 | |
public void setCheckFirstSentence(boolean aFlag) |
525 | |
{ |
526 | 7 | mCheckFirstSentence = aFlag; |
527 | 7 | } |
528 | |
|
529 | |
|
530 | |
|
531 | |
|
532 | |
|
533 | |
public void setCheckHtml(boolean aFlag) |
534 | |
{ |
535 | 7 | mCheckHtml = aFlag; |
536 | 7 | } |
537 | |
|
538 | |
|
539 | |
|
540 | |
|
541 | |
|
542 | |
public void setCheckEmptyJavadoc(boolean aFlag) |
543 | |
{ |
544 | 4 | mCheckEmptyJavadoc = aFlag; |
545 | 4 | } |
546 | |
} |