On Mon, 4 Mar 2024 15:16:32 GMT, Pavel Rappo <pra...@openjdk.org> wrote:
> > I have a test case to report. The following results in no `@param`
> > information being rendered, which I think is a bug:
> > ```
> > /// Hello, _Markdown_ world!
> > ///
> > /// <p>
> > /// @param <T> hello
> > /// </p>
> > ///
> > public class C<T> { }
> > ```
>
> Scratch that. After experimenting a bit more with **traditional** javadoc
> comments, I realised that it might be expected that `@param` would be lost in
> that `<p>...</p>` block; okay.
>
> Still, I find it surprising that the description of the `@param` tag in the
> above comment, hosted in `///` or `/**...*/`, is a single node of type
> `RawText` with the following content:
>
> ```
> hello
> </p>
> ```
>
> (Note, the content includes `</p>`.)
The Markdown aspect of this is behaving about as well as can be expected. But
the generated form is certainly confusing and can be considered a
less-than-optimal presentation of a paragraph within a definition list. You
can see the same behavior in a traditional comment with `@param <T>
<p>hello</p>`. Ideally, we could/should tweak the CSS for this situation, in a
separate changeset.
-------------
PR Comment: https://git.openjdk.org/jdk/pull/16388#issuecomment-1979452615
