On Mon, 3 Mar 2025 16:41:18 GMT, Hannes Wallnöfer <hann...@openjdk.org> wrote:
> Please review an enhancement to make `DocCommentParser` normalize whitespace
> inside `<pre>` elements. The normalization is conceptually simple and and
> intended to be minimally invasive. Before parsing, `DocCommentParser` checks
> whether the text is a traditional doc comment and whether every line starts
> with a space character, which is commonly the case in traditional doc
> comments. If so, a single leading space is removed in block content (top
> level text and `{@code}`/`{@literal}` tags) when parsing within HTML `<pre>`
> tags.
>
> This fixes the incidental one-space indentation in the vast majority of JDK
> code samples using `<pre>` alone or in combination with `<code>` or
> `{@code}`. In fact, I only found one code sample in JDK code that isn't
> solved by this change, for which I included a fix in this PR (it's in
> `String.startsWith(String, int)`, where I replaced the 10 char indentation
> and trailing line with a `<blockquote>`).
>
> The many added `boolean inBlockContent` arguments pased around in
> `DocCommentParser` are to make sure the removal is not applied to multiline
> inline content, which is maybe a bit fussy considering there is not a lot of
> multiline inline content in `<pre>` tags and it usually would not mind about
> removal of a non-essential space character, but I wanted to keep the change
> minimal. There are few javadoc tests that had to be adapted, most of the
> testing is done in `test/langtools/tools/javac/doctree`.
>
> If the exact number of leading whitespace in `<pre>` tags is important to any
> javadoc user the old output can be restored by increasing the indentation by
> 1. There will be a release note for this of course.
>
> Unfortunately, there is another whitespace problem that can't be solved as
> easily, and that is a leading blank line caused by `<pre><code>\n` open tags.
> Browsers will [ignore a newline immediately following a `<pre>` tag][1], but
> not if there is a `<code>` tag in between. There are hundreds of occurrences
> of this in JDK code, including variants with space characters mixed in. The
> fix in javadoc proper would be too complex, so I decided to solve it with 3
> lines of JavaScript and a regex to reverse the order of `<code>\n` at the
> beginning of `<pre>` tags while removing any intermediary space. Script
> operation is indiscernible and it solves the problem.
>
> [1]: https://html.spec.whatwg.org/#the-pre-element:the-pre-element
As you indicated, there are two problems being addressed here, which might
indicate the need for two separate patches. These issues are:
1. The leading 1-space problem.
2. The trailing newline-after-<pre> problem
For the first, it is unduly hard work to fix this just for `<pre>` blocks. I
still think that an overall better long-term solution would be to apply a
conceptual `stripIndent` to the entire doc comment. This would bring
traditional comments into line with the new Markdown comments, and can be done
in just a few lines in `DocCommentParser`, and doing it there in DCP means you
need not update `Elements.getDocComment`. If nothing else, I would suggest
doing the experiment and comparing the generated docs, to verify there are no
unexpected side effects. If there are any significant unexpected side effects,
then your approach might deserve a second look. You could also make this a
JDK-version-specific change if you wanted: meaning the new behavior does not
apply to older JDK versions, although that is not a policy we have adhered to
in the past.
For the second, I just feel that is a step too far, using JavaScript to clean
up what some might consider to be bad input. Authors should either write HTML
according to the HTML (and CSS?) specs, so that `javadoc` is just a
"pass-through" layer, or authors should use a suitable construct, like
`{@snippet...}`, that is "pleasing" to look at in source form while still
generating the desired output.
-------------
PR Comment: https://git.openjdk.org/jdk/pull/23868#issuecomment-2701699839
