Javadoc parser/grammar doesn't report the correct lines in Javadoc AST. #10208
Description
Identified at https://github.com/checkstyle-antlr4/checkstyle-antlr4/issues/15, ANTLR doesn't support the \r (pre-OSX macos) line ending any longer, and has no plans to add support. Therefore, when parsing a Javadoc in a file that uses the \r line ending, the line number never increases in the Javadoc:
public class Test {
/**
* This is a javadoc comment.
* More info, on another line.
*/
void doStuff() {
}
}
Unix utilities do not play well with \r, which renders as ^M with cat:
➜ src cat -v Test.java
public class Test {^M /**^M * This is a javadoc comment.^M * More info, on another line.^M */^M void doStuff() {^M^M }^M}^M%
➜ src java -jar checkstyle-8.44-all.jar -J Test.java
CLASS_DEF -> CLASS_DEF [1:0]
|--MODIFIERS -> MODIFIERS [1:0]
| `--LITERAL_PUBLIC -> public [1:0]
|--LITERAL_CLASS -> class [1:8]
|--IDENT -> Test [1:14]
`--OBJBLOCK -> OBJBLOCK [1:19]
|--LCURLY -> { [1:19]
|--METHOD_DEF -> METHOD_DEF [6:4]
| |--MODIFIERS -> MODIFIERS [6:4]
| |--TYPE -> TYPE [6:4]
| | |--BLOCK_COMMENT_BEGIN -> /* [2:4]
| | | |--COMMENT_CONTENT -> *\r * This is a javadoc comment.\r * More info, on another line.\r [2:6]
| | | | `--JAVADOC -> JAVADOC [2:7] // ok
| | | | |--NEWLINE -> \r [2:7] // ok
| | | | |--LEADING_ASTERISK -> * [2:8] // wrong, should be 3
| | | | |--TEXT -> This is a javadoc comment. [2:14] // wrong, should be 3
| | | | |--NEWLINE -> \r [2:41] // wrong, should be 3
| | | | |--LEADING_ASTERISK -> * [2:42] // wrong, should be 4
| | | | |--TEXT -> More info, on another line. [2:48] // wrong, should be 4
| | | | |--NEWLINE -> \r [2:76] // wrong, should be 4
| | | | |--TEXT -> [2:77] // wrong, should be 5
| | | | `--EOF -> <EOF> [2:82] // wrong, should be 5
| | | `--BLOCK_COMMENT_END -> */ [5:5]
| | `--LITERAL_VOID -> void [6:4]
| |--IDENT -> doStuff [6:9]
| |--LPAREN -> ( [6:16]
| |--PARAMETERS -> PARAMETERS [6:17]
| |--RPAREN -> ) [6:17]
| `--SLIST -> { [6:19]
| `--RCURLY -> } [8:4]
`--RCURLY -> } [9:0]
As you can see, the Javadoc starts on line 2, but then the line number never advances within that Javadoc AST. This is because the consume() function in ANTLR's interpreter doesn't recognize the \r alone as a line ending any longer (it only looks for \n, which covers the other two line endings). We should be able to handle any line ending that Java supports, which is \r, \n, and \r\n.
I would expect the Javadoc AST to track line numbers correctly. Similar issue was originally reported at #2329, and problem was also noted at #2329 (comment).