Using markdown-style javadoc comments (JEP 467)

[John Hendrikx]

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
>>