<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
</head>
<body>
<div dir="ltr" style="font-family: "Iosevka Fixed SS16", Arial, Helvetica, sans-serif; font-size: 12pt; color: rgb(0, 0, 0);">
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.</div>
<div dir="ltr" style="font-family: "Iosevka Fixed SS16", Arial, Helvetica, sans-serif; font-size: 12pt; color: rgb(0, 0, 0);">
<br>
</div>
<div dir="ltr" style="font-family: "Iosevka Fixed SS16", Arial, Helvetica, sans-serif; font-size: 12pt; color: rgb(0, 0, 0);">
-andy</div>
<div dir="ltr" style="font-family: "Iosevka Fixed SS16", Arial, Helvetica, sans-serif; font-size: 12pt; color: rgb(0, 0, 0);">
<br>
</div>
<div id="mail-editor-reference-message-container">
<div class="ms-outlook-mobile-reference-message skipProofing">
<meta name="Generator" content="Microsoft Exchange Server">
</div>
<div class="ms-outlook-mobile-reference-message skipProofing" style="text-align: left; padding: 3pt 0in 0in; border-width: 1pt medium medium; border-style: solid none none; border-color: rgb(181, 196, 223) currentcolor currentcolor; font-family: Aptos; font-size: 12pt; color: black;">
<b>From: </b>openjfx-dev <openjfx-dev-retn@openjdk.org> on behalf of Kevin Rushforth <kevin.rushforth@oracle.com><br>
<b>Date: </b>Friday, October 10, 2025 at 12:26<br>
<b>To: </b>openjfx-dev@openjdk.org <openjfx-dev@openjdk.org><br>
<b>Subject: </b>Re: Using markdown-style javadoc comments (JEP 467)<br>
<br>
</div>
<div class="PlainText" style="font-size: 11pt;">I informally polled a few folks in the core libs group. They haven't<br>
started using it in the JDK yet, but would consider it primarily for new<br>
classes; some felt as Michael did that mixing styles in the same class<br>
would be annoying.<br>
<br>
I can see the argument for consistency, especially in a file like Node<br>
or Control, where we have many existing properties and other methods.<br>
For additions of a new property or method in such a file, consistency<br>
seems more important than being able to use markdown.<br>
<br>
In cases where there aren't so many methods, or where you are already<br>
modifying many of them, it might be reasonable to use markdown for new<br>
or modified methods.<br>
<br>
Perhaps as a compromise, we could consider allowing for new classes and<br>
classes where you are modifying a large percentage of the existing docs<br>
anyway, but in general, avoid using markdown in existing classes.<br>
<br>
Concretely, that would mean asking Nir to update PR 1873 [1] to not use<br>
markdown-style doc comments (it seems gratuitous there anyway, since it<br>
isn't using any markdown syntax), but allow the use of markdown in PR<br>
1880 [2].<br>
<br>
Thoughts?<br>
<br>
-- Kevin<br>
<br>
[1] <a href="https://github.com/openjdk/jfx/pull/1873" data-outlook-id="d2cdfc7c-e760-42c5-ad66-cbaf8d3d2b20">
https://github.com/openjdk/jfx/pull/1873</a><br>
[2] <a href="https://github.com/openjdk/jfx/pull/1880" data-outlook-id="a494fd19-02a2-4097-9ac7-bd682a13ff43">
https://github.com/openjdk/jfx/pull/1880</a><br>
<br>
<br>
On 10/7/2025 6:33 AM, John Hendrikx wrote:<br>
> I'm of the same mind. I don't see a use case for markdown comments at<br>
> all in a<br>
> project as mature as JavaFX, and I'm unlikely to use them, even for new<br>
> files simply to be<br>
> more consistent with other existing files (and I may copy/paste docs<br>
> sometimes as well).<br>
><br>
> There are barely any code conventions in FX as it is (indent is 4<br>
> spaces, and general Java naming<br>
> conventions are the only ones that I think of that are consistent<br>
> through-out the project), but<br>
> a consistent Javadoc style can also be considered one currently... still.<br>
><br>
> --John<br>
><br>
> On 07/10/2025 10:47, Michael Strauß wrote:<br>
>> Markdown comments are not _better_ than HTML comments, they are just<br>
>> different. In particular, I question the unsubstantiated claim that<br>
>> markdown comments are more readable; I've never once struggled with<br>
>> reading HTML comments, especially if you use the recent additions like<br>
>> {@snippet}.<br>
>><br>
>> I might use markdown comments myself if I were to start a greenfield<br>
>> project. But in a mature project, consistency is more important than<br>
>> (at best) tiny ergonomic improvements. In fact, consistency is one of<br>
>> the most important factors contributing to ergonomy. You point out<br>
>> that you wouldn't want to invite wholesale refactoring, but to be<br>
>> fair, I'd rather have a wholesale refactor to use markdown comments<br>
>> everywhere than be forever annoyed to see two wildly different comment<br>
>> styles next to each other.<br>
>><br>
>> I've looked at recent CSRs and API additions in the JDK, and haven't<br>
>> found a single one using markdown comments. Why the rush to be the<br>
>> first project to use them?<br>
>><br>
>> In any case, if we end up allowing markdown comments, I would strongly<br>
>> suggest to only allow a single comment style per file. Mixing both<br>
>> styles in a single file is an unmitigated readability disaster.<br>
>><br>
>><br>
>><br>
>> On Thu, Oct 2, 2025 at 7:33 PM Kevin Rushforth<br>
>> <kevin.rushforth@oracle.com> wrote:<br>
>>> Now that JavaFX requires JDK 24 to build, we can use features from JDK<br>
>>> 23 and 24 like markdown javadoc comments from JEP 467 [0], which was<br>
>>> delivered in JDK 23.<br>
>>><br>
>>> Two outstanding pull requests, PR 1873 [1] and PR 1880 [2], have<br>
>>> proposed changes that do just that.<br>
>>><br>
>>> As was pointed out in a review comment on PR 1873 [3], we should make a<br>
>>> deliberate decision to start using them and have some guidelines around<br>
>>> doing so.<br>
>>><br>
>>> To that end, I would propose that developers can start using markdown<br>
>>> javadoc comments in new APIs and in APIs that are modified such that<br>
>>> markdown comments would be helpful.<br>
>>><br>
>>> This is not an invitation to do wholesale changing of existing javadoc<br>
>>> comments to markdown-style comments for docs that otherwise aren't being<br>
>>> modified.<br>
>>><br>
>>> Comments are welcome.<br>
>>><br>
>>> -- Kevin<br>
>>><br>
>>> [0] <a href="https://openjdk.org/jeps/467" data-outlook-id="b48a226b-a17d-464b-b502-c9a86b515ff3">
https://openjdk.org/jeps/467</a><br>
>>> [1] <a href="https://github.com/openjdk/jfx/pull/1873" data-outlook-id="de877f66-cc2e-43f6-9bc6-a1b2f7983053">
https://github.com/openjdk/jfx/pull/1873</a><br>
>>> [2] <a href="https://github.com/openjdk/jfx/pull/1880" data-outlook-id="a71d5ed8-af22-4168-bec1-a2cf4ca4326b">
https://github.com/openjdk/jfx/pull/1880</a><br>
>>> [3] <a href="https://github.com/openjdk/jfx/pull/1873#discussion_r2283161713" data-outlook-id="5be53893-23d1-47c3-a242-73968e6930e2">
https://github.com/openjdk/jfx/pull/1873#discussion_r2283161713</a><br>
>>><br>
<br>
</div>
</div>
</body>
</html>