<!DOCTYPE html><html><head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
</head>
<body>
A new javadoc tag seems unlikely. Especially for something like this
where the ask would be to automatically link it to some html file
(cssref.html) somewhere in the current JavaFX sources.<br>
<br>
One more thing to point out, is that even if we could get such a tag
added to the JDK javadoc doclet, it would be quite a while before we
could use it in JavaFX. We would have to get it into JDK 24 or 25
and then wait until we update to that JDK as the minimum needed to
build JavaFX. So maybe in JavaFX 27 we could start using it.<br>
<br>
So it's a nice idea, but doesn't seem practical to implement.<br>
<br>
-- Kevin<br>
<br>
<br>
<div class="moz-cite-prefix">On 7/1/2024 12:16 PM, Andy Goryachev
wrote:<br>
</div>
<blockquote type="cite" cite="mid:BL3PR10MB61852FB42928E7F932847B14E5D32@BL3PR10MB6185.namprd10.prod.outlook.com">
<meta name="Generator" content="Microsoft Word 15 (filtered medium)">
<style>@font-face
{font-family:"Cambria Math";
panose-1:2 4 5 3 5 4 6 3 2 4;}@font-face
{font-family:Aptos;
panose-1:2 11 0 4 2 2 2 2 2 4;}@font-face
{font-family:"Iosevka Fixed SS16";
panose-1:2 0 5 9 3 0 0 0 0 4;}@font-face
{font-family:"Times New Roman \(Body CS\)";
panose-1:2 11 6 4 2 2 2 2 2 4;}p.MsoNormal, li.MsoNormal, div.MsoNormal
{margin:0in;
font-size:10.0pt;
font-family:"Aptos",sans-serif;}p.MsoListParagraph, li.MsoListParagraph, div.MsoListParagraph
{mso-style-priority:34;
margin-top:0in;
margin-right:0in;
margin-bottom:0in;
margin-left:.5in;
font-size:10.0pt;
font-family:"Aptos",sans-serif;}span.EmailStyle19
{mso-style-type:personal-reply;
font-family:"Iosevka Fixed SS16";
color:windowtext;}.MsoChpDefault
{mso-style-type:export-only;
font-size:10.0pt;
mso-ligatures:none;}div.WordSection1
{page:WordSection1;}ol
{margin-bottom:0in;}ul
{margin-bottom:0in;}</style>
<div class="WordSection1">
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Iosevka Fixed SS16"">Thank
you for your feedback, Michael!<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Iosevka Fixed SS16""><o:p> </o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Iosevka Fixed SS16"">Let
me first make sure I understand your suggestion correctly:<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Iosevka Fixed SS16""><o:p> </o:p></span></p>
<ol style="margin-top:0in" type="1" start="1">
<li class="MsoListParagraph" style="margin-left:0in;mso-list:l0 level1 lfo1"><span style="font-size:11.0pt;font-family:"Iosevka Fixed SS16"">add
an annotation, let's say @css-prop<o:p></o:p></span></li>
<li class="MsoListParagraph" style="margin-left:0in;mso-list:l0 level1 lfo1"><span style="font-size:11.0pt;font-family:"Iosevka Fixed SS16"">modify
javadoc tool to create an automated link from the property
name to a place in cssref.html
<o:p></o:p></span></li>
<li class="MsoListParagraph" style="margin-left:0in;mso-list:l0 level1 lfo1"><span style="font-size:11.0pt;font-family:"Iosevka Fixed SS16"">javadoc
will render this as<o:p></o:p></span></li>
</ol>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Iosevka Fixed SS16""><o:p> </o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Iosevka Fixed SS16""><b>@css-prop</b>
this property can be styled with CSS using <a
href="...">-fx-prop-name</a><o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Iosevka Fixed SS16""><o:p> </o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Iosevka Fixed SS16"">I
don't know whether javadoc people will be happy about this
idea: javadoc is a part of jdk and unfortunately javafx is
not, though javadoc does offer certain features to make it
play nice with javafx properties.<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Iosevka Fixed SS16""><o:p> </o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Iosevka Fixed SS16"">This
would also require non-trivial modification to cssref.html
to add anchors where each property name is defined.
Alternatively, it could simply point to a class, for which
we do have an id (e.g. <a id="cell">Cell</a>)<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Iosevka Fixed SS16""><o:p> </o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Iosevka Fixed SS16"">Overall,
it is much more extensive | expensive proposition with
external dependencies. Meaning the probability of it
happening is very low.<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Iosevka Fixed SS16""><o:p> </o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Iosevka Fixed SS16"">Having
said that, this is a great idea, very developer-friendly.<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Iosevka Fixed SS16""><o:p> </o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Iosevka Fixed SS16"">-andy<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Iosevka Fixed SS16""><o:p> </o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Iosevka Fixed SS16""><o:p> </o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Iosevka Fixed SS16""><o:p> </o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Iosevka Fixed SS16""><o:p> </o:p></span></p>
<div id="mail-editor-reference-message-container">
<div>
<div style="border:none;border-top:solid #B5C4DF 1.0pt;padding:3.0pt 0in 0in 0in">
<p class="MsoNormal" style="margin-bottom:12.0pt"><b><span style="font-size:12.0pt;color:black">From:
</span></b><span style="font-size:12.0pt;color:black">openjfx-dev
<a class="moz-txt-link-rfc2396E" href="mailto:openjfx-dev-retn@openjdk.org"><openjfx-dev-retn@openjdk.org></a> on behalf of
Michael Strauß <a class="moz-txt-link-rfc2396E" href="mailto:michaelstrau2@gmail.com"><michaelstrau2@gmail.com></a><br>
<b>Date: </b>Monday, July 1, 2024 at 09:45<br>
<b>To: </b><br>
<b>Cc: </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: Should we document Styleable
properties?<o:p></o:p></span></p>
</div>
<div>
<p class="MsoNormal"><span style="font-size:11.0pt">If we
do this, I suggest to add a custom tag for this
purpose instead<br>
of repeating prose for every property.<br>
The javadoc tool will then render the content of this
tag in the<br>
specification list section of the documentation (where
tags such as<br>
@defaultValue will also appear).<br>
<br>
<br>
On Fri, Jun 28, 2024 at 11:21</span><span style="font-size:11.0pt;font-family:"Arial",sans-serif"> </span><span style="font-size:11.0pt">PM Andy Goryachev<br>
<a class="moz-txt-link-rfc2396E" href="mailto:andy.goryachev@oracle.com"><andy.goryachev@oracle.com></a> wrote:<br>
><br>
> Dear fellow developers:<br>
><br>
><br>
><br>
> Should we document which properties are styleable
with CSS in javadoc? Would that be useful?<br>
><br>
><br>
><br>
> Example:<br>
><br>
><br>
><br>
> /**<br>
><br>
> * Determines the caret blink period. This
property cannot be set to {@code null}.<br>
><br>
> * <p><br>
><br>
> * This is a {@link StyleableProperty} with
the name {@code -fx-caret-blink-period}.<br>
><br>
> * <p><br>
><br>
><br>
><br>
> alternative:<br>
><br>
><br>
><br>
> * This property can be styled with CSS using
{@code -fx-caret-blink-period} name.<br>
><br>
> * @implNote The property object implements
{@link StyleableProperty} interface.<br>
><br>
><br>
><br>
><br>
><br>
> Other ideas are also welcome.<br>
><br>
><br>
><br>
> -andy<o:p></o:p></span></p>
</div>
</div>
</div>
</div>
</blockquote>
<br>
</body>
</html>