On Tue, 8 Apr 2025 18:14:53 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.
>
> Hannes Wallnöfer has updated the pull request incrementally with one
> additional commit since the last revision:
>
> Review feedback
LGTM
-------------
Marked as reviewed by liach (Reviewer).
PR Review: https://git.openjdk.org/jdk/pull/24112#pullrequestreview-2751060111
