On Mon, 8 Jan 2024 21:26:50 GMT, Jonathan Gibbons <j...@openjdk.org> 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 with a new target base due to a > merge or a rebase. The incremental webrev excludes the unrelated changes > brought in by the merge/rebase. The pull request contains seven additional > commits since the last revision: > > - Merge with upstream/master > - Merge remote-tracking branch 'upstream/master' into > 8298405.doclet-markdown-v3 > - Address review comments > - Fix whitespace > - Improve handling of embedded inline taglets > - Customize support for Markdown headings > - JDK-8298405: Support Markdown in Documentation Comments On CommonMark. * `jdk.internal.md` contains 133 files, the vast majority of which are from commonmark-java 0.21.0. According to https://github.com/commonmark/commonmark-java/releases 0.21.0 is the latest/current release; good. Questions: * Did we take the tagged commit or mainline at some point after the tagged commit? If it's the latter, we need to take the tagged version. * What's the difference between those commonmark-java files in this PR and official commonmark-java? In other words, how do we adapt them? It would be nice to have a description of the procedure or a script to update those files. * `jdk.internal.md` exports packages to `jdk.jshell`. A question for @lahodaj, who maintains `jdk.jshell`: when do we need to create a new PR similar to that withdrawn https://github.com/openjdk/jdk/pull/11936? src/jdk.internal.md/share/classes/jdk/internal/markdown/MarkdownTransformer.java line 2: > 1: /* > 2: * Copyright (c) 2005, 2023, Oracle and/or its affiliates. All rights > reserved. It's surprising to see 2005. src/jdk.internal.md/share/classes/module-info.java line 29: > 27: * Internal support for Markdown. > 28: * > 29: * @since 22 Suggestion: * @since 23 ------------- PR Review: https://git.openjdk.org/jdk/pull/16388#pullrequestreview-1818084469 PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1450342017 PR Review Comment: https://git.openjdk.org/jdk/pull/16388#discussion_r1450347103