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}