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 * &#47;** {&#64;inheritDoc} *&#47;
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}