Using markdown-style javadoc comments (JEP 467)

[Andy Goryachev]

I think it's a good idea, the new markdown style is more readable and compact.

The only downside I found so far is that the latest Eclipse does not refresh the javadoc tab when editing (someone said it's already fixed in the mainline).

-andy

From: openjfx-dev <openjfx-dev-retn at openjdk.org> on behalf of Kevin Rushforth <kevin.rushforth at oracle.com>
Date: Thursday, October 2, 2025 at 09:59
To: openjfx-dev <openjfx-dev at openjdk.org>
Subject: Using markdown-style javadoc comments (JEP 467)

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

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.org/pipermail/openjfx-dev/attachments/20251002/2aa549e0/attachment-0001.htm>