-
Enhancement
-
Resolution: Fixed
-
P3
-
11
-
None
-
b16
-
generic
-
generic
Leading incidental whitespace at the beginning of each line makes it difficult to author preformatted text using HTML `<pre>` elements in traditional doc comments. While shared indentation is stripped in Markdown line comments, it is preserved in documentation parsed from traditional doc comments due to comment extraction rules[1][2].
[1]: https://docs.oracle.com/en/java/javase/23/docs/api/java.compiler/javax/lang/model/util/Elements.html#getDocComment(javax.lang.model.element.Element)
[2]: https://docs.oracle.com/en/java/javase/23/docs/specs/javadoc/doc-comment-spec.html#traditional-documentation-comments
While the need to track locations in doc comments back to the original source for reporting of errors and warnings has impeded attempts to strip indentation in `DocCommentParser`, it is relatively simple to provide a stripped version of a comment using the same mechanism to map location offsets as used for mapping to the original source file.
The `JavadocTokenizer.OffsetMap` introduced inJDK-8254073 is relatively lightweight (2 int[] elements per offset change) and composable (OffsetMaps can be "stacked" or connected in series). The idea is therefore to create a stripped version of an extracted doc comment which uses an OffsetMap to translate positions to the original extracted comment, and use the original comment's OffsetMap to translate to the file location.
While it would be possible to merge the two OffsetMaps, that would add a lot of complexity (the original map contains other offset changes such as for unicode escapes) with neglectable space benefits. Also, offset map generation needs to be optimized, while use of the map is relatively rare.
An initial implementation has shown that the code is simple and does not add significant computation or memory overhead.
[1]: https://docs.oracle.com/en/java/javase/23/docs/api/java.compiler/javax/lang/model/util/Elements.html#getDocComment(javax.lang.model.element.Element)
[2]: https://docs.oracle.com/en/java/javase/23/docs/specs/javadoc/doc-comment-spec.html#traditional-documentation-comments
While the need to track locations in doc comments back to the original source for reporting of errors and warnings has impeded attempts to strip indentation in `DocCommentParser`, it is relatively simple to provide a stripped version of a comment using the same mechanism to map location offsets as used for mapping to the original source file.
The `JavadocTokenizer.OffsetMap` introduced in
While it would be possible to merge the two OffsetMaps, that would add a lot of complexity (the original map contains other offset changes such as for unicode escapes) with neglectable space benefits. Also, offset map generation needs to be optimized, while use of the map is relatively rare.
An initial implementation has shown that the code is simple and does not add significant computation or memory overhead.
- links to
-
Commit(master) openjdk/jdk/a5d06a18
-
Review(master) openjdk/jdk/24032