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.Set; 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.AnnotationUtil; 32 import com.puppycrawl.tools.checkstyle.utils.CommonUtil; 33 import com.puppycrawl.tools.checkstyle.utils.ScopeUtil; 34 35 /** 36 * <p> 37 * Checks for missing Javadoc comments for class, enum, interface, and annotation interface 38 * definitions. The scope to verify is specified using the {@code Scope} class and defaults 39 * to {@code Scope.PUBLIC}. To verify another scope, set property scope to one of the 40 * {@code Scope} constants. 41 * </p> 42 * <ul> 43 * <li> 44 * Property {@code excludeScope} - Specify the visibility scope where Javadoc comments are not 45 * checked. 46 * Type is {@code com.puppycrawl.tools.checkstyle.api.Scope}. 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 public}. 53 * </li> 54 * <li> 55 * Property {@code skipAnnotations} - Specify annotations that allow missed 56 * documentation. If annotation is present in target sources in multiple forms of qualified 57 * name, all forms should be listed in this property. 58 * Type is {@code java.lang.String[]}. 59 * Default value is {@code Generated}. 60 * </li> 61 * <li> 62 * Property {@code tokens} - tokens to check 63 * Type is {@code java.lang.String[]}. 64 * Validation type is {@code tokenSet}. 65 * Default value is: 66 * <a href="https://checkstyle.org/apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#INTERFACE_DEF"> 67 * INTERFACE_DEF</a>, 68 * <a href="https://checkstyle.org/apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#CLASS_DEF"> 69 * CLASS_DEF</a>, 70 * <a href="https://checkstyle.org/apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#ENUM_DEF"> 71 * ENUM_DEF</a>, 72 * <a href="https://checkstyle.org/apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#ANNOTATION_DEF"> 73 * ANNOTATION_DEF</a>, 74 * <a href="https://checkstyle.org/apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#RECORD_DEF"> 75 * RECORD_DEF</a>. 76 * </li> 77 * </ul> 78 * <p> 79 * Parent is {@code com.puppycrawl.tools.checkstyle.TreeWalker} 80 * </p> 81 * <p> 82 * Violation Message Keys: 83 * </p> 84 * <ul> 85 * <li> 86 * {@code javadoc.missing} 87 * </li> 88 * </ul> 89 * 90 * @since 8.20 91 */ 92 @StatelessCheck 93 public class MissingJavadocTypeCheck extends AbstractCheck { 94 95 /** 96 * A key is pointing to the warning message text in "messages.properties" 97 * file. 98 */ 99 public static final String MSG_JAVADOC_MISSING = "javadoc.missing"; 100 101 /** Specify the visibility scope where Javadoc comments are checked. */ 102 private Scope scope = Scope.PUBLIC; 103 /** Specify the visibility scope where Javadoc comments are not checked. */ 104 private Scope excludeScope; 105 106 /** 107 * Specify annotations that allow missed documentation. 108 * If annotation is present in target sources in multiple forms of qualified 109 * name, all forms should be listed in this property. 110 */ 111 private Set<String> skipAnnotations = Set.of("Generated"); 112 113 /** 114 * Setter to specify the visibility scope where Javadoc comments are checked. 115 * 116 * @param scope a scope. 117 * @since 8.20 118 */ 119 public void setScope(Scope scope) { 120 this.scope = scope; 121 } 122 123 /** 124 * Setter to specify the visibility scope where Javadoc comments are not checked. 125 * 126 * @param excludeScope a scope. 127 * @since 8.20 128 */ 129 public void setExcludeScope(Scope excludeScope) { 130 this.excludeScope = excludeScope; 131 } 132 133 /** 134 * Setter to specify annotations that allow missed documentation. 135 * If annotation is present in target sources in multiple forms of qualified 136 * name, all forms should be listed in this property. 137 * 138 * @param userAnnotations user's value. 139 * @since 8.20 140 */ 141 public void setSkipAnnotations(String... userAnnotations) { 142 skipAnnotations = Set.of(userAnnotations); 143 } 144 145 @Override 146 public int[] getDefaultTokens() { 147 return getAcceptableTokens(); 148 } 149 150 @Override 151 public int[] getAcceptableTokens() { 152 return new int[] { 153 TokenTypes.INTERFACE_DEF, 154 TokenTypes.CLASS_DEF, 155 TokenTypes.ENUM_DEF, 156 TokenTypes.ANNOTATION_DEF, 157 TokenTypes.RECORD_DEF, 158 }; 159 } 160 161 @Override 162 public int[] getRequiredTokens() { 163 return CommonUtil.EMPTY_INT_ARRAY; 164 } 165 166 // suppress deprecation until https://github.com/checkstyle/checkstyle/issues/11166 167 @SuppressWarnings("deprecation") 168 @Override 169 public void visitToken(DetailAST ast) { 170 if (shouldCheck(ast)) { 171 final FileContents contents = getFileContents(); 172 final int lineNo = ast.getLineNo(); 173 final TextBlock textBlock = contents.getJavadocBefore(lineNo); 174 if (textBlock == null) { 175 log(ast, MSG_JAVADOC_MISSING); 176 } 177 } 178 } 179 180 /** 181 * Whether we should check this node. 182 * 183 * @param ast a given node. 184 * @return whether we should check a given node. 185 */ 186 private boolean shouldCheck(final DetailAST ast) { 187 final Scope surroundingScope = ScopeUtil.getSurroundingScope(ast); 188 189 return surroundingScope.isIn(scope) 190 && (excludeScope == null || !surroundingScope.isIn(excludeScope)) 191 && !AnnotationUtil.containsAnnotation(ast, skipAnnotations); 192 } 193 194 }