View Javadoc
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 }