1 /////////////////////////////////////////////////////////////////////////////////////////////// 2 // checkstyle: Checks Java source code and other text files for adherence to a set of rules. 3 // Copyright (C) 2001-2024 the original author or authors. 4 // 5 // This library is free software; you can redistribute it and/or 6 // modify it under the terms of the GNU Lesser General Public 7 // License as published by the Free Software Foundation; either 8 // version 2.1 of the License, or (at your option) any later version. 9 // 10 // This library is distributed in the hope that it will be useful, 11 // but WITHOUT ANY WARRANTY; without even the implied warranty of 12 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 13 // Lesser General Public License for more details. 14 // 15 // You should have received a copy of the GNU Lesser General Public 16 // License along with this library; if not, write to the Free Software 17 // Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA 18 /////////////////////////////////////////////////////////////////////////////////////////////// 19 20 package com.puppycrawl.tools.checkstyle.checks.javadoc; 21 22 import java.util.regex.Pattern; 23 24 import com.puppycrawl.tools.checkstyle.StatelessCheck; 25 import com.puppycrawl.tools.checkstyle.api.AbstractCheck; 26 import com.puppycrawl.tools.checkstyle.api.DetailAST; 27 import com.puppycrawl.tools.checkstyle.api.FileContents; 28 import com.puppycrawl.tools.checkstyle.api.Scope; 29 import com.puppycrawl.tools.checkstyle.api.TextBlock; 30 import com.puppycrawl.tools.checkstyle.api.TokenTypes; 31 import com.puppycrawl.tools.checkstyle.utils.ScopeUtil; 32 33 /** 34 * <p> 35 * Checks that a variable has a Javadoc comment. Ignores {@code serialVersionUID} fields. 36 * </p> 37 * <ul> 38 * <li> 39 * Property {@code excludeScope} - Specify the visibility scope where Javadoc 40 * comments are not checked. 41 * Type is {@code com.puppycrawl.tools.checkstyle.api.Scope}. 42 * Default value is {@code null}. 43 * </li> 44 * <li> 45 * Property {@code ignoreNamePattern} - Specify the regexp to define variable names to ignore. 46 * Type is {@code java.util.regex.Pattern}. 47 * Default value is {@code null}. 48 * </li> 49 * <li> 50 * Property {@code scope} - Specify the visibility scope where Javadoc comments are checked. 51 * Type is {@code com.puppycrawl.tools.checkstyle.api.Scope}. 52 * Default value is {@code private}. 53 * </li> 54 * <li> 55 * Property {@code tokens} - tokens to check 56 * Type is {@code java.lang.String[]}. 57 * Validation type is {@code tokenSet}. 58 * Default value is: 59 * <a href="https://checkstyle.org/apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#ENUM_CONSTANT_DEF"> 60 * ENUM_CONSTANT_DEF</a>. 61 * </li> 62 * </ul> 63 * <p> 64 * Parent is {@code com.puppycrawl.tools.checkstyle.TreeWalker} 65 * </p> 66 * <p> 67 * Violation Message Keys: 68 * </p> 69 * <ul> 70 * <li> 71 * {@code javadoc.missing} 72 * </li> 73 * </ul> 74 * 75 * @since 3.0 76 */ 77 @StatelessCheck 78 public class JavadocVariableCheck 79 extends AbstractCheck { 80 81 /** 82 * A key is pointing to the warning message text in "messages.properties" 83 * file. 84 */ 85 public static final String MSG_JAVADOC_MISSING = "javadoc.missing"; 86 87 /** Specify the visibility scope where Javadoc comments are checked. */ 88 private Scope scope = Scope.PRIVATE; 89 90 /** Specify the visibility scope where Javadoc comments are not checked. */ 91 private Scope excludeScope; 92 93 /** Specify the regexp to define variable names to ignore. */ 94 private Pattern ignoreNamePattern; 95 96 /** 97 * Setter to specify the visibility scope where Javadoc comments are checked. 98 * 99 * @param scope a scope. 100 * @since 3.0 101 */ 102 public void setScope(Scope scope) { 103 this.scope = scope; 104 } 105 106 /** 107 * Setter to specify the visibility scope where Javadoc comments are not checked. 108 * 109 * @param excludeScope a scope. 110 * @since 3.4 111 */ 112 public void setExcludeScope(Scope excludeScope) { 113 this.excludeScope = excludeScope; 114 } 115 116 /** 117 * Setter to specify the regexp to define variable names to ignore. 118 * 119 * @param pattern a pattern. 120 * @since 5.8 121 */ 122 public void setIgnoreNamePattern(Pattern pattern) { 123 ignoreNamePattern = pattern; 124 } 125 126 @Override 127 public int[] getDefaultTokens() { 128 return getAcceptableTokens(); 129 } 130 131 @Override 132 public int[] getAcceptableTokens() { 133 return new int[] { 134 TokenTypes.VARIABLE_DEF, 135 TokenTypes.ENUM_CONSTANT_DEF, 136 }; 137 } 138 139 /* 140 * Skipping enum values is requested. 141 * Checkstyle's issue #1669: https://github.com/checkstyle/checkstyle/issues/1669 142 */ 143 @Override 144 public int[] getRequiredTokens() { 145 return new int[] { 146 TokenTypes.VARIABLE_DEF, 147 }; 148 } 149 150 // suppress deprecation until https://github.com/checkstyle/checkstyle/issues/11166 151 @SuppressWarnings("deprecation") 152 @Override 153 public void visitToken(DetailAST ast) { 154 if (shouldCheck(ast)) { 155 final FileContents contents = getFileContents(); 156 final TextBlock textBlock = 157 contents.getJavadocBefore(ast.getLineNo()); 158 159 if (textBlock == null) { 160 log(ast, MSG_JAVADOC_MISSING); 161 } 162 } 163 } 164 165 /** 166 * Decides whether the variable name of an AST is in the ignore list. 167 * 168 * @param ast the AST to check 169 * @return true if the variable name of ast is in the ignore list. 170 */ 171 private boolean isIgnored(DetailAST ast) { 172 final String name = ast.findFirstToken(TokenTypes.IDENT).getText(); 173 return ignoreNamePattern != null && ignoreNamePattern.matcher(name).matches() 174 || "serialVersionUID".equals(name); 175 } 176 177 /** 178 * Whether we should check this node. 179 * 180 * @param ast a given node. 181 * @return whether we should check a given node. 182 */ 183 private boolean shouldCheck(final DetailAST ast) { 184 boolean result = false; 185 if (!ScopeUtil.isInCodeBlock(ast) && !isIgnored(ast)) { 186 final Scope customScope = ScopeUtil.getScope(ast); 187 final Scope surroundingScope = ScopeUtil.getSurroundingScope(ast); 188 result = customScope.isIn(scope) && surroundingScope.isIn(scope) 189 && (excludeScope == null 190 || !customScope.isIn(excludeScope) 191 || !surroundingScope.isIn(excludeScope)); 192 } 193 return result; 194 } 195 196 }