001//////////////////////////////////////////////////////////////////////////////// 002// checkstyle: Checks Java source code for adherence to a set of rules. 003// Copyright (C) 2001-2020 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 * <p> 035 * Checks that a variable has a Javadoc comment. Ignores {@code serialVersionUID} fields. 036 * </p> 037 * <ul> 038 * <li> 039 * Property {@code scope} - Specify the visibility scope where Javadoc comments are checked. 040 * Type is {@code com.puppycrawl.tools.checkstyle.api.Scope}. 041 * Default value is {@code private}. 042 * </li> 043 * <li> 044 * Property {@code excludeScope} - Specify the visibility scope where Javadoc 045 * comments are not checked. 046 * Type is {@code com.puppycrawl.tools.checkstyle.api.Scope}. 047 * Default value is {@code null}. 048 * </li> 049 * <li> 050 * Property {@code ignoreNamePattern} - Specify the regexp to define variable names to ignore. 051 * Type is {@code java.util.regex.Pattern}. 052 * Default value is {@code null}. 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 * <p> 064 * To configure the default check: 065 * </p> 066 * <pre> 067 * <module name="JavadocVariable"/> 068 * </pre> 069 * <p> 070 * To configure the check for {@code public} scope: 071 * </p> 072 * <pre> 073 * <module name="JavadocVariable"> 074 * <property name="scope" value="public"/> 075 * </module> 076 * </pre> 077 * <p> 078 * To configure the check for members which are in {@code private}, 079 * but not in {@code protected} scope: 080 * </p> 081 * <pre> 082 * <module name="JavadocVariable"> 083 * <property name="scope" value="private"/> 084 * <property name="excludeScope" value="protected"/> 085 * </module> 086 * </pre> 087 * <p> 088 * To ignore absence of Javadoc comments for variables with names {@code log} or {@code logger}: 089 * </p> 090 * <pre> 091 * <module name="JavadocVariable"> 092 * <property name="ignoreNamePattern" value="log|logger"/> 093 * </module> 094 * </pre> 095 * <p> 096 * Parent is {@code com.puppycrawl.tools.checkstyle.TreeWalker} 097 * </p> 098 * <p> 099 * Violation Message Keys: 100 * </p> 101 * <ul> 102 * <li> 103 * {@code javadoc.missing} 104 * </li> 105 * </ul> 106 * 107 * @since 3.0 108 */ 109@StatelessCheck 110public class JavadocVariableCheck 111 extends AbstractCheck { 112 113 /** 114 * A key is pointing to the warning message text in "messages.properties" 115 * file. 116 */ 117 public static final String MSG_JAVADOC_MISSING = "javadoc.missing"; 118 119 /** Specify the visibility scope where Javadoc comments are checked. */ 120 private Scope scope = Scope.PRIVATE; 121 122 /** Specify the visibility scope where Javadoc comments are not checked. */ 123 private Scope excludeScope; 124 125 /** Specify the regexp to define variable names to ignore. */ 126 private Pattern ignoreNamePattern; 127 128 /** 129 * Setter to specify the visibility scope where Javadoc comments are checked. 130 * 131 * @param scope a scope. 132 */ 133 public void setScope(Scope scope) { 134 this.scope = scope; 135 } 136 137 /** 138 * Setter to specify the visibility scope where Javadoc comments are not checked. 139 * 140 * @param excludeScope a scope. 141 */ 142 public void setExcludeScope(Scope excludeScope) { 143 this.excludeScope = excludeScope; 144 } 145 146 /** 147 * Setter to specify the regexp to define variable names to ignore. 148 * 149 * @param pattern a pattern. 150 */ 151 public void setIgnoreNamePattern(Pattern pattern) { 152 ignoreNamePattern = pattern; 153 } 154 155 @Override 156 public int[] getDefaultTokens() { 157 return getAcceptableTokens(); 158 } 159 160 @Override 161 public int[] getAcceptableTokens() { 162 return new int[] { 163 TokenTypes.VARIABLE_DEF, 164 TokenTypes.ENUM_CONSTANT_DEF, 165 }; 166 } 167 168 /* 169 * Skipping enum values is requested. 170 * Checkstyle's issue #1669: https://github.com/checkstyle/checkstyle/issues/1669 171 */ 172 @Override 173 public int[] getRequiredTokens() { 174 return new int[] { 175 TokenTypes.VARIABLE_DEF, 176 }; 177 } 178 179 @Override 180 public void visitToken(DetailAST ast) { 181 if (shouldCheck(ast)) { 182 final FileContents contents = getFileContents(); 183 final TextBlock textBlock = 184 contents.getJavadocBefore(ast.getLineNo()); 185 186 if (textBlock == null) { 187 log(ast, MSG_JAVADOC_MISSING); 188 } 189 } 190 } 191 192 /** 193 * Decides whether the variable name of an AST is in the ignore list. 194 * 195 * @param ast the AST to check 196 * @return true if the variable name of ast is in the ignore list. 197 */ 198 private boolean isIgnored(DetailAST ast) { 199 final String name = ast.findFirstToken(TokenTypes.IDENT).getText(); 200 return ignoreNamePattern != null && ignoreNamePattern.matcher(name).matches() 201 || "serialVersionUID".equals(name); 202 } 203 204 /** 205 * Whether we should check this node. 206 * 207 * @param ast a given node. 208 * @return whether we should check a given node. 209 */ 210 private boolean shouldCheck(final DetailAST ast) { 211 boolean result = false; 212 if (!ScopeUtil.isInCodeBlock(ast) && !isIgnored(ast)) { 213 Scope customScope = Scope.PUBLIC; 214 if (ast.getType() != TokenTypes.ENUM_CONSTANT_DEF 215 && !ScopeUtil.isInInterfaceOrAnnotationBlock(ast)) { 216 final DetailAST mods = ast.findFirstToken(TokenTypes.MODIFIERS); 217 customScope = ScopeUtil.getScopeFromMods(mods); 218 } 219 220 final Scope surroundingScope = ScopeUtil.getSurroundingScope(ast); 221 result = customScope.isIn(scope) && surroundingScope.isIn(scope) 222 && (excludeScope == null 223 || !customScope.isIn(excludeScope) 224 || !surroundingScope.isIn(excludeScope)); 225 } 226 return result; 227 } 228 229}