<!DOCTYPE html><html><head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
</head>
<body>
As a rule we don't backport new API, but we do sometimes backport
wording changes (since we don't have the same constraints that Java
SE spec has). So this would be another consideration in the
discussion as to when and whether to allow using markdown.<br>
<br>
-- Kevin<br>
<br>
<br>
<div class="moz-cite-prefix">On 10/15/2025 9:20 AM, Andy Goryachev
wrote:<br>
</div>
<blockquote type="cite" cite="mid:DS0PR10MB727108708F9DD88E2B4FC7D2E5E8A@DS0PR10MB7271.namprd10.prod.outlook.com">
<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 <a class="moz-txt-link-rfc2396E" href="mailto:openjfx-dev-retn@openjdk.org"><openjfx-dev-retn@openjdk.org></a>
on behalf of Kevin Rushforth
<a class="moz-txt-link-rfc2396E" href="mailto:kevin.rushforth@oracle.com"><kevin.rushforth@oracle.com></a><br>
<b>Date: </b>Friday, October 10, 2025 at 12:26<br>
<b>To: </b><a class="moz-txt-link-abbreviated" href="mailto:openjfx-dev@openjdk.org">openjfx-dev@openjdk.org</a>
<a class="moz-txt-link-rfc2396E" href="mailto:openjfx-dev@openjdk.org"><openjfx-dev@openjdk.org></a><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" moz-do-not-send="true" class="moz-txt-link-freetext">
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" moz-do-not-send="true" class="moz-txt-link-freetext">
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>
>> <a class="moz-txt-link-rfc2396E" href="mailto:kevin.rushforth@oracle.com"><kevin.rushforth@oracle.com></a> 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" moz-do-not-send="true" class="moz-txt-link-freetext">
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" moz-do-not-send="true" class="moz-txt-link-freetext">
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" moz-do-not-send="true" class="moz-txt-link-freetext">
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" moz-do-not-send="true" class="moz-txt-link-freetext">
https://github.com/openjdk/jfx/pull/1873#discussion_r2283161713</a><br>
>>><br>
<br>
</div>
</div>
</blockquote>
<br>
</body>
</html>