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&lt;])|([.?!]$)"}.
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 * &lt;module name="JavadocStyle"/&gt;
162 * </pre>
163 * <p>Example:</p>
164 * <pre>
165 * public class Test {
166 *     &#47;**
167 *      * Some description here. // OK
168 *      *&#47;
169 *     private void methodWithValidCommentStyle() {}
170 *
171 *     &#47;**
172 *      * Some description here // violation, the sentence must end with a proper punctuation
173 *      *&#47;
174 *     private void methodWithInvalidCommentStyle() {}
175 * }
176 * </pre>
177 * <p>
178 * To configure the check for {@code public} scope:
179 * </p>
180 * <pre>
181 * &lt;module name="JavadocStyle"&gt;
182 *   &lt;property name="scope" value="public"/&gt;
183 * &lt;/module&gt;
184 * </pre>
185 * <p>Example:</p>
186 * <pre>
187 * public class Test {
188 *     &#47;**
189 *      * Some description here // violation, the sentence must end with a proper punctuation
190 *      *&#47;
191 *     public void test1() {}
192 *
193 *     &#47;**
194 *      * Some description here // OK
195 *      *&#47;
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 * &lt;module name="JavadocStyle"&gt;
204 *   &lt;property name="scope" value="private"/&gt;
205 *   &lt;property name="excludeScope" value="package"/&gt;
206 * &lt;/module&gt;
207 * </pre>
208 * <p>Example:</p>
209 * <pre>
210 * public class Test {
211 *     &#47;**
212 *      * Some description here // violation, the sentence must end with a proper punctuation
213 *      *&#47;
214 *     private void test1() {}
215 *
216 *     &#47;**
217 *      * Some description here // OK
218 *      *&#47;
219 *     void test2() {}
220 * }
221 * </pre>
222 * <p>
223 * To configure the check to turn off first sentence checking:
224 * </p>
225 * <pre>
226 * &lt;module name="JavadocStyle"&gt;
227 *   &lt;property name="checkFirstSentence" value="false"/&gt;
228 * &lt;/module&gt;
229 * </pre>
230 * <p>Example:</p>
231 * <pre>
232 * public class Test {
233 *     &#47;**
234 *      * Some description here // OK
235 *      * Second line of description // violation, the sentence must end with a proper punctuation
236 *      *&#47;
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 * &lt;module name="JavadocStyle"&gt;
245 * &lt;property name="checkHtml" value="false"/&gt;
246 * &lt;/module&gt;
247 * </pre>
248 * <p>Example:</p>
249 * <pre>
250 * public class Test {
251 *     &#47;**
252 *      * Some description here // violation, the sentence must end with a proper punctuation
253 *      * &lt;p // OK
254 *      *&#47;
255 *     private void test1() {}
256 * }
257 * </pre>
258 * <p>
259 * To configure the check for only class definitions:
260 * </p>
261 * <pre>
262 * &lt;module name="JavadocStyle"&gt;
263 * &lt;property name="tokens" value="CLASS_DEF"/&gt;
264 * &lt;/module&gt;
265 * </pre>
266 * <p>Example:</p>
267 * <pre>
268 * &#47;**
269 *  * Some description here // violation, the sentence must end with a proper punctuation
270 *  *&#47;
271 * public class Test {
272 *     &#47;**
273 *      * Some description here // OK
274 *      *&#47;
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 (&#47** and *&#47) 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}