001//////////////////////////////////////////////////////////////////////////////// 002// checkstyle: Checks Java source code for adherence to a set of rules. 003// Copyright (C) 2001-2020 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; 430 431 if (ScopeUtil.isInInterfaceOrAnnotationBlock(ast) 432 || ast.getType() == TokenTypes.ENUM_CONSTANT_DEF) { 433 customScope = Scope.PUBLIC; 434 } 435 else { 436 customScope = ScopeUtil.getScopeFromMods(ast.findFirstToken(TokenTypes.MODIFIERS)); 437 } 438 final Scope surroundingScope = ScopeUtil.getSurroundingScope(ast); 439 440 check = customScope.isIn(scope) 441 && (surroundingScope == null || surroundingScope.isIn(scope)) 442 && (excludeScope == null 443 || !customScope.isIn(excludeScope) 444 || surroundingScope != null 445 && !surroundingScope.isIn(excludeScope)); 446 } 447 return check; 448 } 449 450 /** 451 * Performs the various checks against the Javadoc comment. 452 * 453 * @param ast the AST of the element being documented 454 * @param comment the source lines that make up the Javadoc comment. 455 * 456 * @see #checkFirstSentenceEnding(DetailAST, TextBlock) 457 * @see #checkHtmlTags(DetailAST, TextBlock) 458 */ 459 private void checkComment(final DetailAST ast, final TextBlock comment) { 460 if (comment == null) { 461 // checking for missing docs in JavadocStyleCheck is not consistent 462 // with the rest of CheckStyle... Even though, I didn't think it 463 // made sense to make another check just to ensure that the 464 // package-info.java file actually contains package Javadocs. 465 if (getFileContents().inPackageInfo()) { 466 log(ast, MSG_JAVADOC_MISSING); 467 } 468 } 469 else { 470 if (checkFirstSentence) { 471 checkFirstSentenceEnding(ast, comment); 472 } 473 474 if (checkHtml) { 475 checkHtmlTags(ast, comment); 476 } 477 478 if (checkEmptyJavadoc) { 479 checkJavadocIsNotEmpty(comment); 480 } 481 } 482 } 483 484 /** 485 * Checks that the first sentence ends with proper punctuation. This method 486 * uses a regular expression that checks for the presence of a period, 487 * question mark, or exclamation mark followed either by whitespace, an 488 * HTML element, or the end of string. This method ignores {_AT_inheritDoc} 489 * comments for TokenTypes that are valid for {_AT_inheritDoc}. 490 * 491 * @param ast the current node 492 * @param comment the source lines that make up the Javadoc comment. 493 */ 494 private void checkFirstSentenceEnding(final DetailAST ast, TextBlock comment) { 495 final String commentText = getCommentText(comment.getText()); 496 497 if (!commentText.isEmpty() 498 && !endOfSentenceFormat.matcher(commentText).find() 499 && !(commentText.startsWith("{@inheritDoc}") 500 && JavadocTagInfo.INHERIT_DOC.isValidOn(ast))) { 501 log(comment.getStartLineNo(), MSG_NO_PERIOD); 502 } 503 } 504 505 /** 506 * Checks that the Javadoc is not empty. 507 * 508 * @param comment the source lines that make up the Javadoc comment. 509 */ 510 private void checkJavadocIsNotEmpty(TextBlock comment) { 511 final String commentText = getCommentText(comment.getText()); 512 513 if (commentText.isEmpty()) { 514 log(comment.getStartLineNo(), MSG_EMPTY); 515 } 516 } 517 518 /** 519 * Returns the comment text from the Javadoc. 520 * 521 * @param comments the lines of Javadoc. 522 * @return a comment text String. 523 */ 524 private static String getCommentText(String... comments) { 525 final StringBuilder builder = new StringBuilder(1024); 526 for (final String line : comments) { 527 final int textStart = findTextStart(line); 528 529 if (textStart != -1) { 530 if (line.charAt(textStart) == '@') { 531 // we have found the tag section 532 break; 533 } 534 builder.append(line.substring(textStart)); 535 trimTail(builder); 536 builder.append('\n'); 537 } 538 } 539 540 return builder.toString().trim(); 541 } 542 543 /** 544 * Finds the index of the first non-whitespace character ignoring the 545 * Javadoc comment start and end strings (/** and */) as well as any 546 * leading asterisk. 547 * 548 * @param line the Javadoc comment line of text to scan. 549 * @return the int index relative to 0 for the start of text 550 * or -1 if not found. 551 */ 552 private static int findTextStart(String line) { 553 int textStart = -1; 554 int index = 0; 555 while (index < line.length()) { 556 if (!Character.isWhitespace(line.charAt(index))) { 557 if (line.regionMatches(index, "/**", 0, "/**".length())) { 558 index += 2; 559 } 560 else if (line.regionMatches(index, "*/", 0, 2)) { 561 index++; 562 } 563 else if (line.charAt(index) != '*') { 564 textStart = index; 565 break; 566 } 567 } 568 index++; 569 } 570 return textStart; 571 } 572 573 /** 574 * Trims any trailing whitespace or the end of Javadoc comment string. 575 * 576 * @param builder the StringBuilder to trim. 577 */ 578 private static void trimTail(StringBuilder builder) { 579 int index = builder.length() - 1; 580 while (true) { 581 if (Character.isWhitespace(builder.charAt(index))) { 582 builder.deleteCharAt(index); 583 } 584 else if (index > 0 && builder.charAt(index) == '/' 585 && builder.charAt(index - 1) == '*') { 586 builder.deleteCharAt(index); 587 builder.deleteCharAt(index - 1); 588 index--; 589 while (builder.charAt(index - 1) == '*') { 590 builder.deleteCharAt(index - 1); 591 index--; 592 } 593 } 594 else { 595 break; 596 } 597 index--; 598 } 599 } 600 601 /** 602 * Checks the comment for HTML tags that do not have a corresponding close 603 * tag or a close tag that has no previous open tag. This code was 604 * primarily copied from the DocCheck checkHtml method. 605 * 606 * @param ast the node with the Javadoc 607 * @param comment the {@code TextBlock} which represents 608 * the Javadoc comment. 609 * @noinspection MethodWithMultipleReturnPoints 610 */ 611 // -@cs[ReturnCount] Too complex to break apart. 612 private void checkHtmlTags(final DetailAST ast, final TextBlock comment) { 613 final int lineNo = comment.getStartLineNo(); 614 final Deque<HtmlTag> htmlStack = new ArrayDeque<>(); 615 final String[] text = comment.getText(); 616 617 final TagParser parser = new TagParser(text, lineNo); 618 619 while (parser.hasNextTag()) { 620 final HtmlTag tag = parser.nextTag(); 621 622 if (tag.isIncompleteTag()) { 623 log(tag.getLineNo(), MSG_INCOMPLETE_TAG, 624 text[tag.getLineNo() - lineNo]); 625 return; 626 } 627 if (tag.isClosedTag()) { 628 // do nothing 629 continue; 630 } 631 if (tag.isCloseTag()) { 632 // We have found a close tag. 633 if (isExtraHtml(tag.getId(), htmlStack)) { 634 // No corresponding open tag was found on the stack. 635 log(tag.getLineNo(), 636 tag.getPosition(), 637 MSG_EXTRA_HTML, 638 tag.getText()); 639 } 640 else { 641 // See if there are any unclosed tags that were opened 642 // after this one. 643 checkUnclosedTags(htmlStack, tag.getId()); 644 } 645 } 646 else { 647 // We only push html tags that are allowed 648 if (isAllowedTag(tag)) { 649 htmlStack.push(tag); 650 } 651 } 652 } 653 654 // Identify any tags left on the stack. 655 // Skip multiples, like <b>...<b> 656 String lastFound = ""; 657 final List<String> typeParameters = CheckUtil.getTypeParameterNames(ast); 658 for (final HtmlTag htmlTag : htmlStack) { 659 if (!isSingleTag(htmlTag) 660 && !htmlTag.getId().equals(lastFound) 661 && !typeParameters.contains(htmlTag.getId())) { 662 log(htmlTag.getLineNo(), htmlTag.getPosition(), 663 MSG_UNCLOSED_HTML, htmlTag.getText()); 664 lastFound = htmlTag.getId(); 665 } 666 } 667 } 668 669 /** 670 * Checks to see if there are any unclosed tags on the stack. The token 671 * represents a html tag that has been closed and has a corresponding open 672 * tag on the stack. Any tags, except single tags, that were opened 673 * (pushed on the stack) after the token are missing a close. 674 * 675 * @param htmlStack the stack of opened HTML tags. 676 * @param token the current HTML tag name that has been closed. 677 */ 678 private void checkUnclosedTags(Deque<HtmlTag> htmlStack, String token) { 679 final Deque<HtmlTag> unclosedTags = new ArrayDeque<>(); 680 HtmlTag lastOpenTag = htmlStack.pop(); 681 while (!token.equalsIgnoreCase(lastOpenTag.getId())) { 682 // Find unclosed elements. Put them on a stack so the 683 // output order won't be back-to-front. 684 if (isSingleTag(lastOpenTag)) { 685 lastOpenTag = htmlStack.pop(); 686 } 687 else { 688 unclosedTags.push(lastOpenTag); 689 lastOpenTag = htmlStack.pop(); 690 } 691 } 692 693 // Output the unterminated tags, if any 694 // Skip multiples, like <b>..<b> 695 String lastFound = ""; 696 for (final HtmlTag htag : unclosedTags) { 697 lastOpenTag = htag; 698 if (lastOpenTag.getId().equals(lastFound)) { 699 continue; 700 } 701 lastFound = lastOpenTag.getId(); 702 log(lastOpenTag.getLineNo(), 703 lastOpenTag.getPosition(), 704 MSG_UNCLOSED_HTML, 705 lastOpenTag.getText()); 706 } 707 } 708 709 /** 710 * Determines if the HtmlTag is one which does not require a close tag. 711 * 712 * @param tag the HtmlTag to check. 713 * @return {@code true} if the HtmlTag is a single tag. 714 */ 715 private static boolean isSingleTag(HtmlTag tag) { 716 // If its a singleton tag (<p>, <br>, etc.), ignore it 717 // Can't simply not put them on the stack, since singletons 718 // like <dt> and <dd> (unhappily) may either be terminated 719 // or not terminated. Both options are legal. 720 return SINGLE_TAGS.contains(tag.getId().toLowerCase(Locale.ENGLISH)); 721 } 722 723 /** 724 * Determines if the HtmlTag is one which is allowed in a javadoc. 725 * 726 * @param tag the HtmlTag to check. 727 * @return {@code true} if the HtmlTag is an allowed html tag. 728 */ 729 private static boolean isAllowedTag(HtmlTag tag) { 730 return ALLOWED_TAGS.contains(tag.getId().toLowerCase(Locale.ENGLISH)); 731 } 732 733 /** 734 * Determines if the given token is an extra HTML tag. This indicates that 735 * a close tag was found that does not have a corresponding open tag. 736 * 737 * @param token an HTML tag id for which a close was found. 738 * @param htmlStack a Stack of previous open HTML tags. 739 * @return {@code false} if a previous open tag was found 740 * for the token. 741 */ 742 private static boolean isExtraHtml(String token, Deque<HtmlTag> htmlStack) { 743 boolean isExtra = true; 744 for (final HtmlTag tag : htmlStack) { 745 // Loop, looking for tags that are closed. 746 // The loop is needed in case there are unclosed 747 // tags on the stack. In that case, the stack would 748 // not be empty, but this tag would still be extra. 749 if (token.equalsIgnoreCase(tag.getId())) { 750 isExtra = false; 751 break; 752 } 753 } 754 755 return isExtra; 756 } 757 758 /** 759 * Setter to specify the visibility scope where Javadoc comments are checked. 760 * 761 * @param scope a scope. 762 */ 763 public void setScope(Scope scope) { 764 this.scope = scope; 765 } 766 767 /** 768 * Setter to specify the visibility scope where Javadoc comments are not checked. 769 * 770 * @param excludeScope a scope. 771 */ 772 public void setExcludeScope(Scope excludeScope) { 773 this.excludeScope = excludeScope; 774 } 775 776 /** 777 * Setter to specify the format for matching the end of a sentence. 778 * 779 * @param pattern a pattern. 780 */ 781 public void setEndOfSentenceFormat(Pattern pattern) { 782 endOfSentenceFormat = pattern; 783 } 784 785 /** 786 * Setter to control whether to check the first sentence for proper end of sentence. 787 * 788 * @param flag {@code true} if the first sentence is to be checked 789 */ 790 public void setCheckFirstSentence(boolean flag) { 791 checkFirstSentence = flag; 792 } 793 794 /** 795 * Setter to control whether to check for incomplete HTML tags. 796 * 797 * @param flag {@code true} if HTML checking is to be performed. 798 */ 799 public void setCheckHtml(boolean flag) { 800 checkHtml = flag; 801 } 802 803 /** 804 * Setter to control whether to check if the Javadoc is missing a describing text. 805 * 806 * @param flag {@code true} if empty Javadoc checking should be done. 807 */ 808 public void setCheckEmptyJavadoc(boolean flag) { 809 checkEmptyJavadoc = flag; 810 } 811 812}