Re: RFR: JDK-8298405: Support Markdown in Documentation Comments [v2]
On Wed, 17 Jan 2024 00:13:40 GMT, Jonathan Gibbons wrote: >> 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. Filed [JDK-8324876](https://bugs.openjdk.org/browse/JDK-8324876) to reconsider these tags. - PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1470321290
Re: RFR: JDK-8298405: Support Markdown in Documentation Comments [v2]
On Thu, 11 Jan 2024 15:35:13 GMT, Pavel Rappo 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
Re: RFR: JDK-8298405: Support Markdown in Documentation Comments [v2]
On Wed, 15 Nov 2023 18:48:59 GMT, Jonathan Gibbons 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
Re: RFR: JDK-8298405: Support Markdown in Documentation Comments [v2]
On Wed, 15 Nov 2023 00:58:51 GMT, Jonathan Gibbons wrote: >> test/langtools/jdk/javadoc/doclet/testMarkdown/TestMarkdown.java line 613: >> >>> 611: /// Lorem ipsum. >>> 612: /// >>> 613: /// ## ATX-style subheading for executable >> >> Can we use Markdown headings inside block tags, such as `@apiNote`? If so, >> should they start from h5? If so, should we get a warning if they "overflow" >> h6? > > 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. - PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1394643842
Re: RFR: JDK-8298405: Support Markdown in Documentation Comments [v2]
On Thu, 9 Nov 2023 16:39:58 GMT, Pavel Rappo wrote: >> Jonathan Gibbons has updated the pull request incrementally with one >> additional commit since the last revision: >> >> Customize support for Markdown headings > > test/langtools/jdk/javadoc/doclet/testMarkdown/TestMarkdown.java line 613: > >> 611: /// Lorem ipsum. >> 612: /// >> 613: /// ## ATX-style subheading for executable > > Can we use Markdown headings inside block tags, such as `@apiNote`? If so, > should they start from h5? If so, should we get a warning if they "overflow" > h6? 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. - PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1393499177
Re: RFR: JDK-8298405: Support Markdown in Documentation Comments [v2]
On Wed, 8 Nov 2023 22:17:21 GMT, Jonathan Gibbons wrote: >> Please review a patch to add support for Markdown syntax in documentation >> comments, as described in the associated JEP. >> >> Notable features: >> >> * support for `///` documentation comments in `JavaTokenizer` >> * new module `jdk.internal.md` -- a private copy of the `commonmark-java` >> library >> * updates to `DocCommentParser` to treat `///` comments as Markdown >> * updates to the standard doclet to render Markdown comments in HTML > > Jonathan Gibbons has updated the pull request incrementally with one > additional commit since the last revision: > > Customize support for Markdown headings I see you've added a new feature and tests for it. test/langtools/jdk/javadoc/doclet/testMarkdown/TestMarkdown.java line 613: > 611: /// Lorem ipsum. > 612: /// > 613: /// ## ATX-style subheading for executable Can we use Markdown headings inside block tags, such as `@apiNote`? If so, should they start from h5? If so, should we get a warning if they "overflow" h6? - PR Review: https://git.openjdk.org/jdk/pull/16388#pullrequestreview-1723026055 PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1388270695
Re: RFR: JDK-8298405: Support Markdown in Documentation Comments [v2]
> Please review a patch to add support for Markdown syntax in documentation > comments, as described in the associated JEP. > > Notable features: > > * support for `///` documentation comments in `JavaTokenizer` > * new module `jdk.internal.md` -- a private copy of the `commonmark-java` > library > * updates to `DocCommentParser` to treat `///` comments as Markdown > * updates to the standard doclet to render Markdown comments in HTML Jonathan Gibbons has updated the pull request incrementally with one additional commit since the last revision: Customize support for Markdown headings - Changes: - all: https://git.openjdk.org/jdk/pull/16388/files - new: https://git.openjdk.org/jdk/pull/16388/files/128363bf..ea9c1614 Webrevs: - full: https://webrevs.openjdk.org/?repo=jdk=16388=01 - incr: https://webrevs.openjdk.org/?repo=jdk=16388=00-01 Stats: 266 lines in 4 files changed: 254 ins; 2 del; 10 mod Patch: https://git.openjdk.org/jdk/pull/16388.diff Fetch: git fetch https://git.openjdk.org/jdk.git pull/16388/head:pull/16388 PR: https://git.openjdk.org/jdk/pull/16388
