Integrated: 8352249: Remove incidental whitespace in traditional doc comments

[Hannes Wallnöfer]

On Thu, 13 Mar 2025 13:12:10 GMT, Hannes Wallnöfer <hannesw at openjdk.org> wrote:

> Please review a patch to remove incidental indentation from traditional doc comments, comparable to doing a `String.stripIndent()` on the comment contents but without special treatment of a last blank line. This adds a `stripIndent()` method to the `Tokens.Comment` interface and a new `JavadocTokenizer.StrippedComment` nested class that implements indentation stripping while maintaining a map of position offsets to the original comment. 
> 
> While the patch changes `javadoc` output by removing leading whitespace, the change is generally not visible in the browser except in `<pre>` elements, which is the point of this enhancement. 
> 
> The change affects most tree positions in the AST checker tests in javac/doctree, but mostly does not affect the structure of the parsed trees, with the exception of `BreakIterator` tests in `FirstSentenceTest.java`. 
> 
> `BreakIterator` does not recognize `.\n` immediately followed by a lower case letter as sentence break, while it recognizes the break if the letter is an upper-case letter *or* if there is a space between the line break and the letter. I find this rule a bit peculiar but AFAICT we can't influence the behavior of `BreakIterator`, so I have added tests that cover both lower and upper-case behavior.
> 
> The source position lookup in the stripped comment is implemented by creating a new `OffsetMap` that translates from the stripped to the original comment, then using the original comment's `OffsetMap` to translate the position to the source file. `OffsetMap` is relatively lightweight (usually 2 `int[]` elements per comment paragraph), so the added overhead is not too bad. 
> 
> Inspired by [JDK-8305688](https://bugs.openjdk.org/browse/JDK-8305688) I did various test builds with restricted jobs and memory settings, but didn't notice any change in processing or memory overhead to API docs builds.

This pull request has now been integrated.

Changeset: a5d06a18
Author:    Hannes Wallnöfer <hannesw at openjdk.org>
URL:       https://git.openjdk.org/jdk/commit/a5d06a18762c81eda5883c07b42621278b9209c9
Stats:     1438 lines in 64 files changed: 268 ins; 53 del; 1117 mod

8352249: Remove incidental whitespace in traditional doc comments

Reviewed-by: liach

-------------

PR: https://git.openjdk.org/jdk/pull/24032