Using markdown-style javadoc comments (JEP 467)

[Andy Goryachev]

Another consideration is backporting.  So, despite my earlier support for markdown comments, I reverse my position and say that we should avoid it for the time being.

-andy

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

I informally polled a few folks in the core libs group. They haven't
started using it in the JDK yet, but would consider it primarily for new
classes; some felt as Michael did that mixing styles in the same class
would be annoying.

I can see the argument for consistency, especially in a file like Node
or Control, where we have many existing properties and other methods.
For additions of a new property or method in such a file, consistency
seems more important than being able to use markdown.

In cases where there aren't so many methods, or where you are already
modifying many of them, it might be reasonable to use markdown for new
or modified methods.

Perhaps as a compromise, we could consider allowing for new classes and
classes where you are modifying a large percentage of the existing docs
anyway, but in general, avoid using markdown in existing classes.

Concretely, that would mean asking Nir to update PR 1873 [1] to not use
markdown-style doc comments (it seems gratuitous there anyway, since it
isn't using any markdown syntax), but allow the use of markdown in PR
1880 [2].

Thoughts?

-- Kevin

[1] https://github.com/openjdk/jfx/pull/1873
[2] https://github.com/openjdk/jfx/pull/1880


On 10/7/2025 6:33 AM, John Hendrikx wrote:
> I'm of the same mind.  I don't see a use case for markdown comments at
> all in a
> project as mature as JavaFX, and I'm unlikely to use them, even for new
> files simply to be
> more consistent with other existing files (and I may copy/paste docs
> sometimes as well).
>
> There are barely any code conventions in FX as it is (indent is 4
> spaces, and general Java naming
> conventions are the only ones that I think of that are consistent
> through-out the project), but
> a consistent Javadoc style can also be considered one currently... still.
>
> --John
>
> On 07/10/2025 10:47, Michael Strauß wrote:
>> 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
>>>

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