1 /////////////////////////////////////////////////////////////////////////////////////////////// 2 // checkstyle: Checks Java source code and other text files for adherence to a set of rules. 3 // Copyright (C) 2001-2025 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.annotation; 21 22 import java.util.BitSet; 23 24 import com.puppycrawl.tools.checkstyle.StatelessCheck; 25 import com.puppycrawl.tools.checkstyle.api.DetailAST; 26 import com.puppycrawl.tools.checkstyle.api.DetailNode; 27 import com.puppycrawl.tools.checkstyle.api.JavadocTokenTypes; 28 import com.puppycrawl.tools.checkstyle.api.TokenTypes; 29 import com.puppycrawl.tools.checkstyle.checks.javadoc.AbstractJavadocCheck; 30 import com.puppycrawl.tools.checkstyle.checks.javadoc.JavadocTagInfo; 31 import com.puppycrawl.tools.checkstyle.utils.AnnotationUtil; 32 import com.puppycrawl.tools.checkstyle.utils.TokenUtil; 33 34 /** 35 * <div> 36 * Verifies that the annotation {@code @Deprecated} and the Javadoc tag 37 * {@code @deprecated} are both present when either of them is present. 38 * </div> 39 * 40 * <p> 41 * Both ways of flagging deprecation serve their own purpose. 42 * The @Deprecated annotation is used for compilers and development tools. 43 * The @deprecated javadoc tag is used to document why something is deprecated 44 * and what, if any, alternatives exist. 45 * </p> 46 * 47 * <p> 48 * In order to properly mark something as deprecated both forms of 49 * deprecation should be present. 50 * </p> 51 * 52 * <p> 53 * Package deprecation is an exception to the rule of always using the 54 * javadoc tag and annotation to deprecate. It is not clear if the javadoc 55 * tool will support it or not as newer versions keep flip-flopping on if 56 * it is supported or will cause an error. See 57 * <a href="https://bugs.openjdk.org/browse/JDK-8160601">JDK-8160601</a>. 58 * The deprecated javadoc tag is currently the only way to say why the package 59 * is deprecated and what to use instead. Until this is resolved, if you don't 60 * want to print violations on package-info, you can use a 61 * <a href="https://checkstyle.org/filters/index.html">filter</a> to ignore 62 * these files until the javadoc tool faithfully supports it. An example config 63 * using SuppressionSingleFilter is: 64 * </p> 65 * <pre> 66 * <!-- required till https://bugs.openjdk.org/browse/JDK-8160601 --> 67 * <module name="SuppressionSingleFilter"> 68 * <property name="checks" value="MissingDeprecatedCheck"/> 69 * <property name="files" value="package-info\.java"/> 70 * </module> 71 * </pre> 72 * <ul> 73 * <li> 74 * Property {@code violateExecutionOnNonTightHtml} - Control when to 75 * print violations if the Javadoc being examined by this check violates the 76 * tight html rules defined at 77 * <a href="https://checkstyle.org/writingjavadocchecks.html#Tight-HTML_rules"> 78 * Tight-HTML Rules</a>. 79 * Type is {@code boolean}. 80 * Default value is {@code false}. 81 * Since version 8.24 82 * </li> 83 * </ul> 84 * 85 * <p> 86 * Parent is {@code com.puppycrawl.tools.checkstyle.TreeWalker} 87 * </p> 88 * 89 * <p> 90 * Violation Message Keys: 91 * </p> 92 * <ul> 93 * <li> 94 * {@code annotation.missing.deprecated} 95 * </li> 96 * <li> 97 * {@code javadoc.duplicateTag} 98 * </li> 99 * <li> 100 * {@code javadoc.missed.html.close} 101 * </li> 102 * <li> 103 * {@code javadoc.parse.rule.error} 104 * </li> 105 * <li> 106 * {@code javadoc.unclosedHtml} 107 * </li> 108 * <li> 109 * {@code javadoc.wrong.singleton.html.tag} 110 * </li> 111 * </ul> 112 * 113 * @since 5.0 114 */ 115 @StatelessCheck 116 public final class MissingDeprecatedCheck extends AbstractJavadocCheck { 117 118 /** 119 * A key is pointing to the warning message text in "messages.properties" 120 * file. 121 */ 122 public static final String MSG_KEY_ANNOTATION_MISSING_DEPRECATED = 123 "annotation.missing.deprecated"; 124 125 /** 126 * A key is pointing to the warning message text in "messages.properties" 127 * file. 128 */ 129 public static final String MSG_KEY_JAVADOC_DUPLICATE_TAG = 130 "javadoc.duplicateTag"; 131 132 /** {@link Deprecated Deprecated} annotation name. */ 133 private static final String DEPRECATED = "Deprecated"; 134 135 /** Fully-qualified {@link Deprecated Deprecated} annotation name. */ 136 private static final String FQ_DEPRECATED = "java.lang." + DEPRECATED; 137 138 /** Token types to find parent of. */ 139 private static final BitSet TYPES_HASH_SET = TokenUtil.asBitSet( 140 TokenTypes.TYPE, TokenTypes.MODIFIERS, TokenTypes.ANNOTATION, 141 TokenTypes.ANNOTATIONS, TokenTypes.ARRAY_DECLARATOR, 142 TokenTypes.TYPE_PARAMETERS, TokenTypes.DOT); 143 144 @Override 145 public int[] getDefaultJavadocTokens() { 146 return getRequiredJavadocTokens(); 147 } 148 149 @Override 150 public int[] getRequiredJavadocTokens() { 151 return new int[] { 152 JavadocTokenTypes.JAVADOC, 153 }; 154 } 155 156 @Override 157 public void visitJavadocToken(DetailNode ast) { 158 final DetailAST parentAst = getParent(getBlockCommentAst()); 159 160 final boolean containsAnnotation = 161 AnnotationUtil.containsAnnotation(parentAst, DEPRECATED) 162 || AnnotationUtil.containsAnnotation(parentAst, FQ_DEPRECATED); 163 164 final boolean containsJavadocTag = containsDeprecatedTag(ast); 165 166 if (containsAnnotation ^ containsJavadocTag) { 167 log(parentAst.getLineNo(), MSG_KEY_ANNOTATION_MISSING_DEPRECATED); 168 } 169 } 170 171 /** 172 * Checks to see if the javadoc contains a deprecated tag. 173 * 174 * @param javadoc the javadoc of the AST 175 * @return true if contains the tag 176 */ 177 private boolean containsDeprecatedTag(DetailNode javadoc) { 178 boolean found = false; 179 for (DetailNode child : javadoc.getChildren()) { 180 if (child.getType() == JavadocTokenTypes.JAVADOC_TAG 181 && child.getChildren()[0].getType() == JavadocTokenTypes.DEPRECATED_LITERAL) { 182 if (found) { 183 log(child.getLineNumber(), MSG_KEY_JAVADOC_DUPLICATE_TAG, 184 JavadocTagInfo.DEPRECATED.getText()); 185 } 186 found = true; 187 } 188 } 189 return found; 190 } 191 192 /** 193 * Returns the parent node of the comment. 194 * 195 * @param commentBlock child node. 196 * @return parent node. 197 */ 198 private static DetailAST getParent(DetailAST commentBlock) { 199 DetailAST result = commentBlock.getParent(); 200 201 if (TokenUtil.isRootNode(result)) { 202 result = commentBlock.getNextSibling(); 203 } 204 205 while (true) { 206 final int type = result.getType(); 207 if (TYPES_HASH_SET.get(type)) { 208 result = result.getParent(); 209 } 210 else if (type == TokenTypes.SINGLE_LINE_COMMENT) { 211 result = result.getNextSibling(); 212 } 213 else { 214 break; 215 } 216 } 217 218 return result; 219 } 220 221 }