On Wed, 15 Nov 2023 18:48:59 GMT, Jonathan Gibbons <j...@openjdk.org> wrote:
>> Hmm. teeny-tiny "yes", dominated by a big "BUT". >> >> There is no easy simple direct support for Markdown in user-defined taglets, >> since there is no way to know the syntactic form of user-defined tags. We >> might be able to do something for user-defined tags given on the command >> line (with `-tag`) but in general we should be wary and think carefully >> about putting any headings inside any block tag, because block tags get >> converted to HTML definition lists. >> >> --- >> >> Separately, generally speaking, the Markdown headings in any doc comment >> should start at level 1 and increase from there. An offset will be added >> during translation to give the correct heading level in the overall page. >> There is a guard in the code (but no warning as yet) if you "overflow" >> heading level 6. For example, if you go overboard and use `#### my heading` >> in the comment for a method (where the offset for headings is 3), it will >> (currently) max out at level 6. Generating warnings for questionable >> Markdown is somewhat against the spirit of Markdown. It would seem a bit >> weird to warn against an obscure case like overflowing headings when the >> general policy for real errors is no message and just show the literal text. > > 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 ------------- PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1449039906
