001//////////////////////////////////////////////////////////////////////////////// 002// checkstyle: Checks Java source code for adherence to a set of rules. 003// Copyright (C) 2001-2020 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.annotation; 021 022import java.util.Arrays; 023import java.util.HashSet; 024import java.util.Set; 025 026import com.puppycrawl.tools.checkstyle.StatelessCheck; 027import com.puppycrawl.tools.checkstyle.api.DetailAST; 028import com.puppycrawl.tools.checkstyle.api.DetailNode; 029import com.puppycrawl.tools.checkstyle.api.JavadocTokenTypes; 030import com.puppycrawl.tools.checkstyle.api.TokenTypes; 031import com.puppycrawl.tools.checkstyle.checks.javadoc.AbstractJavadocCheck; 032import com.puppycrawl.tools.checkstyle.checks.javadoc.JavadocTagInfo; 033import com.puppycrawl.tools.checkstyle.utils.AnnotationUtil; 034 035/** 036 * <p> 037 * Verifies that the annotation {@code @Deprecated} and the Javadoc tag 038 * {@code @deprecated} are both present when either of them is present. 039 * </p> 040 * <p> 041 * Both ways of flagging deprecation serve their own purpose. 042 * The @Deprecated annotation is used for compilers and development tools. 043 * The @deprecated javadoc tag is used to document why something is deprecated 044 * and what, if any, alternatives exist. 045 * </p> 046 * <p> 047 * In order to properly mark something as deprecated both forms of 048 * deprecation should be present. 049 * </p> 050 * <p> 051 * Package deprecation is a exception to the rule of always using the 052 * javadoc tag and annotation to deprecate. It is not clear if the javadoc 053 * tool will support it or not as newer versions keep flip flopping on if 054 * it is supported or will cause an error. See 055 * <a href="https://bugs.openjdk.java.net/browse/JDK-8160601">JDK-8160601</a>. 056 * The deprecated javadoc tag is currently the only way to say why the package 057 * is deprecated and what to use instead. Until this is resolved, if you don't 058 * want to print violations on package-info, you can use a 059 * <a href="https://checkstyle.org/config_filters.html">filter</a> to ignore 060 * these files until the javadoc tool faithfully supports it. An example config 061 * using SuppressionSingleFilter is: 062 * </p> 063 * <pre> 064 * <!-- required till https://bugs.openjdk.java.net/browse/JDK-8160601 --> 065 * <module name="SuppressionSingleFilter"> 066 * <property name="checks" value="MissingDeprecatedCheck"/> 067 * <property name="files" value="package-info\.java"/> 068 * </module> 069 * </pre> 070 * <ul> 071 * <li> 072 * Property {@code violateExecutionOnNonTightHtml} - Control when to 073 * print violations if the Javadoc being examined by this check violates the 074 * tight html rules defined at 075 * <a href="https://checkstyle.org/writingjavadocchecks.html#Tight-HTML_rules"> 076 * Tight-HTML Rules</a>. 077 * Default value is {@code false}. 078 * </li> 079 * </ul> 080 * <p> 081 * To configure the check: 082 * </p> 083 * <pre> 084 * <module name="MissingDeprecated"/> 085 * </pre> 086 * <p> 087 * Examples of validating source code: 088 * </p> 089 * <pre> 090 * @Deprecated 091 * public static final int MY_CONST = 123456; // no violation 092 * 093 * /** This javadoc is missing deprecated tag. */ 094 * @Deprecated 095 * public static final int COUNTER = 10; // violation 096 * </pre> 097 * 098 * @since 5.0 099 */ 100@StatelessCheck 101public final class MissingDeprecatedCheck extends AbstractJavadocCheck { 102 103 /** 104 * A key is pointing to the warning message text in "messages.properties" 105 * file. 106 */ 107 public static final String MSG_KEY_ANNOTATION_MISSING_DEPRECATED = 108 "annotation.missing.deprecated"; 109 110 /** 111 * A key is pointing to the warning message text in "messages.properties" 112 * file. 113 */ 114 public static final String MSG_KEY_JAVADOC_DUPLICATE_TAG = 115 "javadoc.duplicateTag"; 116 117 /** {@link Deprecated Deprecated} annotation name. */ 118 private static final String DEPRECATED = "Deprecated"; 119 120 /** Fully-qualified {@link Deprecated Deprecated} annotation name. */ 121 private static final String FQ_DEPRECATED = "java.lang." + DEPRECATED; 122 123 /** List of token types to find parent of. */ 124 private static final Set<Integer> TYPES_HASH_SET = new HashSet<>(Arrays.asList( 125 TokenTypes.TYPE, TokenTypes.MODIFIERS, TokenTypes.ANNOTATION, 126 TokenTypes.ANNOTATIONS, TokenTypes.ARRAY_DECLARATOR, 127 TokenTypes.TYPE_PARAMETERS, TokenTypes.DOT)); 128 129 @Override 130 public int[] getDefaultJavadocTokens() { 131 return getRequiredJavadocTokens(); 132 } 133 134 @Override 135 public int[] getRequiredJavadocTokens() { 136 return new int[] { 137 JavadocTokenTypes.JAVADOC, 138 }; 139 } 140 141 @Override 142 public void visitJavadocToken(DetailNode ast) { 143 final DetailAST parentAst = getParent(getBlockCommentAst()); 144 145 final boolean containsAnnotation = 146 AnnotationUtil.containsAnnotation(parentAst, DEPRECATED) 147 || AnnotationUtil.containsAnnotation(parentAst, FQ_DEPRECATED); 148 149 final boolean containsJavadocTag = containsDeprecatedTag(ast); 150 151 if (containsAnnotation ^ containsJavadocTag) { 152 log(parentAst.getLineNo(), MSG_KEY_ANNOTATION_MISSING_DEPRECATED); 153 } 154 } 155 156 /** 157 * Checks to see if the javadoc contains a deprecated tag. 158 * 159 * @param javadoc the javadoc of the AST 160 * @return true if contains the tag 161 */ 162 private boolean containsDeprecatedTag(DetailNode javadoc) { 163 boolean found = false; 164 for (DetailNode child : javadoc.getChildren()) { 165 if (child.getType() == JavadocTokenTypes.JAVADOC_TAG 166 && child.getChildren()[0].getType() == JavadocTokenTypes.DEPRECATED_LITERAL) { 167 if (found) { 168 log(child.getLineNumber(), MSG_KEY_JAVADOC_DUPLICATE_TAG, 169 JavadocTagInfo.DEPRECATED.getText()); 170 } 171 found = true; 172 } 173 } 174 return found; 175 } 176 177 /** 178 * Returns the parent node of the comment. 179 * 180 * @param commentBlock child node. 181 * @return parent node. 182 */ 183 private static DetailAST getParent(DetailAST commentBlock) { 184 DetailAST result = commentBlock.getParent(); 185 186 if (result == null) { 187 result = commentBlock.getNextSibling(); 188 } 189 190 while (true) { 191 final int type = result.getType(); 192 if (TYPES_HASH_SET.contains(type)) { 193 result = result.getParent(); 194 } 195 else if (type == TokenTypes.SINGLE_LINE_COMMENT) { 196 result = result.getNextSibling(); 197 } 198 else { 199 break; 200 } 201 } 202 203 return result; 204 } 205 206}