RFR: JDK-8298405: Support Markdown in Documentation Comments [v2]

[Jonathan Gibbons]

On Thu, 11 Jan 2024 15:35:13 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

>> Update: 
>> Markdown in tags defined by the user on the command-line works pretty much as expected: not great, but not bad.
>> 
>> Headings in user-defined tags work, but are semantically questionable, since the tags are generated inside a definition list (which itself is maybe questionable, these days.). There is (currently) no special accommodation for the "virtual heading" in the presentation of the block tag.
>> 
>> Headings, sections, HTML 5, Markdown and taglets are a complicated mess, and probably better discussed and tracked in JBS.
>
> Understood. FWIW, here are a few examples of headings in user-defined tags in JDK:
> 
> https://github.com/openjdk/jdk/blob/a6785e4d633908596ddb6de6d2eeab1c9ebdf2c3/src/java.base/share/classes/java/math/BigDecimal.java#L229-L239
> 
> https://github.com/openjdk/jdk/blob/ddbbd36e4b064b9e7433f0a55973d72cd6dbc0d3/src/java.xml/share/classes/module-info.java#L402-L420
> 
> https://github.com/openjdk/jdk/blob/6f6486e97743eadfb20b4175e1b4b2b05b59a17a/src/jdk.incubator.vector/share/classes/jdk/incubator/vector/Vector.java#L1089-L1093

Thanks for the examples.

Stylistically, they are maybe questionable.  But we can make sure that something sensible happens, and deal with stylistic issues later.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1454239539