On Wed, 19 Mar 2025 11:26:32 GMT, Hannes Wallnöfer <[email protected]> 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.
This pull request has now been integrated.
Changeset: 24ff96af
Author: Hannes Wallnöfer <[email protected]>
URL:
https://git.openjdk.org/jdk/commit/24ff96afe41b62275fe8635e477ecc04bff93123
Stats: 352 lines in 7 files changed: 340 ins; 3 del; 9 mod
8352389: Remove incidental whitespace in pre/code content
Reviewed-by: liach
-------------
PR: https://git.openjdk.org/jdk/pull/24112
