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.

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.

So it's a nice idea, but doesn't seem practical to implement.

-- Kevin


On 7/1/2024 12:16 PM, Andy Goryachev wrote:

Thank you for your feedback, Michael!

Let me first make sure I understand your suggestion correctly:

 1. add an annotation, let's say @css-prop
 2. modify javadoc tool to create an automated link from the property
    name to a place in cssref.html
 3. javadoc will render this as

<b>@css-prop</b> this property can be styled with CSS using <a href="...">-fx-prop-name</a>

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.

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

Overall, it is much more extensive | expensive proposition with external dependencies.  Meaning the probability of it happening is very low.

Having said that, this is a great idea, very developer-friendly.

-andy

*From: *openjfx-dev <[email protected]> on behalf of Michael Strauß <[email protected]>
*Date: *Monday, July 1, 2024 at 09:45
*To: *
*Cc: *[email protected] <[email protected]>
*Subject: *Re: Should we document Styleable properties?

If we do this, I suggest to add a custom tag for this purpose instead
of repeating prose for every property.
The javadoc tool will then render the content of this tag in the
specification list section of the documentation (where tags such as
@defaultValue will also appear).


On Fri, Jun 28, 2024 at 11:21 PM Andy Goryachev
<[email protected]> wrote:
>
> Dear fellow developers:
>
>
>
> Should we document which properties are styleable with CSS in javadoc?  Would that be useful?
>
>
>
> Example:
>
>
>
>     /**
>
>      * Determines the caret blink period.  This property cannot be set to {@code null}.
>
>      * <p>
>
>      * This is a {@link StyleableProperty} with the name {@code -fx-caret-blink-period}.
>
>      * <p>
>
>
>
> alternative:
>
>
>
>      * This property can be styled with CSS using {@code -fx-caret-blink-period} name.
>
>      * @implNote The property object implements {@link StyleableProperty} interface.
>
>
>
>
>
> Other ideas are also welcome.
>
>
>
> -andy

Reply via email to