<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);">
The link to the Eclipse issue: <a href="https://github.com/eclipse-jdt/eclipse.jdt.ui/issues/1800" data-outlook-id="46207202-d9bc-4f80-b4da-93a44ec582f1">
https://github.com/eclipse-jdt/eclipse.jdt.ui/issues/1800</a></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);">
Thank you for filing these bugs, Nir!</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 dir="ltr" class="ms-outlook-mobile-reference-message skipProofing"></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>Nir Lisker <nlisker@gmail.com><br>
<b>Date: </b>Thursday, October 2, 2025 at 12:06<br>
<b>To: </b>Andy Goryachev <andy.goryachev@oracle.com><br>
<b>Cc: </b>Kevin Rushforth <kevin.rushforth@oracle.com>, openjfx-dev <openjfx-dev@openjdk.org><br>
<b>Subject: </b>[External] : Re: Using markdown-style javadoc comments (JEP 467)<br>
<br>
</div>
<div dir="ltr" class="ms-outlook-mobile-reference-message skipProofing">As both referenced pull requests are mine, I'll add that MD docs are especially helpful with regards to code blocks. The combination of {@code} and <pre> is cumbersome. {@snippet} is also
a good solution here. I've been using MD comments since JDK 23 and I never found the need to use HTML ones since, especially when you can still use HTML tags in MD comments, which are necessary for tables (the MD tables flavor in the JDK can't add the mandatory
alt-text/caption).</div>
<div dir="ltr" class="ms-outlook-mobile-reference-message skipProofing"><br>
</div>
<div dir="ltr" class="ms-outlook-mobile-reference-message skipProofing">Further, I don't see an issue with mixed HTML and MD comments in the same file/repo, just like with any newer replacements. If a relevant segment of code changes, the doc comments can be
converted with it (and I would argue that this conversion is always an improvement).</div>
<div dir="ltr" class="ms-outlook-mobile-reference-message skipProofing"><br>
</div>
<div dir="ltr" class="ms-outlook-mobile-reference-message skipProofing">Andy, I use the integration builds of Eclipse. They are stable and contain the latest fixes so I don't need to wait for the quarterly releases. Parsing MD docs has been fixed, writing them
still entails some annoyances (issue #1800 in jdt.ui), but it works.</div>
<div dir="ltr" class="ms-outlook-mobile-reference-message skipProofing"><br>
</div>
<div dir="ltr" class="gmail_attr">On Thu, Oct 2, 2025 at 8:11 PM Andy Goryachev <<a href="mailto:andy.goryachev@oracle.com" data-outlook-id="b3eee39c-14d1-4843-87bb-da598e20e486">andy.goryachev@oracle.com</a>> wrote:</div>
<blockquote style="margin: 0px 0px 0px 0.8ex; padding-left: 1ex; border-left-width: 1px; border-left-style: solid; border-left-color: rgb(204, 204, 204);">
<div dir="ltr" class="gmail_quote" style="font-family: "Iosevka Fixed SS16", Arial, Helvetica, sans-serif; font-size: 12pt; color: rgb(0, 0, 0);">
I think it's a good idea, the new markdown style is more readable and compact.</div>
<div dir="ltr" class="gmail_quote" style="font-family: "Iosevka Fixed SS16", Arial, Helvetica, sans-serif; font-size: 12pt; color: rgb(0, 0, 0);">
<br>
</div>
<div dir="ltr" class="gmail_quote" style="font-family: "Iosevka Fixed SS16", Arial, Helvetica, sans-serif; font-size: 12pt; color: rgb(0, 0, 0);">
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).</div>
<div dir="ltr" class="gmail_quote" style="font-family: "Iosevka Fixed SS16", Arial, Helvetica, sans-serif; font-size: 12pt; color: rgb(0, 0, 0);">
<br>
</div>
<div dir="ltr" class="gmail_quote" style="font-family: "Iosevka Fixed SS16", Arial, Helvetica, sans-serif; font-size: 12pt; color: rgb(0, 0, 0);">
-andy</div>
<div dir="ltr" class="gmail_quote" style="font-family: "Iosevka Fixed SS16", Arial, Helvetica, sans-serif; font-size: 12pt; color: rgb(0, 0, 0);">
<br>
</div>
<div id="m_-4521226714730766045mail-editor-reference-message-container">
<div 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 href="mailto:openjfx-dev-retn@openjdk.org" target="_blank" data-outlook-id="57918d27-c597-4ee3-94ab-818e26ec931a">openjfx-dev-retn@openjdk.org</a>> on behalf of Kevin Rushforth <<a href="mailto:kevin.rushforth@oracle.com" target="_blank" data-outlook-id="0f17b289-2921-495b-85f5-d131ef3ed35e">kevin.rushforth@oracle.com</a>><br>
<b>Date: </b>Thursday, October 2, 2025 at 09:59<br>
<b>To: </b>openjfx-dev <<a href="mailto:openjfx-dev@openjdk.org" target="_blank" data-outlook-id="be8c0b2b-94c4-417c-8721-18e6cf057e86">openjfx-dev@openjdk.org</a>><br>
<b>Subject: </b>Using markdown-style javadoc comments (JEP 467)<br>
<br>
</div>
<div style="font-size: 11pt;">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" target="_blank" data-outlook-id="a126788b-85bd-445d-8d64-4d1790ec3467">
https://openjdk.org/jeps/467</a><br>
[1] <a href="https://urldefense.com/v3/__https://github.com/openjdk/jfx/pull/1873__;!!ACWV5N9M2RV99hQ!O5_sVZ_A2EEt6rDf452reR900oHvcRgWAdRo0544Cue6VbR5-edyNMwIgdzRe9QQXQqEz2sNP_UN4EQnaicL$" target="_blank" data-outlook-id="3879e887-4a74-46c6-938e-f392b4bb3cad">
https://github.com/openjdk/jfx/pull/1873</a><br>
[2] <a href="https://urldefense.com/v3/__https://github.com/openjdk/jfx/pull/1880__;!!ACWV5N9M2RV99hQ!O5_sVZ_A2EEt6rDf452reR900oHvcRgWAdRo0544Cue6VbR5-edyNMwIgdzRe9QQXQqEz2sNP_UN4Gq9AoGB$" target="_blank" data-outlook-id="53ca0389-4a8f-4c4a-87ed-7465a5695aa1">
https://github.com/openjdk/jfx/pull/1880</a><br>
[3] <a href="https://urldefense.com/v3/__https://github.com/openjdk/jfx/pull/1873*discussion_r2283161713__;Iw!!ACWV5N9M2RV99hQ!O5_sVZ_A2EEt6rDf452reR900oHvcRgWAdRo0544Cue6VbR5-edyNMwIgdzRe9QQXQqEz2sNP_UN4Btnfz2B$" target="_blank" data-outlook-id="5f955512-5c30-41d2-85d4-698ffa3e9d53">
https://github.com/openjdk/jfx/pull/1873#discussion_r2283161713</a><br>
<br>
</div>
</div>
</blockquote>
</div>
</body>
</html>