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.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 * <div>
035 * Checks that a variable has a Javadoc comment. Ignores {@code serialVersionUID} fields.
036 * </div>
037 * <ul>
038 * <li>
039 * Property {@code excludeScope} - Specify the visibility scope where Javadoc
040 * comments are not checked.
041 * Type is {@code com.puppycrawl.tools.checkstyle.api.Scope}.
042 * Default value is {@code null}.
043 * </li>
044 * <li>
045 * Property {@code ignoreNamePattern} - Specify the regexp to define variable names to ignore.
046 * Type is {@code java.util.regex.Pattern}.
047 * Default value is {@code null}.
048 * </li>
049 * <li>
050 * Property {@code scope} - Specify the visibility scope where Javadoc comments are checked.
051 * Type is {@code com.puppycrawl.tools.checkstyle.api.Scope}.
052 * Default value is {@code private}.
053 * </li>
054 * <li>
055 * Property {@code tokens} - tokens to check
056 * Type is {@code java.lang.String[]}.
057 * Validation type is {@code tokenSet}.
058 * Default value is:
059 * <a href="https://checkstyle.org/apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#ENUM_CONSTANT_DEF">
060 * ENUM_CONSTANT_DEF</a>.
061 * </li>
062 * </ul>
063 *
064 * <p>
065 * Parent is {@code com.puppycrawl.tools.checkstyle.TreeWalker}
066 * </p>
067 *
068 * <p>
069 * Violation Message Keys:
070 * </p>
071 * <ul>
072 * <li>
073 * {@code javadoc.missing}
074 * </li>
075 * </ul>
076 *
077 * @since 3.0
078 */
079@StatelessCheck
080public class JavadocVariableCheck
081    extends AbstractCheck {
082
083    /**
084     * A key is pointing to the warning message text in "messages.properties"
085     * file.
086     */
087    public static final String MSG_JAVADOC_MISSING = "javadoc.missing";
088
089    /** Specify the visibility scope where Javadoc comments are checked. */
090    private Scope scope = Scope.PRIVATE;
091
092    /** Specify the visibility scope where Javadoc comments are not checked. */
093    private Scope excludeScope;
094
095    /** Specify the regexp to define variable names to ignore. */
096    private Pattern ignoreNamePattern;
097
098    /**
099     * Setter to specify the visibility scope where Javadoc comments are checked.
100     *
101     * @param scope a scope.
102     * @since 3.0
103     */
104    public void setScope(Scope scope) {
105        this.scope = scope;
106    }
107
108    /**
109     * Setter to specify the visibility scope where Javadoc comments are not checked.
110     *
111     * @param excludeScope a scope.
112     * @since 3.4
113     */
114    public void setExcludeScope(Scope excludeScope) {
115        this.excludeScope = excludeScope;
116    }
117
118    /**
119     * Setter to specify the regexp to define variable names to ignore.
120     *
121     * @param pattern a pattern.
122     * @since 5.8
123     */
124    public void setIgnoreNamePattern(Pattern pattern) {
125        ignoreNamePattern = pattern;
126    }
127
128    @Override
129    public int[] getDefaultTokens() {
130        return getAcceptableTokens();
131    }
132
133    @Override
134    public int[] getAcceptableTokens() {
135        return new int[] {
136            TokenTypes.VARIABLE_DEF,
137            TokenTypes.ENUM_CONSTANT_DEF,
138        };
139    }
140
141    /*
142     * Skipping enum values is requested.
143     * Checkstyle's issue #1669: https://github.com/checkstyle/checkstyle/issues/1669
144     */
145    @Override
146    public int[] getRequiredTokens() {
147        return new int[] {
148            TokenTypes.VARIABLE_DEF,
149        };
150    }
151
152    // suppress deprecation until https://github.com/checkstyle/checkstyle/issues/11166
153    @SuppressWarnings("deprecation")
154    @Override
155    public void visitToken(DetailAST ast) {
156        if (shouldCheck(ast)) {
157            final FileContents contents = getFileContents();
158            final TextBlock textBlock =
159                contents.getJavadocBefore(ast.getLineNo());
160
161            if (textBlock == null) {
162                log(ast, MSG_JAVADOC_MISSING);
163            }
164        }
165    }
166
167    /**
168     * Decides whether the variable name of an AST is in the ignore list.
169     *
170     * @param ast the AST to check
171     * @return true if the variable name of ast is in the ignore list.
172     */
173    private boolean isIgnored(DetailAST ast) {
174        final String name = ast.findFirstToken(TokenTypes.IDENT).getText();
175        return ignoreNamePattern != null && ignoreNamePattern.matcher(name).matches()
176            || "serialVersionUID".equals(name);
177    }
178
179    /**
180     * Whether we should check this node.
181     *
182     * @param ast a given node.
183     * @return whether we should check a given node.
184     */
185    private boolean shouldCheck(final DetailAST ast) {
186        boolean result = false;
187        if (!ScopeUtil.isInCodeBlock(ast) && !isIgnored(ast)) {
188            final Scope customScope = ScopeUtil.getScope(ast);
189            final Scope surroundingScope = ScopeUtil.getSurroundingScope(ast);
190            result = customScope.isIn(scope) && surroundingScope.isIn(scope)
191                && (excludeScope == null
192                    || !customScope.isIn(excludeScope)
193                    || !surroundingScope.isIn(excludeScope));
194        }
195        return result;
196    }
197
198}