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.regex.Matcher;
23 import java.util.regex.Pattern;
24
25 import com.puppycrawl.tools.checkstyle.StatelessCheck;
26 import com.puppycrawl.tools.checkstyle.api.AbstractCheck;
27 import com.puppycrawl.tools.checkstyle.api.DetailAST;
28 import com.puppycrawl.tools.checkstyle.api.FileContents;
29 import com.puppycrawl.tools.checkstyle.api.SeverityLevel;
30 import com.puppycrawl.tools.checkstyle.api.TextBlock;
31 import com.puppycrawl.tools.checkstyle.api.TokenTypes;
32 import com.puppycrawl.tools.checkstyle.utils.CommonUtil;
33
34 /**
35 * <p>
36 * Requires user defined Javadoc tag to be present in Javadoc comment with defined format.
37 * To define the format for a tag, set property tagFormat to a regular expression.
38 * Property tagSeverity is used for severity of events when the tag exists.
39 * </p>
40 * <ul>
41 * <li>
42 * Property {@code tag} - Specify the name of tag.
43 * Type is {@code java.lang.String}.
44 * Default value is {@code null}.
45 * </li>
46 * <li>
47 * Property {@code tagFormat} - Specify the regexp to match tag content.
48 * Type is {@code java.util.regex.Pattern}.
49 * Default value is {@code null}.
50 * </li>
51 * <li>
52 * Property {@code tagSeverity} - Specify the severity level when tag is found and printed.
53 * Type is {@code com.puppycrawl.tools.checkstyle.api.SeverityLevel}.
54 * Default value is {@code info}.
55 * </li>
56 * <li>
57 * Property {@code tokens} - tokens to check
58 * Type is {@code java.lang.String[]}.
59 * Validation type is {@code tokenSet}.
60 * Default value is:
61 * <a href="https://checkstyle.org/apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#INTERFACE_DEF">
62 * INTERFACE_DEF</a>,
63 * <a href="https://checkstyle.org/apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#CLASS_DEF">
64 * CLASS_DEF</a>,
65 * <a href="https://checkstyle.org/apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#ENUM_DEF">
66 * ENUM_DEF</a>,
67 * <a href="https://checkstyle.org/apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#ANNOTATION_DEF">
68 * ANNOTATION_DEF</a>,
69 * <a href="https://checkstyle.org/apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#RECORD_DEF">
70 * RECORD_DEF</a>.
71 * </li>
72 * </ul>
73 * <p>
74 * Parent is {@code com.puppycrawl.tools.checkstyle.TreeWalker}
75 * </p>
76 * <p>
77 * Violation Message Keys:
78 * </p>
79 * <ul>
80 * <li>
81 * {@code javadoc.writeTag}
82 * </li>
83 * <li>
84 * {@code type.missingTag}
85 * </li>
86 * <li>
87 * {@code type.tagFormat}
88 * </li>
89 * </ul>
90 *
91 * @since 4.2
92 */
93 @StatelessCheck
94 public class WriteTagCheck
95 extends AbstractCheck {
96
97 /**
98 * A key is pointing to the warning message text in "messages.properties"
99 * file.
100 */
101 public static final String MSG_MISSING_TAG = "type.missingTag";
102
103 /**
104 * A key is pointing to the warning message text in "messages.properties"
105 * file.
106 */
107 public static final String MSG_WRITE_TAG = "javadoc.writeTag";
108
109 /**
110 * A key is pointing to the warning message text in "messages.properties"
111 * file.
112 */
113 public static final String MSG_TAG_FORMAT = "type.tagFormat";
114
115 /** Compiled regexp to match tag. */
116 private Pattern tagRegExp;
117 /** Specify the regexp to match tag content. */
118 private Pattern tagFormat;
119
120 /** Specify the name of tag. */
121 private String tag;
122 /** Specify the severity level when tag is found and printed. */
123 private SeverityLevel tagSeverity = SeverityLevel.INFO;
124
125 /**
126 * Setter to specify the name of tag.
127 *
128 * @param tag tag to check
129 * @since 4.2
130 */
131 public void setTag(String tag) {
132 this.tag = tag;
133 tagRegExp = CommonUtil.createPattern(tag + "\\s*(.*$)");
134 }
135
136 /**
137 * Setter to specify the regexp to match tag content.
138 *
139 * @param pattern a {@code String} value
140 * @since 4.2
141 */
142 public void setTagFormat(Pattern pattern) {
143 tagFormat = pattern;
144 }
145
146 /**
147 * Setter to specify the severity level when tag is found and printed.
148 *
149 * @param severity The new severity level
150 * @see SeverityLevel
151 * @since 4.2
152 */
153 public final void setTagSeverity(SeverityLevel severity) {
154 tagSeverity = severity;
155 }
156
157 @Override
158 public int[] getDefaultTokens() {
159 return new int[] {
160 TokenTypes.INTERFACE_DEF,
161 TokenTypes.CLASS_DEF,
162 TokenTypes.ENUM_DEF,
163 TokenTypes.ANNOTATION_DEF,
164 TokenTypes.RECORD_DEF,
165 };
166 }
167
168 @Override
169 public int[] getAcceptableTokens() {
170 return new int[] {
171 TokenTypes.INTERFACE_DEF,
172 TokenTypes.CLASS_DEF,
173 TokenTypes.ENUM_DEF,
174 TokenTypes.ANNOTATION_DEF,
175 TokenTypes.METHOD_DEF,
176 TokenTypes.CTOR_DEF,
177 TokenTypes.ENUM_CONSTANT_DEF,
178 TokenTypes.ANNOTATION_FIELD_DEF,
179 TokenTypes.RECORD_DEF,
180 TokenTypes.COMPACT_CTOR_DEF,
181 };
182 }
183
184 @Override
185 public int[] getRequiredTokens() {
186 return CommonUtil.EMPTY_INT_ARRAY;
187 }
188
189 // suppress deprecation until https://github.com/checkstyle/checkstyle/issues/11166
190 @SuppressWarnings("deprecation")
191 @Override
192 public void visitToken(DetailAST ast) {
193 final FileContents contents = getFileContents();
194 final int lineNo = ast.getLineNo();
195 final TextBlock cmt =
196 contents.getJavadocBefore(lineNo);
197 if (cmt == null) {
198 log(lineNo, MSG_MISSING_TAG, tag);
199 }
200 else {
201 checkTag(lineNo, cmt.getText());
202 }
203 }
204
205 /**
206 * Verifies that a type definition has a required tag.
207 *
208 * @param lineNo the line number for the type definition.
209 * @param comment the Javadoc comment for the type definition.
210 */
211 private void checkTag(int lineNo, String... comment) {
212 if (tagRegExp != null) {
213 boolean hasTag = false;
214 for (int i = 0; i < comment.length; i++) {
215 final String commentValue = comment[i];
216 final Matcher matcher = tagRegExp.matcher(commentValue);
217 if (matcher.find()) {
218 hasTag = true;
219 final int contentStart = matcher.start(1);
220 final String content = commentValue.substring(contentStart);
221 if (tagFormat == null || tagFormat.matcher(content).find()) {
222 logTag(lineNo + i - comment.length, tag, content);
223 }
224 else {
225 log(lineNo + i - comment.length, MSG_TAG_FORMAT, tag, tagFormat.pattern());
226 }
227 }
228 }
229 if (!hasTag) {
230 log(lineNo, MSG_MISSING_TAG, tag);
231 }
232 }
233 }
234
235 /**
236 * Log a message.
237 *
238 * @param line the line number where the violation was found
239 * @param tagName the javadoc tag to be logged
240 * @param tagValue the contents of the tag
241 *
242 * @see java.text.MessageFormat
243 */
244 private void logTag(int line, String tagName, String tagValue) {
245 final String originalSeverity = getSeverity();
246 setSeverity(tagSeverity.getName());
247
248 log(line, MSG_WRITE_TAG, tagName, tagValue);
249
250 setSeverity(originalSeverity);
251 }
252
253 }