RFR: 8352389: Remove incidental whitespace in pre/code content [v3]

[Chen Liang]

On Thu, 20 Mar 2025 07:27:39 GMT, Hannes Wallnöfer <hannesw at openjdk.org> wrote:

>> Please review a change to remove incidental whitespace commonly found at the beginning of `<pre><code>` tags in API documentation. 
>> 
>> In a nutshell, using `<pre><code>\n` or `<pre>{@code\n` adds an extra empty line at the beginning of the content, compared to just using `<pre>\n`. This is due to [HTML syntax](https://html.spec.whatwg.org/#the-pre-element:the-pre-element), which ignores a leading `\n` only if it immediately follows the opening `<pre>` tag. It causes leading blank lines in several hundred JDK code samples, such as [here](https://download.java.net/java/early_access/jdk25/docs/api/java.base/java/util/stream/package-summary.html#Reduction) and [here](https://download.java.net/java/early_access/jdk25/docs/api/java.base/java/util/Map.html#computeIfAbsent(K,java.util.function.Function)).
>> 
>> What makes the problem a bit more complicated is that we also need to remove any horizontal whitespace between the `<pre>` and `<code>` tags, as that would otherwise add to the first content line line. 
>> 
>> The feature is implemented in `DocCommentParser` by parsing content of `<pre>` elements into a separate list buffer, and filtering the content when we encounter the `</pre>` close tag. This approach allows us to keep the logic in a single `normalizePreContent` method instead of spreading it all over `DocCommentParser`. The method uses a `DocTreeVisitor` in combination with a `State` enum to make sure pre content is only modified if all conditions are met (which involves inspecting up to the first three DocTrees).
>> 
>> Normalization is also performed for `<pre>{@literal\n`. Although `{@literal}` by itself does not cause the problem described above as it does not produce an HTML tag, any horizontal whitespace between `<pre>` and `{@literal` will cause the problem, so we err on the side of caution. 
>> 
>> This change solves the leading blank line issue in a lot of JDK code fragments, and probably many more in 3rd party Java code.
>
> Hannes Wallnöfer has updated the pull request with a new target base due to a merge or a rebase. The pull request now contains 14 commits:
> 
>  - Merge branch 'master' into JDK-8352389
>  - Improve test
>  - Add comment
>  - 8352389: Remove incidental whitespace in pre/code content
>  - Whitespace normalization in PrettyCheck becomes simpler
>  - Rename method
>  - Update comment
>  - Clean up code, add comments, tests and @bug id
>  - Updated copyright year in testSourceTab breaks test
>  - Update remaining doctree tests & copyright headers
>  - ... and 4 more: https://git.openjdk.org/jdk/compare/fb210e3a...5ec3bc04

src/jdk.compiler/share/classes/com/sun/tools/javac/parser/DocCommentParser.java line 503:

> 501:         if (mainTrees != null) {
> 502:             mainTrees.addAll(trees);
> 503:             trees = mainTrees;

Should we add `mainTrees = null;` after this line?

src/jdk.compiler/share/classes/com/sun/tools/javac/parser/DocCommentParser.java line 1224:

> 1222:     /**
> 1223:      * Removes a newline character following a <code>, {@code or {@literal tag at the
> 1224:      * beginning of <pre> element content, as well as any space/tabs between the pre

Consider converting this to a plain comment as these are not valid javadoc

src/jdk.compiler/share/classes/com/sun/tools/javac/parser/DocCommentParser.java line 1309:

> 1307:         for (var tree : trees) {
> 1308:             var visited = visitor.visit(tree, cx);
> 1309:             if (visited != null) {

Should we just fail if `visited == null`? Can it happen with any user input?

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

PR Review Comment: https://git.openjdk.org/jdk/pull/24112#discussion_r2033694953
PR Review Comment: https://git.openjdk.org/jdk/pull/24112#discussion_r2033696724
PR Review Comment: https://git.openjdk.org/jdk/pull/24112#discussion_r2033700330