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

[Hannes Wallnöfer]

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 combined `pre` and `code` tags. 
>> 
>> In a nutshell, using `<pre><code>\n` or `<pre>{@code\n` at the beginning of preformatted code adds an extra empty line at the beginning of the content, compared to just using `<pre>\n`. This is due to [HTML syntax rules](https://html.spec.whatwg.org/#the-pre-element:the-pre-element) and needlessly complicates use of these tags in doc comments. 
>> 
>> This change does the minimum necessary to remove the leading line break. What makes the task slightly more complicated is that we also have to remove any horizontal whitespace between `pre` and `code` tags as these would otherwise add indentation to the first line of actual pre content.
>> 
>> This is implemented by parsing content of `<pre>` elements into a separate list buffer in `DocCommentParser`, 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 in various existing places of `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 in `<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.
>
> 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

Note: Github shows 14 commits for this PR, but the first 10 belong to #24032, on which this PR depended and which has already been integrated. Only the last 4 commits actually belong to this PR.

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

PR Comment: https://git.openjdk.org/jdk/pull/24112#issuecomment-2742416198