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.Set; 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.AnnotationUtil; 032import com.puppycrawl.tools.checkstyle.utils.CommonUtil; 033import com.puppycrawl.tools.checkstyle.utils.ScopeUtil; 034 035/** 036 * <p> 037 * Checks for missing Javadoc comments for class, enum, interface, and annotation interface 038 * definitions. The scope to verify is specified using the {@code Scope} class and defaults 039 * to {@code Scope.PUBLIC}. To verify another scope, set property scope to one of the 040 * {@code Scope} constants. 041 * </p> 042 * <ul> 043 * <li> 044 * Property {@code excludeScope} - Specify the visibility scope where Javadoc comments are not 045 * checked. 046 * Type is {@code com.puppycrawl.tools.checkstyle.api.Scope}. 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 public}. 053 * </li> 054 * <li> 055 * Property {@code skipAnnotations} - Specify annotations that allow missed 056 * documentation. If annotation is present in target sources in multiple forms of qualified 057 * name, all forms should be listed in this property. 058 * Type is {@code java.lang.String[]}. 059 * Default value is {@code Generated}. 060 * </li> 061 * <li> 062 * Property {@code tokens} - tokens to check 063 * Type is {@code java.lang.String[]}. 064 * Validation type is {@code tokenSet}. 065 * Default value is: 066 * <a href="https://checkstyle.org/apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#INTERFACE_DEF"> 067 * INTERFACE_DEF</a>, 068 * <a href="https://checkstyle.org/apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#CLASS_DEF"> 069 * CLASS_DEF</a>, 070 * <a href="https://checkstyle.org/apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#ENUM_DEF"> 071 * ENUM_DEF</a>, 072 * <a href="https://checkstyle.org/apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#ANNOTATION_DEF"> 073 * ANNOTATION_DEF</a>, 074 * <a href="https://checkstyle.org/apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#RECORD_DEF"> 075 * RECORD_DEF</a>. 076 * </li> 077 * </ul> 078 * <p> 079 * Parent is {@code com.puppycrawl.tools.checkstyle.TreeWalker} 080 * </p> 081 * <p> 082 * Violation Message Keys: 083 * </p> 084 * <ul> 085 * <li> 086 * {@code javadoc.missing} 087 * </li> 088 * </ul> 089 * 090 * @since 8.20 091 */ 092@StatelessCheck 093public class MissingJavadocTypeCheck extends AbstractCheck { 094 095 /** 096 * A key is pointing to the warning message text in "messages.properties" 097 * file. 098 */ 099 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}