001////////////////////////////////////////////////////////////////////////////////
002// checkstyle: Checks Java source code for adherence to a set of rules.
003// Copyright (C) 2001-2019 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.regex.Pattern;
023
024import com.puppycrawl.tools.checkstyle.StatelessCheck;
025import com.puppycrawl.tools.checkstyle.api.AbstractCheck;
026import com.puppycrawl.tools.checkstyle.api.DetailAST;
027import com.puppycrawl.tools.checkstyle.api.FileContents;
028import com.puppycrawl.tools.checkstyle.api.Scope;
029import com.puppycrawl.tools.checkstyle.api.TextBlock;
030import com.puppycrawl.tools.checkstyle.api.TokenTypes;
031import com.puppycrawl.tools.checkstyle.utils.ScopeUtil;
032
033/**
034 * Checks that a variable has Javadoc comment. Ignores {@code serialVersionUID} fields.
035 *
036 */
037@StatelessCheck
038public class JavadocVariableCheck
039    extends AbstractCheck {
040
041    /**
042     * A key is pointing to the warning message text in "messages.properties"
043     * file.
044     */
045    public static final String MSG_JAVADOC_MISSING = "javadoc.missing";
046
047    /** The scope to check. */
048    private Scope scope = Scope.PRIVATE;
049
050    /** The visibility scope where Javadoc comments shouldn't be checked. **/
051    private Scope excludeScope;
052
053    /** The pattern to ignore variable name. */
054    private Pattern ignoreNamePattern;
055
056    /**
057     * Sets the scope to check.
058     * @param scope a scope.
059     */
060    public void setScope(Scope scope) {
061        this.scope = scope;
062    }
063
064    /**
065     * Set the excludeScope.
066     * @param excludeScope a scope.
067     */
068    public void setExcludeScope(Scope excludeScope) {
069        this.excludeScope = excludeScope;
070    }
071
072    /**
073     * Sets the variable names to ignore in the check.
074     * @param pattern a pattern.
075     */
076    public void setIgnoreNamePattern(Pattern pattern) {
077        ignoreNamePattern = pattern;
078    }
079
080    @Override
081    public int[] getDefaultTokens() {
082        return getAcceptableTokens();
083    }
084
085    @Override
086    public int[] getAcceptableTokens() {
087        return new int[] {
088            TokenTypes.VARIABLE_DEF,
089            TokenTypes.ENUM_CONSTANT_DEF,
090        };
091    }
092
093    /*
094     * Skipping enum values is requested.
095     * Checkstyle's issue #1669: https://github.com/checkstyle/checkstyle/issues/1669
096     */
097    @Override
098    public int[] getRequiredTokens() {
099        return new int[] {
100            TokenTypes.VARIABLE_DEF,
101        };
102    }
103
104    @Override
105    public void visitToken(DetailAST ast) {
106        if (shouldCheck(ast)) {
107            final FileContents contents = getFileContents();
108            final TextBlock textBlock =
109                contents.getJavadocBefore(ast.getLineNo());
110
111            if (textBlock == null) {
112                log(ast, MSG_JAVADOC_MISSING);
113            }
114        }
115    }
116
117    /**
118     * Decides whether the variable name of an AST is in the ignore list.
119     * @param ast the AST to check
120     * @return true if the variable name of ast is in the ignore list.
121     */
122    private boolean isIgnored(DetailAST ast) {
123        final String name = ast.findFirstToken(TokenTypes.IDENT).getText();
124        return ignoreNamePattern != null && ignoreNamePattern.matcher(name).matches()
125            || "serialVersionUID".equals(name);
126    }
127
128    /**
129     * Whether we should check this node.
130     * @param ast a given node.
131     * @return whether we should check a given node.
132     */
133    private boolean shouldCheck(final DetailAST ast) {
134        boolean result = false;
135        if (!ScopeUtil.isInCodeBlock(ast) && !isIgnored(ast)) {
136            Scope customScope = Scope.PUBLIC;
137            if (ast.getType() != TokenTypes.ENUM_CONSTANT_DEF
138                    && !ScopeUtil.isInInterfaceOrAnnotationBlock(ast)) {
139                final DetailAST mods = ast.findFirstToken(TokenTypes.MODIFIERS);
140                customScope = ScopeUtil.getScopeFromMods(mods);
141            }
142
143            final Scope surroundingScope = ScopeUtil.getSurroundingScope(ast);
144            result = customScope.isIn(scope) && surroundingScope.isIn(scope)
145                && (excludeScope == null
146                    || !customScope.isIn(excludeScope)
147                    || !surroundingScope.isIn(excludeScope));
148        }
149        return result;
150    }
151
152}