Using markdown-style javadoc comments (JEP 467)

[Michael Strauß]

Markdown comments are not _better_ than HTML comments, they are just
different. In particular, I question the unsubstantiated claim that
markdown comments are more readable; I've never once struggled with
reading HTML comments, especially if you use the recent additions like
{@snippet}.

I might use markdown comments myself if I were to start a greenfield
project. But in a mature project, consistency is more important than
(at best) tiny ergonomic improvements. In fact, consistency is one of
the most important factors contributing to ergonomy. You point out
that you wouldn't want to invite wholesale refactoring, but to be
fair, I'd rather have a wholesale refactor to use markdown comments
everywhere than be forever annoyed to see two wildly different comment
styles next to each other.

I've looked at recent CSRs and API additions in the JDK, and haven't
found a single one using markdown comments. Why the rush to be the
first project to use them?

In any case, if we end up allowing markdown comments, I would strongly
suggest to only allow a single comment style per file. Mixing both
styles in a single file is an unmitigated readability disaster.



On Thu, Oct 2, 2025 at 7:33 PM Kevin Rushforth
<kevin.rushforth at oracle.com> wrote:
>
> Now that JavaFX requires JDK 24 to build, we can use features from JDK
> 23 and 24 like markdown javadoc comments from JEP 467 [0], which was
> delivered in JDK 23.
>
> Two outstanding pull requests, PR 1873 [1] and PR 1880 [2], have
> proposed changes that do just that.
>
> As was pointed out in a review comment on PR 1873 [3], we should make a
> deliberate decision to start using them and have some guidelines around
> doing so.
>
> To that end, I would propose that developers can start using markdown
> javadoc comments in new APIs and in APIs that are modified such that
> markdown comments would be helpful.
>
> This is not an invitation to do wholesale changing of existing javadoc
> comments to markdown-style comments for docs that otherwise aren't being
> modified.
>
> Comments are welcome.
>
> -- Kevin
>
> [0] https://openjdk.org/jeps/467
> [1] https://github.com/openjdk/jfx/pull/1873
> [2] https://github.com/openjdk/jfx/pull/1880
> [3] https://github.com/openjdk/jfx/pull/1873#discussion_r2283161713
>