1 ///////////////////////////////////////////////////////////////////////////////////////////////
2 // checkstyle: Checks Java source code and other text files for adherence to a set of rules.
3 // Copyright (C) 2001-2026 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;
21
22 import java.util.Set;
23
24 import org.antlr.v4.runtime.BaseErrorListener;
25 import org.antlr.v4.runtime.CharStreams;
26 import org.antlr.v4.runtime.CommonTokenStream;
27 import org.antlr.v4.runtime.RecognitionException;
28 import org.antlr.v4.runtime.Recognizer;
29 import org.antlr.v4.runtime.atn.PredictionMode;
30 import org.antlr.v4.runtime.misc.ParseCancellationException;
31
32 import com.puppycrawl.tools.checkstyle.api.DetailAST;
33 import com.puppycrawl.tools.checkstyle.api.DetailNode;
34 import com.puppycrawl.tools.checkstyle.grammar.SimpleToken;
35 import com.puppycrawl.tools.checkstyle.grammar.javadoc.JavadocCommentsLexer;
36 import com.puppycrawl.tools.checkstyle.grammar.javadoc.JavadocCommentsParser;
37 import com.puppycrawl.tools.checkstyle.utils.JavadocUtil;
38
39 /**
40 * Used for parsing Javadoc comment as DetailNode tree.
41 *
42 */
43 public class JavadocDetailNodeParser {
44
45 /**
46 * Parse error while rule recognition.
47 */
48 public static final String MSG_JAVADOC_PARSE_RULE_ERROR = "javadoc.parse.rule.error";
49
50 /**
51 * Message property key for the Unclosed HTML message.
52 */
53 public static final String MSG_UNCLOSED_HTML_TAG = "javadoc.unclosedHtml";
54
55 /** Symbols with which javadoc starts. */
56 private static final String JAVADOC_START = "/**";
57
58 /**
59 * Creates a new {@code JavadocDetailNodeParser} instance.
60 */
61 public JavadocDetailNodeParser() {
62 // no code by default
63 }
64
65 /**
66 * Parses the given Javadoc comment AST into a {@link ParseStatus} object.
67 *
68 * <p>
69 * This method extracts the raw Javadoc comment text from the supplied
70 * {@link DetailAST}, creates a new lexer and parser for the Javadoc grammar,
71 * and attempts to parse it into an AST of {@link DetailNode}s.
72 * The parser uses {@link PredictionMode#SLL} for
73 * faster performance and stops parsing on the first error encountered by
74 * using {@link CheckstyleParserErrorStrategy}.
75 * </p>
76 *
77 * @param javadocCommentAst
78 * the {@code DetailAST} node representing the Javadoc comment in the source file
79 * @return a {@code ParseStatus} containing the root of the parsed Javadoc
80 * tree (if successful), the first non-tight HTML tag (if any), and
81 * the error message (if parsing failed)
82 */
83 public ParseStatus parseJavadocComment(DetailAST javadocCommentAst) {
84 final int blockCommentLineNumber = javadocCommentAst.getLineNo();
85
86 final String javadocComment = JavadocUtil.getJavadocCommentContent(javadocCommentAst);
87 final ParseStatus result = new ParseStatus();
88
89 // Use a new error listener each time to be able to use
90 // one check instance for multiple files to be checked
91 // without getting side effects.
92 final DescriptiveErrorListener errorListener = new DescriptiveErrorListener();
93
94 // Log messages should have line number in scope of file,
95 // not in scope of Javadoc comment.
96 // Offset is line number of beginning of Javadoc comment.
97 errorListener.setOffset(javadocCommentAst.getLineNo() - 1);
98
99 final JavadocCommentsLexer lexer =
100 new JavadocCommentsLexer(CharStreams.fromString(javadocComment), true);
101
102 lexer.removeErrorListeners();
103 lexer.addErrorListener(errorListener);
104
105 final CommonTokenStream tokens = new CommonTokenStream(lexer);
106 tokens.fill();
107
108 final Set<SimpleToken> unclosedTags = lexer.getUnclosedTagNameTokens();
109 final JavadocCommentsParser parser = new JavadocCommentsParser(tokens, unclosedTags);
110
111 // set prediction mode to SLL to speed up parsing
112 parser.getInterpreter().setPredictionMode(PredictionMode.SLL);
113
114 // remove default error listeners
115 parser.removeErrorListeners();
116
117 parser.addErrorListener(errorListener);
118
119 // JavadocParserErrorStrategy stops parsing on first parse error encountered unlike the
120 // DefaultErrorStrategy used by ANTLR which rather attempts error recovery.
121 parser.setErrorHandler(new CheckstyleParserErrorStrategy());
122
123 try {
124 final JavadocCommentsParser.JavadocContext javadoc = parser.javadoc();
125 final int javadocColumnNumber = javadocCommentAst.getColumnNo()
126 + JAVADOC_START.length();
127
128 final JavadocCommentsAstVisitor visitor = new JavadocCommentsAstVisitor(
129 tokens, blockCommentLineNumber, javadocColumnNumber);
130 final DetailNode tree = visitor.visit(javadoc);
131
132 result.setTree(tree);
133
134 result.firstNonTightHtmlTag = visitor.getFirstNonTightHtmlTag();
135
136 result.setParseErrorMessage(errorListener.getErrorMessage());
137 }
138 catch (ParseCancellationException | IllegalArgumentException exc) {
139 result.setParseErrorMessage(errorListener.getErrorMessage());
140 }
141
142 return result;
143 }
144
145 /**
146 * Custom error listener for JavadocParser that prints user readable errors.
147 */
148 private static final class DescriptiveErrorListener extends BaseErrorListener {
149
150 /**
151 * Offset is line number of beginning of the Javadoc comment. Log
152 * messages should have line number in scope of file, not in scope of Javadoc comment.
153 */
154 private int offset;
155
156 /**
157 * Error message that appeared while parsing.
158 */
159 private ParseErrorMessage errorMessage;
160
161 /**
162 * Creates a new {@code DescriptiveErrorListener} instance.
163 */
164 private DescriptiveErrorListener() {
165 // no code by default
166 }
167
168 /**
169 * Getter for error message during parsing.
170 *
171 * @return Error message during parsing.
172 */
173 private ParseErrorMessage getErrorMessage() {
174 return errorMessage;
175 }
176
177 /**
178 * Sets offset. Offset is line number of beginning of the Javadoc
179 * comment. Log messages should have line number in scope of file, not
180 * in scope of Javadoc comment.
181 *
182 * @param offset
183 * offset line number
184 */
185 /* package */ void setOffset(int offset) {
186 this.offset = offset;
187 }
188
189 /**
190 * Logs parser errors in Checkstyle manner. Parser can generate error
191 * messages. There is special error that parser can generate. It is
192 * missed close HTML tag. This case is special because parser prints
193 * error like {@code "no viable alternative at input 'b \n *\n'"} and it
194 * is not clear that error is about missed close HTML tag. Other error
195 * messages are not special and logged simply as "Parse Error...".
196 *
197 * <p>{@inheritDoc}
198 */
199 @Override
200 public void syntaxError(
201 Recognizer<?, ?> recognizer, Object offendingSymbol,
202 int line, int charPositionInLine,
203 String msg, RecognitionException ex) {
204 final int lineNumber = offset + line;
205
206 final String target;
207 if (recognizer instanceof final JavadocCommentsLexer lexer) {
208 target = lexer.getPreviousToken().getText();
209 }
210 else {
211 final int ruleIndex = ex.getCtx().getRuleIndex();
212 final String ruleName = recognizer.getRuleNames()[ruleIndex];
213 target = convertUpperCamelToUpperUnderscore(ruleName);
214 }
215
216 errorMessage = new ParseErrorMessage(lineNumber,
217 MSG_JAVADOC_PARSE_RULE_ERROR, charPositionInLine, msg, target);
218
219 }
220
221 /**
222 * Converts the given {@code text} from camel case to all upper case with
223 * underscores separating each word.
224 *
225 * @param text The string to convert.
226 * @return The result of the conversion.
227 */
228 private static String convertUpperCamelToUpperUnderscore(String text) {
229 final StringBuilder result = new StringBuilder(20);
230 for (int index = 0; index < text.length(); index++) {
231 final char letter = text.charAt(index);
232 if (Character.isUpperCase(letter)) {
233 result.append('_');
234 }
235 result.append(Character.toUpperCase(letter));
236 }
237 return result.toString();
238 }
239
240 }
241
242 /**
243 * Contains result of parsing javadoc comment: DetailNode tree and parse error message.
244 */
245 public static class ParseStatus {
246
247 /**
248 * DetailNode tree (is null if parsing fails).
249 */
250 private DetailNode tree;
251
252 /**
253 * Parse error message (is null if parsing is successful).
254 */
255 private ParseErrorMessage parseErrorMessage;
256
257 /**
258 * Stores the first non-tight HTML tag encountered while parsing javadoc.
259 *
260 * @see <a
261 * href="https://checkstyle.org/writing-javadoc-checks.html#Tight-HTML_rules">
262 * Tight HTML rules</a>
263 */
264 private DetailNode firstNonTightHtmlTag;
265
266 /**
267 * Creates a new {@code ParseStatus} instance.
268 */
269 public ParseStatus() {
270 // no code by default
271 }
272
273 /**
274 * Getter for DetailNode tree.
275 *
276 * @return DetailNode tree if parsing was successful, null otherwise.
277 */
278 public DetailNode getTree() {
279 return tree;
280 }
281
282 /**
283 * Sets DetailNode tree.
284 *
285 * @param tree DetailNode tree.
286 */
287 public void setTree(DetailNode tree) {
288 this.tree = tree;
289 }
290
291 /**
292 * Getter for error message during parsing.
293 *
294 * @return Error message if parsing was unsuccessful, null otherwise.
295 */
296 public ParseErrorMessage getParseErrorMessage() {
297 return parseErrorMessage;
298 }
299
300 /**
301 * Sets parse error message.
302 *
303 * @param parseErrorMessage Parse error message.
304 */
305 public void setParseErrorMessage(ParseErrorMessage parseErrorMessage) {
306 this.parseErrorMessage = parseErrorMessage;
307 }
308
309 /**
310 * This method is used to check if the javadoc parsed has non-tight HTML tags.
311 *
312 * @return returns true if the javadoc has at least one non-tight HTML tag; false otherwise
313 * @see <a
314 * href="https://checkstyle.org/writing-javadoc-checks.html#Tight-HTML_rules">
315 * Tight HTML rules</a>
316 */
317 public boolean isNonTight() {
318 return firstNonTightHtmlTag != null;
319 }
320
321 /**
322 * Getter for the first non-tight HTML tag encountered while parsing javadoc.
323 *
324 * @return the first non-tight HTML tag that is encountered while parsing Javadoc,
325 * if one exists
326 * @see <a href="https://checkstyle.org/writing-javadoc-checks.html#Tight-HTML_rules">
327 * Tight HTML rules</a>
328 */
329 public DetailNode getFirstNonTightHtmlTag() {
330 return firstNonTightHtmlTag;
331 }
332
333 }
334
335 /**
336 * Contains information about parse error message.
337 */
338 public static class ParseErrorMessage {
339
340 /**
341 * Line number where parse error occurred.
342 */
343 private final int lineNumber;
344
345 /**
346 * Key for error message.
347 */
348 private final String messageKey;
349
350 /**
351 * Error message arguments.
352 */
353 private final Object[] messageArguments;
354
355 /**
356 * Initializes parse error message.
357 *
358 * @param lineNumber line number
359 * @param messageKey message key
360 * @param messageArguments message arguments
361 */
362 /* package */ ParseErrorMessage(int lineNumber, String messageKey,
363 Object... messageArguments) {
364 this.lineNumber = lineNumber;
365 this.messageKey = messageKey;
366 this.messageArguments = messageArguments.clone();
367 }
368
369 /**
370 * Getter for line number where parse error occurred.
371 *
372 * @return Line number where parse error occurred.
373 */
374 public int getLineNumber() {
375 return lineNumber;
376 }
377
378 /**
379 * Getter for key for error message.
380 *
381 * @return Key for error message.
382 */
383 public String getMessageKey() {
384 return messageKey;
385 }
386
387 /**
388 * Getter for error message arguments.
389 *
390 * @return Array of error message arguments.
391 */
392 public Object[] getMessageArguments() {
393 return messageArguments.clone();
394 }
395
396 }
397
398 }