001/////////////////////////////////////////////////////////////////////////////////////////////// 002// checkstyle: Checks Java source code and other text files for adherence to a set of rules. 003// Copyright (C) 2001-2024 the original author or authors. 004// 005// This library is free software; you can redistribute it and/or 006// modify it under the terms of the GNU Lesser General Public 007// License as published by the Free Software Foundation; either 008// version 2.1 of the License, or (at your option) any later version. 009// 010// This library is distributed in the hope that it will be useful, 011// but WITHOUT ANY WARRANTY; without even the implied warranty of 012// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 013// Lesser General Public License for more details. 014// 015// You should have received a copy of the GNU Lesser General Public 016// License along with this library; if not, write to the Free Software 017// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA 018/////////////////////////////////////////////////////////////////////////////////////////////// 019 020package com.puppycrawl.tools.checkstyle.checks.javadoc; 021 022import java.util.ArrayList; 023import java.util.Arrays; 024import java.util.Collection; 025import java.util.Iterator; 026import java.util.List; 027import java.util.ListIterator; 028import java.util.Set; 029import java.util.regex.MatchResult; 030import java.util.regex.Matcher; 031import java.util.regex.Pattern; 032 033import com.puppycrawl.tools.checkstyle.StatelessCheck; 034import com.puppycrawl.tools.checkstyle.api.AbstractCheck; 035import com.puppycrawl.tools.checkstyle.api.DetailAST; 036import com.puppycrawl.tools.checkstyle.api.FileContents; 037import com.puppycrawl.tools.checkstyle.api.FullIdent; 038import com.puppycrawl.tools.checkstyle.api.TextBlock; 039import com.puppycrawl.tools.checkstyle.api.TokenTypes; 040import com.puppycrawl.tools.checkstyle.checks.naming.AccessModifierOption; 041import com.puppycrawl.tools.checkstyle.utils.AnnotationUtil; 042import com.puppycrawl.tools.checkstyle.utils.CheckUtil; 043import com.puppycrawl.tools.checkstyle.utils.CommonUtil; 044import com.puppycrawl.tools.checkstyle.utils.UnmodifiableCollectionUtil; 045 046/** 047 * <div> 048 * Checks the Javadoc of a method or constructor. 049 * </div> 050 * 051 * <p> 052 * Violates parameters and type parameters for which no param tags are present can 053 * be suppressed by defining property {@code allowMissingParamTags}. 054 * </p> 055 * 056 * <p> 057 * Violates methods which return non-void but for which no return tag is present can 058 * be suppressed by defining property {@code allowMissingReturnTag}. 059 * </p> 060 * 061 * <p> 062 * Violates exceptions which are declared to be thrown (by {@code throws} in the method 063 * signature or by {@code throw new} in the method body), but for which no throws tag is 064 * present by activation of property {@code validateThrows}. 065 * Note that {@code throw new} is not checked in the following places: 066 * </p> 067 * <ul> 068 * <li> 069 * Inside a try block (with catch). It is not possible to determine if the thrown 070 * exception can be caught by the catch block as there is no knowledge of the 071 * inheritance hierarchy, so the try block is ignored entirely. However, catch 072 * and finally blocks, as well as try blocks without catch, are still checked. 073 * </li> 074 * <li> 075 * Local classes, anonymous classes and lambda expressions. It is not known when the 076 * throw statements inside such classes are going to be evaluated, so they are ignored. 077 * </li> 078 * </ul> 079 * 080 * <p> 081 * ATTENTION: Checkstyle does not have information about hierarchy of exception types 082 * so usage of base class is considered as separate exception type. 083 * As workaround, you need to specify both types in javadoc (parent and exact type). 084 * </p> 085 * 086 * <p> 087 * Javadoc is not required on a method that is tagged with the {@code @Override} 088 * annotation. However, under Java 5 it is not possible to mark a method required 089 * for an interface (this was <i>corrected</i> under Java 6). Hence, Checkstyle 090 * supports using the convention of using a single {@code {@inheritDoc}} tag 091 * instead of all the other tags. 092 * </p> 093 * 094 * <p> 095 * Note that only inheritable items will allow the {@code {@inheritDoc}} 096 * tag to be used in place of comments. Static methods at all visibilities, 097 * private non-static methods and constructors are not inheritable. 098 * </p> 099 * 100 * <p> 101 * For example, if the following method is implementing a method required by 102 * an interface, then the Javadoc could be done as: 103 * </p> 104 * <pre> 105 * /** {@inheritDoc} */ 106 * public int checkReturnTag(final int aTagIndex, 107 * JavadocTag[] aTags, 108 * int aLineNo) 109 * </pre> 110 * <ul> 111 * <li> 112 * Property {@code accessModifiers} - Specify the access modifiers where Javadoc comments are 113 * checked. 114 * Type is {@code com.puppycrawl.tools.checkstyle.checks.naming.AccessModifierOption[]}. 115 * Default value is {@code public, protected, package, private}. 116 * </li> 117 * <li> 118 * Property {@code allowMissingParamTags} - Control whether to ignore violations 119 * when a method has parameters but does not have matching {@code param} tags in the javadoc. 120 * Type is {@code boolean}. 121 * Default value is {@code false}. 122 * </li> 123 * <li> 124 * Property {@code allowMissingReturnTag} - Control whether to ignore violations 125 * when a method returns non-void type and does not have a {@code return} tag in the javadoc. 126 * Type is {@code boolean}. 127 * Default value is {@code false}. 128 * </li> 129 * <li> 130 * Property {@code allowedAnnotations} - Specify annotations that allow missed documentation. 131 * Type is {@code java.lang.String[]}. 132 * Default value is {@code Override}. 133 * </li> 134 * <li> 135 * Property {@code validateThrows} - Control whether to validate {@code throws} tags. 136 * Type is {@code boolean}. 137 * Default value is {@code false}. 138 * </li> 139 * <li> 140 * Property {@code tokens} - tokens to check 141 * Type is {@code java.lang.String[]}. 142 * Validation type is {@code tokenSet}. 143 * Default value is: 144 * <a href="https://checkstyle.org/apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#METHOD_DEF"> 145 * METHOD_DEF</a>, 146 * <a href="https://checkstyle.org/apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#CTOR_DEF"> 147 * CTOR_DEF</a>, 148 * <a href="https://checkstyle.org/apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#ANNOTATION_FIELD_DEF"> 149 * ANNOTATION_FIELD_DEF</a>, 150 * <a href="https://checkstyle.org/apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#COMPACT_CTOR_DEF"> 151 * COMPACT_CTOR_DEF</a>. 152 * </li> 153 * </ul> 154 * 155 * <p> 156 * Parent is {@code com.puppycrawl.tools.checkstyle.TreeWalker} 157 * </p> 158 * 159 * <p> 160 * Violation Message Keys: 161 * </p> 162 * <ul> 163 * <li> 164 * {@code javadoc.classInfo} 165 * </li> 166 * <li> 167 * {@code javadoc.duplicateTag} 168 * </li> 169 * <li> 170 * {@code javadoc.expectedTag} 171 * </li> 172 * <li> 173 * {@code javadoc.invalidInheritDoc} 174 * </li> 175 * <li> 176 * {@code javadoc.return.expected} 177 * </li> 178 * <li> 179 * {@code javadoc.unusedTag} 180 * </li> 181 * <li> 182 * {@code javadoc.unusedTagGeneral} 183 * </li> 184 * </ul> 185 * 186 * @since 3.0 187 */ 188@StatelessCheck 189public class JavadocMethodCheck extends AbstractCheck { 190 191 /** 192 * A key is pointing to the warning message text in "messages.properties" 193 * file. 194 */ 195 public static final String MSG_CLASS_INFO = "javadoc.classInfo"; 196 197 /** 198 * A key is pointing to the warning message text in "messages.properties" 199 * file. 200 */ 201 public static final String MSG_UNUSED_TAG_GENERAL = "javadoc.unusedTagGeneral"; 202 203 /** 204 * A key is pointing to the warning message text in "messages.properties" 205 * file. 206 */ 207 public static final String MSG_INVALID_INHERIT_DOC = "javadoc.invalidInheritDoc"; 208 209 /** 210 * A key is pointing to the warning message text in "messages.properties" 211 * file. 212 */ 213 public static final String MSG_UNUSED_TAG = "javadoc.unusedTag"; 214 215 /** 216 * A key is pointing to the warning message text in "messages.properties" 217 * file. 218 */ 219 public static final String MSG_EXPECTED_TAG = "javadoc.expectedTag"; 220 221 /** 222 * A key is pointing to the warning message text in "messages.properties" 223 * file. 224 */ 225 public static final String MSG_RETURN_EXPECTED = "javadoc.return.expected"; 226 227 /** 228 * A key is pointing to the warning message text in "messages.properties" 229 * file. 230 */ 231 public static final String MSG_DUPLICATE_TAG = "javadoc.duplicateTag"; 232 233 /** Html element start symbol. */ 234 private static final String ELEMENT_START = "<"; 235 236 /** Html element end symbol. */ 237 private static final String ELEMENT_END = ">"; 238 239 /** Compiled regexp to match Javadoc tags that take an argument. */ 240 private static final Pattern MATCH_JAVADOC_ARG = CommonUtil.createPattern( 241 "^\\s*(?>\\*|\\/\\*\\*)?\\s*@(throws|exception|param)\\s+(\\S+)\\s+\\S*"); 242 /** Compiled regexp to match Javadoc tags with argument but with missing description. */ 243 private static final Pattern MATCH_JAVADOC_ARG_MISSING_DESCRIPTION = 244 CommonUtil.createPattern("^\\s*(?>\\*|\\/\\*\\*)?\\s*@(throws|exception|param)\\s+" 245 + "(\\S[^*]*)(?:(\\s+|\\*\\/))?"); 246 247 /** Compiled regexp to look for a continuation of the comment. */ 248 private static final Pattern MATCH_JAVADOC_MULTILINE_CONT = 249 CommonUtil.createPattern("(\\*\\/|@|[^\\s\\*])"); 250 251 /** Multiline finished at end of comment. */ 252 private static final String END_JAVADOC = "*/"; 253 /** Multiline finished at next Javadoc. */ 254 private static final String NEXT_TAG = "@"; 255 256 /** Compiled regexp to match Javadoc tags with no argument. */ 257 private static final Pattern MATCH_JAVADOC_NOARG = 258 CommonUtil.createPattern("^\\s*(?>\\*|\\/\\*\\*)?\\s*@(return|see)\\s+\\S"); 259 /** Compiled regexp to match first part of multilineJavadoc tags. */ 260 private static final Pattern MATCH_JAVADOC_NOARG_MULTILINE_START = 261 CommonUtil.createPattern("^\\s*(?>\\*|\\/\\*\\*)?\\s*@(return|see)\\s*$"); 262 /** Compiled regexp to match Javadoc tags with no argument and {}. */ 263 private static final Pattern MATCH_JAVADOC_NOARG_CURLY = 264 CommonUtil.createPattern("\\{\\s*@(inheritDoc)\\s*\\}"); 265 266 /** Specify the access modifiers where Javadoc comments are checked. */ 267 private AccessModifierOption[] accessModifiers = { 268 AccessModifierOption.PUBLIC, 269 AccessModifierOption.PROTECTED, 270 AccessModifierOption.PACKAGE, 271 AccessModifierOption.PRIVATE, 272 }; 273 274 /** 275 * Control whether to validate {@code throws} tags. 276 */ 277 private boolean validateThrows; 278 279 /** 280 * Control whether to ignore violations when a method has parameters but does 281 * not have matching {@code param} tags in the javadoc. 282 */ 283 private boolean allowMissingParamTags; 284 285 /** 286 * Control whether to ignore violations when a method returns non-void type 287 * and does not have a {@code return} tag in the javadoc. 288 */ 289 private boolean allowMissingReturnTag; 290 291 /** Specify annotations that allow missed documentation. */ 292 private Set<String> allowedAnnotations = Set.of("Override"); 293 294 /** 295 * Setter to control whether to validate {@code throws} tags. 296 * 297 * @param value user's value. 298 * @since 6.0 299 */ 300 public void setValidateThrows(boolean value) { 301 validateThrows = value; 302 } 303 304 /** 305 * Setter to specify annotations that allow missed documentation. 306 * 307 * @param userAnnotations user's value. 308 * @since 6.0 309 */ 310 public void setAllowedAnnotations(String... userAnnotations) { 311 allowedAnnotations = Set.of(userAnnotations); 312 } 313 314 /** 315 * Setter to specify the access modifiers where Javadoc comments are checked. 316 * 317 * @param accessModifiers access modifiers. 318 * @since 8.42 319 */ 320 public void setAccessModifiers(AccessModifierOption... accessModifiers) { 321 this.accessModifiers = 322 UnmodifiableCollectionUtil.copyOfArray(accessModifiers, accessModifiers.length); 323 } 324 325 /** 326 * Setter to control whether to ignore violations when a method has parameters 327 * but does not have matching {@code param} tags in the javadoc. 328 * 329 * @param flag a {@code Boolean} value 330 * @since 3.1 331 */ 332 public void setAllowMissingParamTags(boolean flag) { 333 allowMissingParamTags = flag; 334 } 335 336 /** 337 * Setter to control whether to ignore violations when a method returns non-void type 338 * and does not have a {@code return} tag in the javadoc. 339 * 340 * @param flag a {@code Boolean} value 341 * @since 3.1 342 */ 343 public void setAllowMissingReturnTag(boolean flag) { 344 allowMissingReturnTag = flag; 345 } 346 347 @Override 348 public final int[] getRequiredTokens() { 349 return CommonUtil.EMPTY_INT_ARRAY; 350 } 351 352 @Override 353 public int[] getDefaultTokens() { 354 return getAcceptableTokens(); 355 } 356 357 @Override 358 public int[] getAcceptableTokens() { 359 return new int[] { 360 TokenTypes.METHOD_DEF, 361 TokenTypes.CTOR_DEF, 362 TokenTypes.ANNOTATION_FIELD_DEF, 363 TokenTypes.COMPACT_CTOR_DEF, 364 }; 365 } 366 367 @Override 368 public final void visitToken(DetailAST ast) { 369 processAST(ast); 370 } 371 372 /** 373 * Called to process an AST when visiting it. 374 * 375 * @param ast the AST to process. Guaranteed to not be PACKAGE_DEF or 376 * IMPORT tokens. 377 */ 378 // suppress deprecation until https://github.com/checkstyle/checkstyle/issues/11166 379 @SuppressWarnings("deprecation") 380 private void processAST(DetailAST ast) { 381 if (shouldCheck(ast)) { 382 final FileContents contents = getFileContents(); 383 final TextBlock textBlock = contents.getJavadocBefore(ast.getLineNo()); 384 385 if (textBlock != null) { 386 checkComment(ast, textBlock); 387 } 388 } 389 } 390 391 /** 392 * Whether we should check this node. 393 * 394 * @param ast a given node. 395 * @return whether we should check a given node. 396 */ 397 private boolean shouldCheck(final DetailAST ast) { 398 final AccessModifierOption surroundingAccessModifier = CheckUtil 399 .getSurroundingAccessModifier(ast); 400 final AccessModifierOption accessModifier = CheckUtil 401 .getAccessModifierFromModifiersToken(ast); 402 return surroundingAccessModifier != null 403 && Arrays.stream(accessModifiers) 404 .anyMatch(modifier -> modifier == surroundingAccessModifier) 405 && Arrays.stream(accessModifiers).anyMatch(modifier -> modifier == accessModifier); 406 } 407 408 /** 409 * Checks the Javadoc for a method. 410 * 411 * @param ast the token for the method 412 * @param comment the Javadoc comment 413 */ 414 private void checkComment(DetailAST ast, TextBlock comment) { 415 final List<JavadocTag> tags = getMethodTags(comment); 416 417 if (!hasShortCircuitTag(ast, tags)) { 418 if (ast.getType() == TokenTypes.ANNOTATION_FIELD_DEF) { 419 checkReturnTag(tags, ast.getLineNo(), true); 420 } 421 else { 422 final Iterator<JavadocTag> it = tags.iterator(); 423 // Check for inheritDoc 424 boolean hasInheritDocTag = false; 425 while (!hasInheritDocTag && it.hasNext()) { 426 hasInheritDocTag = it.next().isInheritDocTag(); 427 } 428 final boolean reportExpectedTags = !hasInheritDocTag 429 && !AnnotationUtil.containsAnnotation(ast, allowedAnnotations); 430 431 // COMPACT_CTOR_DEF has no parameters 432 if (ast.getType() != TokenTypes.COMPACT_CTOR_DEF) { 433 checkParamTags(tags, ast, reportExpectedTags); 434 } 435 final List<ExceptionInfo> throwed = 436 combineExceptionInfo(getThrows(ast), getThrowed(ast)); 437 checkThrowsTags(tags, throwed, reportExpectedTags); 438 if (CheckUtil.isNonVoidMethod(ast)) { 439 checkReturnTag(tags, ast.getLineNo(), reportExpectedTags); 440 } 441 442 } 443 444 // Dump out all unused tags 445 tags.stream().filter(javadocTag -> !javadocTag.isSeeOrInheritDocTag()) 446 .forEach(javadocTag -> log(javadocTag.getLineNo(), MSG_UNUSED_TAG_GENERAL)); 447 } 448 } 449 450 /** 451 * Validates whether the Javadoc has a short circuit tag. Currently, this is 452 * the inheritTag. Any violations are logged. 453 * 454 * @param ast the construct being checked 455 * @param tags the list of Javadoc tags associated with the construct 456 * @return true if the construct has a short circuit tag. 457 */ 458 private boolean hasShortCircuitTag(final DetailAST ast, final List<JavadocTag> tags) { 459 boolean result = true; 460 // Check if it contains {@inheritDoc} tag 461 if (tags.size() == 1 462 && tags.get(0).isInheritDocTag()) { 463 // Invalid if private, a constructor, or a static method 464 if (!JavadocTagInfo.INHERIT_DOC.isValidOn(ast)) { 465 log(ast, MSG_INVALID_INHERIT_DOC); 466 } 467 } 468 else { 469 result = false; 470 } 471 return result; 472 } 473 474 /** 475 * Returns the tags in a javadoc comment. Only finds throws, exception, 476 * param, return and see tags. 477 * 478 * @param comment the Javadoc comment 479 * @return the tags found 480 */ 481 private static List<JavadocTag> getMethodTags(TextBlock comment) { 482 final String[] lines = comment.getText(); 483 final List<JavadocTag> tags = new ArrayList<>(); 484 int currentLine = comment.getStartLineNo() - 1; 485 final int startColumnNumber = comment.getStartColNo(); 486 487 for (int i = 0; i < lines.length; i++) { 488 currentLine++; 489 final Matcher javadocArgMatcher = 490 MATCH_JAVADOC_ARG.matcher(lines[i]); 491 final Matcher javadocArgMissingDescriptionMatcher = 492 MATCH_JAVADOC_ARG_MISSING_DESCRIPTION.matcher(lines[i]); 493 final Matcher javadocNoargMatcher = 494 MATCH_JAVADOC_NOARG.matcher(lines[i]); 495 final Matcher noargCurlyMatcher = 496 MATCH_JAVADOC_NOARG_CURLY.matcher(lines[i]); 497 final Matcher noargMultilineStart = 498 MATCH_JAVADOC_NOARG_MULTILINE_START.matcher(lines[i]); 499 500 if (javadocArgMatcher.find()) { 501 final int col = calculateTagColumn(javadocArgMatcher, i, startColumnNumber); 502 tags.add(new JavadocTag(currentLine, col, javadocArgMatcher.group(1), 503 javadocArgMatcher.group(2))); 504 } 505 else if (javadocArgMissingDescriptionMatcher.find()) { 506 final int col = calculateTagColumn(javadocArgMissingDescriptionMatcher, i, 507 startColumnNumber); 508 tags.add(new JavadocTag(currentLine, col, 509 javadocArgMissingDescriptionMatcher.group(1), 510 javadocArgMissingDescriptionMatcher.group(2))); 511 } 512 else if (javadocNoargMatcher.find()) { 513 final int col = calculateTagColumn(javadocNoargMatcher, i, startColumnNumber); 514 tags.add(new JavadocTag(currentLine, col, javadocNoargMatcher.group(1))); 515 } 516 else if (noargCurlyMatcher.find()) { 517 tags.add(new JavadocTag(currentLine, 0, noargCurlyMatcher.group(1))); 518 } 519 else if (noargMultilineStart.find()) { 520 tags.addAll(getMultilineNoArgTags(noargMultilineStart, lines, i, currentLine)); 521 } 522 } 523 return tags; 524 } 525 526 /** 527 * Calculates column number using Javadoc tag matcher. 528 * 529 * @param javadocTagMatchResult found javadoc tag match result 530 * @param lineNumber line number of Javadoc tag in comment 531 * @param startColumnNumber column number of Javadoc comment beginning 532 * @return column number 533 */ 534 private static int calculateTagColumn(MatchResult javadocTagMatchResult, 535 int lineNumber, int startColumnNumber) { 536 int col = javadocTagMatchResult.start(1) - 1; 537 if (lineNumber == 0) { 538 col += startColumnNumber; 539 } 540 return col; 541 } 542 543 /** 544 * Gets multiline Javadoc tags with no arguments. 545 * 546 * @param noargMultilineStart javadoc tag Matcher 547 * @param lines comment text lines 548 * @param lineIndex line number that contains the javadoc tag 549 * @param tagLine javadoc tag line number in file 550 * @return javadoc tags with no arguments 551 */ 552 private static List<JavadocTag> getMultilineNoArgTags(final Matcher noargMultilineStart, 553 final String[] lines, final int lineIndex, final int tagLine) { 554 int remIndex = lineIndex; 555 Matcher multilineCont; 556 557 do { 558 remIndex++; 559 multilineCont = MATCH_JAVADOC_MULTILINE_CONT.matcher(lines[remIndex]); 560 } while (!multilineCont.find()); 561 562 final List<JavadocTag> tags = new ArrayList<>(); 563 final String lFin = multilineCont.group(1); 564 if (!NEXT_TAG.equals(lFin) 565 && !END_JAVADOC.equals(lFin)) { 566 final String param1 = noargMultilineStart.group(1); 567 final int col = noargMultilineStart.start(1) - 1; 568 569 tags.add(new JavadocTag(tagLine, col, param1)); 570 } 571 572 return tags; 573 } 574 575 /** 576 * Computes the parameter nodes for a method. 577 * 578 * @param ast the method node. 579 * @return the list of parameter nodes for ast. 580 */ 581 private static List<DetailAST> getParameters(DetailAST ast) { 582 final DetailAST params = ast.findFirstToken(TokenTypes.PARAMETERS); 583 final List<DetailAST> returnValue = new ArrayList<>(); 584 585 DetailAST child = params.getFirstChild(); 586 while (child != null) { 587 final DetailAST ident = child.findFirstToken(TokenTypes.IDENT); 588 if (ident != null) { 589 returnValue.add(ident); 590 } 591 child = child.getNextSibling(); 592 } 593 return returnValue; 594 } 595 596 /** 597 * Computes the exception nodes for a method. 598 * 599 * @param ast the method node. 600 * @return the list of exception nodes for ast. 601 */ 602 private static List<ExceptionInfo> getThrows(DetailAST ast) { 603 final List<ExceptionInfo> returnValue = new ArrayList<>(); 604 final DetailAST throwsAST = ast 605 .findFirstToken(TokenTypes.LITERAL_THROWS); 606 if (throwsAST != null) { 607 DetailAST child = throwsAST.getFirstChild(); 608 while (child != null) { 609 if (child.getType() == TokenTypes.IDENT 610 || child.getType() == TokenTypes.DOT) { 611 returnValue.add(getExceptionInfo(child)); 612 } 613 child = child.getNextSibling(); 614 } 615 } 616 return returnValue; 617 } 618 619 /** 620 * Get ExceptionInfo for all exceptions that throws in method code by 'throw new'. 621 * 622 * @param methodAst method DetailAST object where to find exceptions 623 * @return list of ExceptionInfo 624 */ 625 private static List<ExceptionInfo> getThrowed(DetailAST methodAst) { 626 final List<ExceptionInfo> returnValue = new ArrayList<>(); 627 final DetailAST blockAst = methodAst.findFirstToken(TokenTypes.SLIST); 628 if (blockAst != null) { 629 final List<DetailAST> throwLiterals = findTokensInAstByType(blockAst, 630 TokenTypes.LITERAL_THROW); 631 for (DetailAST throwAst : throwLiterals) { 632 if (!isInIgnoreBlock(blockAst, throwAst)) { 633 final DetailAST newAst = throwAst.getFirstChild().getFirstChild(); 634 if (newAst.getType() == TokenTypes.LITERAL_NEW) { 635 final DetailAST child = newAst.getFirstChild(); 636 returnValue.add(getExceptionInfo(child)); 637 } 638 } 639 } 640 } 641 return returnValue; 642 } 643 644 /** 645 * Get ExceptionInfo instance. 646 * 647 * @param ast DetailAST object where to find exceptions node; 648 * @return ExceptionInfo 649 */ 650 private static ExceptionInfo getExceptionInfo(DetailAST ast) { 651 final FullIdent ident = FullIdent.createFullIdent(ast); 652 final DetailAST firstClassNameNode = getFirstClassNameNode(ast); 653 return new ExceptionInfo(firstClassNameNode, 654 new ClassInfo(new Token(ident))); 655 } 656 657 /** 658 * Get node where class name of exception starts. 659 * 660 * @param ast DetailAST object where to find exceptions node; 661 * @return exception node where class name starts 662 */ 663 private static DetailAST getFirstClassNameNode(DetailAST ast) { 664 DetailAST startNode = ast; 665 while (startNode.getType() == TokenTypes.DOT) { 666 startNode = startNode.getFirstChild(); 667 } 668 return startNode; 669 } 670 671 /** 672 * Checks if a 'throw' usage is contained within a block that should be ignored. 673 * Such blocks consist of try (with catch) blocks, local classes, anonymous classes, 674 * and lambda expressions. Note that a try block without catch is not considered. 675 * 676 * @param methodBodyAst DetailAST node representing the method body 677 * @param throwAst DetailAST node representing the 'throw' literal 678 * @return true if throwAst is inside a block that should be ignored 679 */ 680 private static boolean isInIgnoreBlock(DetailAST methodBodyAst, DetailAST throwAst) { 681 DetailAST ancestor = throwAst; 682 while (ancestor != methodBodyAst) { 683 if (ancestor.getType() == TokenTypes.LAMBDA 684 || ancestor.getType() == TokenTypes.OBJBLOCK 685 || ancestor.findFirstToken(TokenTypes.LITERAL_CATCH) != null) { 686 // throw is inside a lambda expression/anonymous class/local class, 687 // or throw is inside a try block, and there is a catch block 688 break; 689 } 690 if (ancestor.getType() == TokenTypes.LITERAL_CATCH 691 || ancestor.getType() == TokenTypes.LITERAL_FINALLY) { 692 // if the throw is inside a catch or finally block, 693 // skip the immediate ancestor (try token) 694 ancestor = ancestor.getParent(); 695 } 696 ancestor = ancestor.getParent(); 697 } 698 return ancestor != methodBodyAst; 699 } 700 701 /** 702 * Combine ExceptionInfo collections together by matching names. 703 * 704 * @param first the first collection of ExceptionInfo 705 * @param second the second collection of ExceptionInfo 706 * @return combined list of ExceptionInfo 707 */ 708 private static List<ExceptionInfo> combineExceptionInfo(Collection<ExceptionInfo> first, 709 Iterable<ExceptionInfo> second) { 710 final List<ExceptionInfo> result = new ArrayList<>(first); 711 for (ExceptionInfo exceptionInfo : second) { 712 if (result.stream().noneMatch(item -> isExceptionInfoSame(item, exceptionInfo))) { 713 result.add(exceptionInfo); 714 } 715 } 716 return result; 717 } 718 719 /** 720 * Finds node of specified type among root children, siblings, siblings children 721 * on any deep level. 722 * 723 * @param root DetailAST 724 * @param astType value of TokenType 725 * @return {@link List} of {@link DetailAST} nodes which matches the predicate. 726 */ 727 public static List<DetailAST> findTokensInAstByType(DetailAST root, int astType) { 728 final List<DetailAST> result = new ArrayList<>(); 729 // iterative preorder depth-first search 730 DetailAST curNode = root; 731 do { 732 // process curNode 733 if (curNode.getType() == astType) { 734 result.add(curNode); 735 } 736 // process children (if any) 737 if (curNode.hasChildren()) { 738 curNode = curNode.getFirstChild(); 739 continue; 740 } 741 // backtrack to parent if last child, stopping at root 742 while (curNode != root && curNode.getNextSibling() == null) { 743 curNode = curNode.getParent(); 744 } 745 // explore siblings if not root 746 if (curNode != root) { 747 curNode = curNode.getNextSibling(); 748 } 749 } while (curNode != root); 750 return result; 751 } 752 753 /** 754 * Checks a set of tags for matching parameters. 755 * 756 * @param tags the tags to check 757 * @param parent the node which takes the parameters 758 * @param reportExpectedTags whether we should report if do not find 759 * expected tag 760 */ 761 private void checkParamTags(final List<JavadocTag> tags, 762 final DetailAST parent, boolean reportExpectedTags) { 763 final List<DetailAST> params = getParameters(parent); 764 final List<DetailAST> typeParams = CheckUtil 765 .getTypeParameters(parent); 766 767 // Loop over the tags, checking to see they exist in the params. 768 final ListIterator<JavadocTag> tagIt = tags.listIterator(); 769 while (tagIt.hasNext()) { 770 final JavadocTag tag = tagIt.next(); 771 772 if (!tag.isParamTag()) { 773 continue; 774 } 775 776 tagIt.remove(); 777 778 final String arg1 = tag.getFirstArg(); 779 boolean found = removeMatchingParam(params, arg1); 780 781 if (arg1.startsWith(ELEMENT_START) && arg1.endsWith(ELEMENT_END)) { 782 found = searchMatchingTypeParameter(typeParams, 783 arg1.substring(1, arg1.length() - 1)); 784 } 785 786 // Handle extra JavadocTag 787 if (!found) { 788 log(tag.getLineNo(), tag.getColumnNo(), MSG_UNUSED_TAG, 789 "@param", arg1); 790 } 791 } 792 793 // Now dump out all type parameters/parameters without tags :- unless 794 // the user has chosen to suppress these problems 795 if (!allowMissingParamTags && reportExpectedTags) { 796 for (DetailAST param : params) { 797 log(param, MSG_EXPECTED_TAG, 798 JavadocTagInfo.PARAM.getText(), param.getText()); 799 } 800 801 for (DetailAST typeParam : typeParams) { 802 log(typeParam, MSG_EXPECTED_TAG, 803 JavadocTagInfo.PARAM.getText(), 804 ELEMENT_START + typeParam.findFirstToken(TokenTypes.IDENT).getText() 805 + ELEMENT_END); 806 } 807 } 808 } 809 810 /** 811 * Returns true if required type found in type parameters. 812 * 813 * @param typeParams 814 * collection of type parameters 815 * @param requiredTypeName 816 * name of required type 817 * @return true if required type found in type parameters. 818 */ 819 private static boolean searchMatchingTypeParameter(Iterable<DetailAST> typeParams, 820 String requiredTypeName) { 821 // Loop looking for matching type param 822 final Iterator<DetailAST> typeParamsIt = typeParams.iterator(); 823 boolean found = false; 824 while (typeParamsIt.hasNext()) { 825 final DetailAST typeParam = typeParamsIt.next(); 826 if (typeParam.findFirstToken(TokenTypes.IDENT).getText() 827 .equals(requiredTypeName)) { 828 found = true; 829 typeParamsIt.remove(); 830 break; 831 } 832 } 833 return found; 834 } 835 836 /** 837 * Remove parameter from params collection by name. 838 * 839 * @param params collection of DetailAST parameters 840 * @param paramName name of parameter 841 * @return true if parameter found and removed 842 */ 843 private static boolean removeMatchingParam(Iterable<DetailAST> params, String paramName) { 844 boolean found = false; 845 final Iterator<DetailAST> paramIt = params.iterator(); 846 while (paramIt.hasNext()) { 847 final DetailAST param = paramIt.next(); 848 if (param.getText().equals(paramName)) { 849 found = true; 850 paramIt.remove(); 851 break; 852 } 853 } 854 return found; 855 } 856 857 /** 858 * Checks for only one return tag. All return tags will be removed from the 859 * supplied list. 860 * 861 * @param tags the tags to check 862 * @param lineNo the line number of the expected tag 863 * @param reportExpectedTags whether we should report if do not find 864 * expected tag 865 */ 866 private void checkReturnTag(List<JavadocTag> tags, int lineNo, 867 boolean reportExpectedTags) { 868 // Loop over tags finding return tags. After the first one, report a 869 // violation. 870 boolean found = false; 871 final ListIterator<JavadocTag> it = tags.listIterator(); 872 while (it.hasNext()) { 873 final JavadocTag javadocTag = it.next(); 874 if (javadocTag.isReturnTag()) { 875 if (found) { 876 log(javadocTag.getLineNo(), javadocTag.getColumnNo(), 877 MSG_DUPLICATE_TAG, 878 JavadocTagInfo.RETURN.getText()); 879 } 880 found = true; 881 it.remove(); 882 } 883 } 884 885 // Handle there being no @return tags :- unless 886 // the user has chosen to suppress these problems 887 if (!found && !allowMissingReturnTag && reportExpectedTags) { 888 log(lineNo, MSG_RETURN_EXPECTED); 889 } 890 } 891 892 /** 893 * Checks a set of tags for matching throws. 894 * 895 * @param tags the tags to check 896 * @param throwsList the throws to check 897 * @param reportExpectedTags whether we should report if do not find 898 * expected tag 899 */ 900 private void checkThrowsTags(List<JavadocTag> tags, 901 List<ExceptionInfo> throwsList, boolean reportExpectedTags) { 902 // Loop over the tags, checking to see they exist in the throws. 903 final ListIterator<JavadocTag> tagIt = tags.listIterator(); 904 while (tagIt.hasNext()) { 905 final JavadocTag tag = tagIt.next(); 906 907 if (!tag.isThrowsTag()) { 908 continue; 909 } 910 tagIt.remove(); 911 912 // Loop looking for matching throw 913 processThrows(throwsList, tag.getFirstArg()); 914 } 915 // Now dump out all throws without tags :- unless 916 // the user has chosen to suppress these problems 917 if (validateThrows && reportExpectedTags) { 918 throwsList.stream().filter(exceptionInfo -> !exceptionInfo.isFound()) 919 .forEach(exceptionInfo -> { 920 final Token token = exceptionInfo.getName(); 921 log(exceptionInfo.getAst(), 922 MSG_EXPECTED_TAG, 923 JavadocTagInfo.THROWS.getText(), token.getText()); 924 }); 925 } 926 } 927 928 /** 929 * Verifies that documented exception is in throws. 930 * 931 * @param throwsIterable collection of throws 932 * @param documentedClassName documented exception class name 933 */ 934 private static void processThrows(Iterable<ExceptionInfo> throwsIterable, 935 String documentedClassName) { 936 for (ExceptionInfo exceptionInfo : throwsIterable) { 937 if (isClassNamesSame(exceptionInfo.getName().getText(), 938 documentedClassName)) { 939 exceptionInfo.setFound(); 940 break; 941 } 942 } 943 } 944 945 /** 946 * Check that ExceptionInfo objects are same by name. 947 * 948 * @param info1 ExceptionInfo object 949 * @param info2 ExceptionInfo object 950 * @return true is ExceptionInfo object have the same name 951 */ 952 private static boolean isExceptionInfoSame(ExceptionInfo info1, ExceptionInfo info2) { 953 return isClassNamesSame(info1.getName().getText(), 954 info2.getName().getText()); 955 } 956 957 /** 958 * Check that class names are same by short name of class. If some class name is fully 959 * qualified it is cut to short name. 960 * 961 * @param class1 class name 962 * @param class2 class name 963 * @return true is ExceptionInfo object have the same name 964 */ 965 private static boolean isClassNamesSame(String class1, String class2) { 966 boolean result = false; 967 if (class1.equals(class2)) { 968 result = true; 969 } 970 else { 971 final String separator = "."; 972 if (class1.contains(separator) || class2.contains(separator)) { 973 final String class1ShortName = class1 974 .substring(class1.lastIndexOf('.') + 1); 975 final String class2ShortName = class2 976 .substring(class2.lastIndexOf('.') + 1); 977 result = class1ShortName.equals(class2ShortName); 978 } 979 } 980 return result; 981 } 982 983 /** 984 * Contains class's {@code Token}. 985 */ 986 private static class ClassInfo { 987 988 /** {@code FullIdent} associated with this class. */ 989 private final Token name; 990 991 /** 992 * Creates new instance of class information object. 993 * 994 * @param className token which represents class name. 995 * @throws IllegalArgumentException when className is nulls 996 */ 997 protected ClassInfo(final Token className) { 998 name = className; 999 } 1000 1001 /** 1002 * Gets class name. 1003 * 1004 * @return class name 1005 */ 1006 public final Token getName() { 1007 return name; 1008 } 1009 1010 } 1011 1012 /** 1013 * Represents text element with location in the text. 1014 */ 1015 private static final class Token { 1016 1017 /** Token's column number. */ 1018 private final int columnNo; 1019 /** Token's line number. */ 1020 private final int lineNo; 1021 /** Token's text. */ 1022 private final String text; 1023 1024 /** 1025 * Creates token. 1026 * 1027 * @param text token's text 1028 * @param lineNo token's line number 1029 * @param columnNo token's column number 1030 */ 1031 private Token(String text, int lineNo, int columnNo) { 1032 this.text = text; 1033 this.lineNo = lineNo; 1034 this.columnNo = columnNo; 1035 } 1036 1037 /** 1038 * Converts FullIdent to Token. 1039 * 1040 * @param fullIdent full ident to convert. 1041 */ 1042 private Token(FullIdent fullIdent) { 1043 text = fullIdent.getText(); 1044 lineNo = fullIdent.getLineNo(); 1045 columnNo = fullIdent.getColumnNo(); 1046 } 1047 1048 /** 1049 * Gets text of the token. 1050 * 1051 * @return text of the token 1052 */ 1053 public String getText() { 1054 return text; 1055 } 1056 1057 @Override 1058 public String toString() { 1059 return "Token[" + text + "(" + lineNo 1060 + "x" + columnNo + ")]"; 1061 } 1062 1063 } 1064 1065 /** Stores useful information about declared exception. */ 1066 private static final class ExceptionInfo { 1067 1068 /** AST node representing this exception. */ 1069 private final DetailAST ast; 1070 1071 /** Class information associated with this exception. */ 1072 private final ClassInfo classInfo; 1073 /** Does the exception have throws tag associated with. */ 1074 private boolean found; 1075 1076 /** 1077 * Creates new instance for {@code FullIdent}. 1078 * 1079 * @param ast AST node representing this exception 1080 * @param classInfo class info 1081 */ 1082 private ExceptionInfo(DetailAST ast, ClassInfo classInfo) { 1083 this.ast = ast; 1084 this.classInfo = classInfo; 1085 } 1086 1087 /** 1088 * Gets the AST node representing this exception. 1089 * 1090 * @return the AST node representing this exception 1091 */ 1092 private DetailAST getAst() { 1093 return ast; 1094 } 1095 1096 /** Mark that the exception has associated throws tag. */ 1097 private void setFound() { 1098 found = true; 1099 } 1100 1101 /** 1102 * Checks that the exception has throws tag associated with it. 1103 * 1104 * @return whether the exception has throws tag associated with 1105 */ 1106 private boolean isFound() { 1107 return found; 1108 } 1109 1110 /** 1111 * Gets exception name. 1112 * 1113 * @return exception's name 1114 */ 1115 private Token getName() { 1116 return classInfo.getName(); 1117 } 1118 1119 } 1120 1121}