RFR: JDK-8298405: Implement JEP 467: Markdown Documentation Comments [v44]

[Jonathan Gibbons]

On Mon, 4 Mar 2024 15:16:32 GMT, Pavel Rappo <prappo at 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