On Wed, 15 May 2024 21:04:36 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 incrementally with one > additional commit since the last revision: > > update tests for dangling doc comments, per review feedback > > A meta question about the JEP: Why don't Javadoc features (like snippets > > and markdown comments) don't go through preview, while Compiler features > > mostly do? Is there any bar for previews? > > Jon could probably reply more substantially, but my understanding is that > [_JEP 12: Preview Features_](https://openjdk.org/jeps/12) is barely > applicable here (emphasis mine): > > > ## Summary > > A _preview feature_ is a new feature of the Java language, Java Virtual > > Machine, or **Java SE API** that is fully specified, fully implemented, and > > yet impermanent. It is available in a JDK feature release to provoke > > developer feedback based on real world use; this may lead to it becoming > > permanent in a future Java SE Platform. > > Technically, the only reason we could invoke JEP 12 here would be a tiny > change to `Elements`, which is Java SE. But let's be honest, that change is > not what _JEP 467: Markdown Documentation Comments_ is about. Additionally, JavaDoc supports Preview APIs, but does not support previews (meta-previews?) of its own features. We simply don't have a mechanism to say: "Hey, that thing you are looking at is a new feature of JavaDoc. Click _here_ to learn more." ------------- PR Comment: https://git.openjdk.org/jdk/pull/16388#issuecomment-2115404225
