Should we document Styleable properties?

[Markus Mack]

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
>