Should we document Styleable properties?

[Andy Goryachev]

Thank you for your feedback!

I agree: referring to places in cssref.html is a good idea.  And perhaps even referring from cssref.html to javadoc might be also a good idea, though cssref.html does suggest the class which owns the corresponding properties, or at least the class in question can be found in most cases.

-andy

From: openjfx-dev <openjfx-dev-retn at openjdk.org> on behalf of Markus Mack <markus.mack at gmail.com>
Date: Monday, July 1, 2024 at 04:48
To: openjfx-dev at openjdk.org <openjfx-dev at openjdk.org>
Subject: Re: Should we document Styleable properties?
I'd say this is a good idea. Both variants are good, we might want to
mention CSS in the first one, though.

Not sure how others do it, but I regularly struggle to find out which
code properties correspond to which CSS styles. This is particularly the
case for names like "background", "border", or "stroke", where there is
no clean 1:1 correspondence, or similar names are used in multiple contexts.

Some way of linking to the current CSS reference might also be helpful
to find out about allowed arguments. If I google something like  "javafx
css" I typically only get links to outdated versions of the CSS
reference. Also, linking back from the CSS reference to the code
properties' javadoc pages is something I've been missing - maybe this
could be added without much additional effort if javadocs are updated
according to this proposal?

Am 28.06.2024 um 23:04 schrieb Andy Goryachev:
>
> 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
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.org/pipermail/openjfx-dev/attachments/20240701/79664938/attachment-0001.htm>