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

[Hannes Wallnöfer]

> 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

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

Changes:
  - all: https://git.openjdk.org/jdk/pull/24112/files
  - new: https://git.openjdk.org/jdk/pull/24112/files/5ec3bc04..69584152

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jdk&pr=24112&range=03
 - incr: https://webrevs.openjdk.org/?repo=jdk&pr=24112&range=02-03

  Stats: 8 lines in 1 file changed: 2 ins; 4 del; 2 mod
  Patch: https://git.openjdk.org/jdk/pull/24112.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/24112/head:pull/24112

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