001//////////////////////////////////////////////////////////////////////////////// 002// checkstyle: Checks Java source code for adherence to a set of rules. 003// Copyright (C) 2001-2021 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.ArrayDeque; 023import java.util.Arrays; 024import java.util.Collections; 025import java.util.Deque; 026import java.util.List; 027import java.util.Locale; 028import java.util.Set; 029import java.util.TreeSet; 030import java.util.regex.Pattern; 031import java.util.stream.Collectors; 032 033import com.puppycrawl.tools.checkstyle.JavadocDetailNodeParser; 034import com.puppycrawl.tools.checkstyle.StatelessCheck; 035import com.puppycrawl.tools.checkstyle.api.AbstractCheck; 036import com.puppycrawl.tools.checkstyle.api.DetailAST; 037import com.puppycrawl.tools.checkstyle.api.FileContents; 038import com.puppycrawl.tools.checkstyle.api.Scope; 039import com.puppycrawl.tools.checkstyle.api.TextBlock; 040import com.puppycrawl.tools.checkstyle.api.TokenTypes; 041import com.puppycrawl.tools.checkstyle.utils.CheckUtil; 042import com.puppycrawl.tools.checkstyle.utils.CommonUtil; 043import com.puppycrawl.tools.checkstyle.utils.ScopeUtil; 044 045/** 046 * <p> 047 * Validates Javadoc comments to help ensure they are well formed. 048 * </p> 049 * <p> 050 * The following checks are performed: 051 * </p> 052 * <ul> 053 * <li> 054 * Ensures the first sentence ends with proper punctuation 055 * (That is a period, question mark, or exclamation mark, by default). 056 * Javadoc automatically places the first sentence in the method summary 057 * table and index. Without proper punctuation the Javadoc may be malformed. 058 * All items eligible for the {@code {@inheritDoc}} tag are exempt from this 059 * requirement. 060 * </li> 061 * <li> 062 * Check text for Javadoc statements that do not have any description. 063 * This includes both completely empty Javadoc, and Javadoc with only tags 064 * such as {@code @param} and {@code @return}. 065 * </li> 066 * <li> 067 * Check text for incomplete HTML tags. Verifies that HTML tags have 068 * corresponding end tags and issues an "Unclosed HTML tag found:" error if not. 069 * An "Extra HTML tag found:" error is issued if an end tag is found without 070 * a previous open tag. 071 * </li> 072 * <li> 073 * Check that a package Javadoc comment is well-formed (as described above) and 074 * NOT missing from any package-info.java files. 075 * </li> 076 * <li> 077 * Check for allowed HTML tags. The list of allowed HTML tags is 078 * "a", "abbr", "acronym", "address", "area", "b", "bdo", "big", "blockquote", 079 * "br", "caption", "cite", "code", "colgroup", "dd", "del", "dfn", "div", "dl", 080 * "dt", "em", "fieldset", "font", "h1", "h2", "h3", "h4", "h5", "h6", "hr", 081 * "i", "img", "ins", "kbd", "li", "ol", "p", "pre", "q", "samp", "small", 082 * "span", "strong", "sub", "sup", "table", "tbody", "td", "tfoot", "th", 083 * "thead", "tr", "tt", "u", "ul", "var". 084 * </li> 085 * </ul> 086 * <p> 087 * These checks were patterned after the checks made by the 088 * <a href="http://maven-doccheck.sourceforge.net/">DocCheck</a> doclet 089 * available from Sun. Note: Original Sun's DocCheck tool does not exist anymore. 090 * </p> 091 * <ul> 092 * <li> 093 * Property {@code scope} - Specify the visibility scope where Javadoc comments are checked. 094 * Type is {@code com.puppycrawl.tools.checkstyle.api.Scope}. 095 * Default value is {@code private}. 096 * </li> 097 * <li> 098 * Property {@code excludeScope} - Specify the visibility scope where 099 * Javadoc comments are not checked. 100 * Type is {@code com.puppycrawl.tools.checkstyle.api.Scope}. 101 * Default value is {@code null}. 102 * </li> 103 * <li> 104 * Property {@code checkFirstSentence} - Control whether to check the first 105 * sentence for proper end of sentence. 106 * Type is {@code boolean}. 107 * Default value is {@code true}. 108 * </li> 109 * <li> 110 * Property {@code endOfSentenceFormat} - Specify the format for matching 111 * the end of a sentence. 112 * Type is {@code java.util.regex.Pattern}. 113 * Default value is {@code "([.?!][ \t\n\r\f<])|([.?!]$)"}. 114 * </li> 115 * <li> 116 * Property {@code checkEmptyJavadoc} - Control whether to check if the Javadoc 117 * is missing a describing text. 118 * Type is {@code boolean}. 119 * Default value is {@code false}. 120 * </li> 121 * <li> 122 * Property {@code checkHtml} - Control whether to check for incomplete HTML tags. 123 * Type is {@code boolean}. 124 * Default value is {@code true}. 125 * </li> 126 * <li> 127 * Property {@code tokens} - tokens to check 128 * Type is {@code java.lang.String[]}. 129 * Validation type is {@code tokenSet}. 130 * Default value is: 131 * <a href="https://checkstyle.org/apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#ANNOTATION_DEF"> 132 * ANNOTATION_DEF</a>, 133 * <a href="https://checkstyle.org/apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#ANNOTATION_FIELD_DEF"> 134 * ANNOTATION_FIELD_DEF</a>, 135 * <a href="https://checkstyle.org/apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#CLASS_DEF"> 136 * CLASS_DEF</a>, 137 * <a href="https://checkstyle.org/apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#CTOR_DEF"> 138 * CTOR_DEF</a>, 139 * <a href="https://checkstyle.org/apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#ENUM_CONSTANT_DEF"> 140 * ENUM_CONSTANT_DEF</a>, 141 * <a href="https://checkstyle.org/apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#ENUM_DEF"> 142 * ENUM_DEF</a>, 143 * <a href="https://checkstyle.org/apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#INTERFACE_DEF"> 144 * INTERFACE_DEF</a>, 145 * <a href="https://checkstyle.org/apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#METHOD_DEF"> 146 * METHOD_DEF</a>, 147 * <a href="https://checkstyle.org/apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#PACKAGE_DEF"> 148 * PACKAGE_DEF</a>, 149 * <a href="https://checkstyle.org/apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#VARIABLE_DEF"> 150 * VARIABLE_DEF</a>, 151 * <a href="https://checkstyle.org/apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#RECORD_DEF"> 152 * RECORD_DEF</a>, 153 * <a href="https://checkstyle.org/apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#COMPACT_CTOR_DEF"> 154 * COMPACT_CTOR_DEF</a>. 155 * </li> 156 * </ul> 157 * <p> 158 * To configure the default check: 159 * </p> 160 * <pre> 161 * <module name="JavadocStyle"/> 162 * </pre> 163 * <p>Example:</p> 164 * <pre> 165 * public class Test { 166 * /** 167 * * Some description here. // OK 168 * */ 169 * private void methodWithValidCommentStyle() {} 170 * 171 * /** 172 * * Some description here // violation, the sentence must end with a proper punctuation 173 * */ 174 * private void methodWithInvalidCommentStyle() {} 175 * } 176 * </pre> 177 * <p> 178 * To configure the check for {@code public} scope: 179 * </p> 180 * <pre> 181 * <module name="JavadocStyle"> 182 * <property name="scope" value="public"/> 183 * </module> 184 * </pre> 185 * <p>Example:</p> 186 * <pre> 187 * public class Test { 188 * /** 189 * * Some description here // violation, the sentence must end with a proper punctuation 190 * */ 191 * public void test1() {} 192 * 193 * /** 194 * * Some description here // OK 195 * */ 196 * private void test2() {} 197 * } 198 * </pre> 199 * <p> 200 * To configure the check for javadoc which is in {@code private}, but not in {@code package} scope: 201 * </p> 202 * <pre> 203 * <module name="JavadocStyle"> 204 * <property name="scope" value="private"/> 205 * <property name="excludeScope" value="package"/> 206 * </module> 207 * </pre> 208 * <p>Example:</p> 209 * <pre> 210 * public class Test { 211 * /** 212 * * Some description here // violation, the sentence must end with a proper punctuation 213 * */ 214 * private void test1() {} 215 * 216 * /** 217 * * Some description here // OK 218 * */ 219 * void test2() {} 220 * } 221 * </pre> 222 * <p> 223 * To configure the check to turn off first sentence checking: 224 * </p> 225 * <pre> 226 * <module name="JavadocStyle"> 227 * <property name="checkFirstSentence" value="false"/> 228 * </module> 229 * </pre> 230 * <p>Example:</p> 231 * <pre> 232 * public class Test { 233 * /** 234 * * Some description here // OK 235 * * Second line of description // violation, the sentence must end with a proper punctuation 236 * */ 237 * private void test1() {} 238 * } 239 * </pre> 240 * <p> 241 * To configure the check to turn off validation of incomplete html tags: 242 * </p> 243 * <pre> 244 * <module name="JavadocStyle"> 245 * <property name="checkHtml" value="false"/> 246 * </module> 247 * </pre> 248 * <p>Example:</p> 249 * <pre> 250 * public class Test { 251 * /** 252 * * Some description here // violation, the sentence must end with a proper punctuation 253 * * <p // OK 254 * */ 255 * private void test1() {} 256 * } 257 * </pre> 258 * <p> 259 * To configure the check for only class definitions: 260 * </p> 261 * <pre> 262 * <module name="JavadocStyle"> 263 * <property name="tokens" value="CLASS_DEF"/> 264 * </module> 265 * </pre> 266 * <p>Example:</p> 267 * <pre> 268 * /** 269 * * Some description here // violation, the sentence must end with a proper punctuation 270 * */ 271 * public class Test { 272 * /** 273 * * Some description here // OK 274 * */ 275 * private void test1() {} 276 * } 277 * </pre> 278 * <p> 279 * Parent is {@code com.puppycrawl.tools.checkstyle.TreeWalker} 280 * </p> 281 * <p> 282 * Violation Message Keys: 283 * </p> 284 * <ul> 285 * <li> 286 * {@code javadoc.empty} 287 * </li> 288 * <li> 289 * {@code javadoc.extraHtml} 290 * </li> 291 * <li> 292 * {@code javadoc.incompleteTag} 293 * </li> 294 * <li> 295 * {@code javadoc.missing} 296 * </li> 297 * <li> 298 * {@code javadoc.noPeriod} 299 * </li> 300 * <li> 301 * {@code javadoc.unclosedHtml} 302 * </li> 303 * </ul> 304 * 305 * @since 3.2 306 */ 307@StatelessCheck 308public class JavadocStyleCheck 309 extends AbstractCheck { 310 311 /** Message property key for the Missing Javadoc message. */ 312 public static final String MSG_JAVADOC_MISSING = "javadoc.missing"; 313 314 /** Message property key for the Empty Javadoc message. */ 315 public static final String MSG_EMPTY = "javadoc.empty"; 316 317 /** Message property key for the No Javadoc end of Sentence Period message. */ 318 public static final String MSG_NO_PERIOD = "javadoc.noPeriod"; 319 320 /** Message property key for the Incomplete Tag message. */ 321 public static final String MSG_INCOMPLETE_TAG = "javadoc.incompleteTag"; 322 323 /** Message property key for the Unclosed HTML message. */ 324 public static final String MSG_UNCLOSED_HTML = JavadocDetailNodeParser.MSG_UNCLOSED_HTML_TAG; 325 326 /** Message property key for the Extra HTML message. */ 327 public static final String MSG_EXTRA_HTML = "javadoc.extraHtml"; 328 329 /** HTML tags that do not require a close tag. */ 330 private static final Set<String> SINGLE_TAGS = Collections.unmodifiableSortedSet( 331 Arrays.stream(new String[] {"br", "li", "dt", "dd", "hr", "img", "p", "td", "tr", "th", }) 332 .collect(Collectors.toCollection(TreeSet::new))); 333 334 /** 335 * HTML tags that are allowed in java docs. 336 * From https://www.w3schools.com/tags/default.asp 337 * The forms and structure tags are not allowed 338 */ 339 private static final Set<String> ALLOWED_TAGS = Collections.unmodifiableSortedSet( 340 Arrays.stream(new String[] { 341 "a", "abbr", "acronym", "address", "area", "b", "bdo", "big", 342 "blockquote", "br", "caption", "cite", "code", "colgroup", "dd", 343 "del", "dfn", "div", "dl", "dt", "em", "fieldset", "font", "h1", 344 "h2", "h3", "h4", "h5", "h6", "hr", "i", "img", "ins", "kbd", 345 "li", "ol", "p", "pre", "q", "samp", "small", "span", "strong", 346 "sub", "sup", "table", "tbody", "td", "tfoot", "th", "thead", 347 "tr", "tt", "u", "ul", "var", }) 348 .collect(Collectors.toCollection(TreeSet::new))); 349 350 /** Specify the visibility scope where Javadoc comments are checked. */ 351 private Scope scope = Scope.PRIVATE; 352 353 /** Specify the visibility scope where Javadoc comments are not checked. */ 354 private Scope excludeScope; 355 356 /** Specify the format for matching the end of a sentence. */ 357 private Pattern endOfSentenceFormat = Pattern.compile("([.?!][ \t\n\r\f<])|([.?!]$)"); 358 359 /** 360 * Control whether to check the first sentence for proper end of sentence. 361 */ 362 private boolean checkFirstSentence = true; 363 364 /** 365 * Control whether to check for incomplete HTML tags. 366 */ 367 private boolean checkHtml = true; 368 369 /** 370 * Control whether to check if the Javadoc is missing a describing text. 371 */ 372 private boolean checkEmptyJavadoc; 373 374 @Override 375 public int[] getDefaultTokens() { 376 return getAcceptableTokens(); 377 } 378 379 @Override 380 public int[] getAcceptableTokens() { 381 return new int[] { 382 TokenTypes.ANNOTATION_DEF, 383 TokenTypes.ANNOTATION_FIELD_DEF, 384 TokenTypes.CLASS_DEF, 385 TokenTypes.CTOR_DEF, 386 TokenTypes.ENUM_CONSTANT_DEF, 387 TokenTypes.ENUM_DEF, 388 TokenTypes.INTERFACE_DEF, 389 TokenTypes.METHOD_DEF, 390 TokenTypes.PACKAGE_DEF, 391 TokenTypes.VARIABLE_DEF, 392 TokenTypes.RECORD_DEF, 393 TokenTypes.COMPACT_CTOR_DEF, 394 }; 395 } 396 397 @Override 398 public int[] getRequiredTokens() { 399 return CommonUtil.EMPTY_INT_ARRAY; 400 } 401 402 @Override 403 public void visitToken(DetailAST ast) { 404 if (shouldCheck(ast)) { 405 final FileContents contents = getFileContents(); 406 // Need to start searching for the comment before the annotations 407 // that may exist. Even if annotations are not defined on the 408 // package, the ANNOTATIONS AST is defined. 409 final TextBlock textBlock = 410 contents.getJavadocBefore(ast.getFirstChild().getLineNo()); 411 412 checkComment(ast, textBlock); 413 } 414 } 415 416 /** 417 * Whether we should check this node. 418 * 419 * @param ast a given node. 420 * @return whether we should check a given node. 421 */ 422 private boolean shouldCheck(final DetailAST ast) { 423 boolean check = false; 424 425 if (ast.getType() == TokenTypes.PACKAGE_DEF) { 426 check = getFileContents().inPackageInfo(); 427 } 428 else if (!ScopeUtil.isInCodeBlock(ast)) { 429 final Scope customScope = ScopeUtil.getScope(ast); 430 final Scope surroundingScope = ScopeUtil.getSurroundingScope(ast); 431 432 check = customScope.isIn(scope) 433 && (surroundingScope == null || surroundingScope.isIn(scope)) 434 && (excludeScope == null 435 || !customScope.isIn(excludeScope) 436 || surroundingScope != null 437 && !surroundingScope.isIn(excludeScope)); 438 } 439 return check; 440 } 441 442 /** 443 * Performs the various checks against the Javadoc comment. 444 * 445 * @param ast the AST of the element being documented 446 * @param comment the source lines that make up the Javadoc comment. 447 * 448 * @see #checkFirstSentenceEnding(DetailAST, TextBlock) 449 * @see #checkHtmlTags(DetailAST, TextBlock) 450 */ 451 private void checkComment(final DetailAST ast, final TextBlock comment) { 452 if (comment == null) { 453 // checking for missing docs in JavadocStyleCheck is not consistent 454 // with the rest of CheckStyle... Even though, I didn't think it 455 // made sense to make another check just to ensure that the 456 // package-info.java file actually contains package Javadocs. 457 if (getFileContents().inPackageInfo()) { 458 log(ast, MSG_JAVADOC_MISSING); 459 } 460 } 461 else { 462 if (checkFirstSentence) { 463 checkFirstSentenceEnding(ast, comment); 464 } 465 466 if (checkHtml) { 467 checkHtmlTags(ast, comment); 468 } 469 470 if (checkEmptyJavadoc) { 471 checkJavadocIsNotEmpty(comment); 472 } 473 } 474 } 475 476 /** 477 * Checks that the first sentence ends with proper punctuation. This method 478 * uses a regular expression that checks for the presence of a period, 479 * question mark, or exclamation mark followed either by whitespace, an 480 * HTML element, or the end of string. This method ignores {_AT_inheritDoc} 481 * comments for TokenTypes that are valid for {_AT_inheritDoc}. 482 * 483 * @param ast the current node 484 * @param comment the source lines that make up the Javadoc comment. 485 */ 486 private void checkFirstSentenceEnding(final DetailAST ast, TextBlock comment) { 487 final String commentText = getCommentText(comment.getText()); 488 489 if (!commentText.isEmpty() 490 && !endOfSentenceFormat.matcher(commentText).find() 491 && !(commentText.startsWith("{@inheritDoc}") 492 && JavadocTagInfo.INHERIT_DOC.isValidOn(ast))) { 493 log(comment.getStartLineNo(), MSG_NO_PERIOD); 494 } 495 } 496 497 /** 498 * Checks that the Javadoc is not empty. 499 * 500 * @param comment the source lines that make up the Javadoc comment. 501 */ 502 private void checkJavadocIsNotEmpty(TextBlock comment) { 503 final String commentText = getCommentText(comment.getText()); 504 505 if (commentText.isEmpty()) { 506 log(comment.getStartLineNo(), MSG_EMPTY); 507 } 508 } 509 510 /** 511 * Returns the comment text from the Javadoc. 512 * 513 * @param comments the lines of Javadoc. 514 * @return a comment text String. 515 */ 516 private static String getCommentText(String... comments) { 517 final StringBuilder builder = new StringBuilder(1024); 518 for (final String line : comments) { 519 final int textStart = findTextStart(line); 520 521 if (textStart != -1) { 522 if (line.charAt(textStart) == '@') { 523 // we have found the tag section 524 break; 525 } 526 builder.append(line.substring(textStart)); 527 trimTail(builder); 528 builder.append('\n'); 529 } 530 } 531 532 return builder.toString().trim(); 533 } 534 535 /** 536 * Finds the index of the first non-whitespace character ignoring the 537 * Javadoc comment start and end strings (/** and */) as well as any 538 * leading asterisk. 539 * 540 * @param line the Javadoc comment line of text to scan. 541 * @return the int index relative to 0 for the start of text 542 * or -1 if not found. 543 */ 544 private static int findTextStart(String line) { 545 int textStart = -1; 546 int index = 0; 547 while (index < line.length()) { 548 if (!Character.isWhitespace(line.charAt(index))) { 549 if (line.regionMatches(index, "/**", 0, "/**".length())) { 550 index += 2; 551 } 552 else if (line.regionMatches(index, "*/", 0, 2)) { 553 index++; 554 } 555 else if (line.charAt(index) != '*') { 556 textStart = index; 557 break; 558 } 559 } 560 index++; 561 } 562 return textStart; 563 } 564 565 /** 566 * Trims any trailing whitespace or the end of Javadoc comment string. 567 * 568 * @param builder the StringBuilder to trim. 569 */ 570 private static void trimTail(StringBuilder builder) { 571 int index = builder.length() - 1; 572 while (true) { 573 if (Character.isWhitespace(builder.charAt(index))) { 574 builder.deleteCharAt(index); 575 } 576 else if (index > 0 && builder.charAt(index) == '/' 577 && builder.charAt(index - 1) == '*') { 578 builder.deleteCharAt(index); 579 builder.deleteCharAt(index - 1); 580 index--; 581 while (builder.charAt(index - 1) == '*') { 582 builder.deleteCharAt(index - 1); 583 index--; 584 } 585 } 586 else { 587 break; 588 } 589 index--; 590 } 591 } 592 593 /** 594 * Checks the comment for HTML tags that do not have a corresponding close 595 * tag or a close tag that has no previous open tag. This code was 596 * primarily copied from the DocCheck checkHtml method. 597 * 598 * @param ast the node with the Javadoc 599 * @param comment the {@code TextBlock} which represents 600 * the Javadoc comment. 601 * @noinspection MethodWithMultipleReturnPoints 602 */ 603 // -@cs[ReturnCount] Too complex to break apart. 604 private void checkHtmlTags(final DetailAST ast, final TextBlock comment) { 605 final int lineNo = comment.getStartLineNo(); 606 final Deque<HtmlTag> htmlStack = new ArrayDeque<>(); 607 final String[] text = comment.getText(); 608 609 final TagParser parser = new TagParser(text, lineNo); 610 611 while (parser.hasNextTag()) { 612 final HtmlTag tag = parser.nextTag(); 613 614 if (tag.isIncompleteTag()) { 615 log(tag.getLineNo(), MSG_INCOMPLETE_TAG, 616 text[tag.getLineNo() - lineNo]); 617 return; 618 } 619 if (tag.isClosedTag()) { 620 // do nothing 621 continue; 622 } 623 if (tag.isCloseTag()) { 624 // We have found a close tag. 625 if (isExtraHtml(tag.getId(), htmlStack)) { 626 // No corresponding open tag was found on the stack. 627 log(tag.getLineNo(), 628 tag.getPosition(), 629 MSG_EXTRA_HTML, 630 tag.getText()); 631 } 632 else { 633 // See if there are any unclosed tags that were opened 634 // after this one. 635 checkUnclosedTags(htmlStack, tag.getId()); 636 } 637 } 638 else { 639 // We only push html tags that are allowed 640 if (isAllowedTag(tag)) { 641 htmlStack.push(tag); 642 } 643 } 644 } 645 646 // Identify any tags left on the stack. 647 // Skip multiples, like <b>...<b> 648 String lastFound = ""; 649 final List<String> typeParameters = CheckUtil.getTypeParameterNames(ast); 650 for (final HtmlTag htmlTag : htmlStack) { 651 if (!isSingleTag(htmlTag) 652 && !htmlTag.getId().equals(lastFound) 653 && !typeParameters.contains(htmlTag.getId())) { 654 log(htmlTag.getLineNo(), htmlTag.getPosition(), 655 MSG_UNCLOSED_HTML, htmlTag.getText()); 656 lastFound = htmlTag.getId(); 657 } 658 } 659 } 660 661 /** 662 * Checks to see if there are any unclosed tags on the stack. The token 663 * represents a html tag that has been closed and has a corresponding open 664 * tag on the stack. Any tags, except single tags, that were opened 665 * (pushed on the stack) after the token are missing a close. 666 * 667 * @param htmlStack the stack of opened HTML tags. 668 * @param token the current HTML tag name that has been closed. 669 */ 670 private void checkUnclosedTags(Deque<HtmlTag> htmlStack, String token) { 671 final Deque<HtmlTag> unclosedTags = new ArrayDeque<>(); 672 HtmlTag lastOpenTag = htmlStack.pop(); 673 while (!token.equalsIgnoreCase(lastOpenTag.getId())) { 674 // Find unclosed elements. Put them on a stack so the 675 // output order won't be back-to-front. 676 if (isSingleTag(lastOpenTag)) { 677 lastOpenTag = htmlStack.pop(); 678 } 679 else { 680 unclosedTags.push(lastOpenTag); 681 lastOpenTag = htmlStack.pop(); 682 } 683 } 684 685 // Output the unterminated tags, if any 686 // Skip multiples, like <b>..<b> 687 String lastFound = ""; 688 for (final HtmlTag htag : unclosedTags) { 689 lastOpenTag = htag; 690 if (lastOpenTag.getId().equals(lastFound)) { 691 continue; 692 } 693 lastFound = lastOpenTag.getId(); 694 log(lastOpenTag.getLineNo(), 695 lastOpenTag.getPosition(), 696 MSG_UNCLOSED_HTML, 697 lastOpenTag.getText()); 698 } 699 } 700 701 /** 702 * Determines if the HtmlTag is one which does not require a close tag. 703 * 704 * @param tag the HtmlTag to check. 705 * @return {@code true} if the HtmlTag is a single tag. 706 */ 707 private static boolean isSingleTag(HtmlTag tag) { 708 // If its a singleton tag (<p>, <br>, etc.), ignore it 709 // Can't simply not put them on the stack, since singletons 710 // like <dt> and <dd> (unhappily) may either be terminated 711 // or not terminated. Both options are legal. 712 return SINGLE_TAGS.contains(tag.getId().toLowerCase(Locale.ENGLISH)); 713 } 714 715 /** 716 * Determines if the HtmlTag is one which is allowed in a javadoc. 717 * 718 * @param tag the HtmlTag to check. 719 * @return {@code true} if the HtmlTag is an allowed html tag. 720 */ 721 private static boolean isAllowedTag(HtmlTag tag) { 722 return ALLOWED_TAGS.contains(tag.getId().toLowerCase(Locale.ENGLISH)); 723 } 724 725 /** 726 * Determines if the given token is an extra HTML tag. This indicates that 727 * a close tag was found that does not have a corresponding open tag. 728 * 729 * @param token an HTML tag id for which a close was found. 730 * @param htmlStack a Stack of previous open HTML tags. 731 * @return {@code false} if a previous open tag was found 732 * for the token. 733 */ 734 private static boolean isExtraHtml(String token, Deque<HtmlTag> htmlStack) { 735 boolean isExtra = true; 736 for (final HtmlTag tag : htmlStack) { 737 // Loop, looking for tags that are closed. 738 // The loop is needed in case there are unclosed 739 // tags on the stack. In that case, the stack would 740 // not be empty, but this tag would still be extra. 741 if (token.equalsIgnoreCase(tag.getId())) { 742 isExtra = false; 743 break; 744 } 745 } 746 747 return isExtra; 748 } 749 750 /** 751 * Setter to specify the visibility scope where Javadoc comments are checked. 752 * 753 * @param scope a scope. 754 */ 755 public void setScope(Scope scope) { 756 this.scope = scope; 757 } 758 759 /** 760 * Setter to specify the visibility scope where Javadoc comments are not checked. 761 * 762 * @param excludeScope a scope. 763 */ 764 public void setExcludeScope(Scope excludeScope) { 765 this.excludeScope = excludeScope; 766 } 767 768 /** 769 * Setter to specify the format for matching the end of a sentence. 770 * 771 * @param pattern a pattern. 772 */ 773 public void setEndOfSentenceFormat(Pattern pattern) { 774 endOfSentenceFormat = pattern; 775 } 776 777 /** 778 * Setter to control whether to check the first sentence for proper end of sentence. 779 * 780 * @param flag {@code true} if the first sentence is to be checked 781 */ 782 public void setCheckFirstSentence(boolean flag) { 783 checkFirstSentence = flag; 784 } 785 786 /** 787 * Setter to control whether to check for incomplete HTML tags. 788 * 789 * @param flag {@code true} if HTML checking is to be performed. 790 */ 791 public void setCheckHtml(boolean flag) { 792 checkHtml = flag; 793 } 794 795 /** 796 * Setter to control whether to check if the Javadoc is missing a describing text. 797 * 798 * @param flag {@code true} if empty Javadoc checking should be done. 799 */ 800 public void setCheckEmptyJavadoc(boolean flag) { 801 checkEmptyJavadoc = flag; 802 } 803 804}