View Javadoc
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 &#64;Deprecated annotation is used for compilers and development tools.
43   * The &#64;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   * &lt;!-- required till https://bugs.openjdk.org/browse/JDK-8160601 --&gt;
67   * &lt;module name="SuppressionSingleFilter"&gt;
68   *     &lt;property name="checks" value="MissingDeprecatedCheck"/&gt;
69   *     &lt;property name="files" value="package-info\.java"/&gt;
70   * &lt;/module&gt;
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 }