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