Should we document Styleable properties?

[Andy Goryachev]

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 <openjfx-dev-retn at openjdk.org> on behalf of Michael Strauß <michaelstrau2 at gmail.com>
Date: Monday, July 1, 2024 at 09:45
To:
Cc: openjfx-dev at openjdk.org <openjfx-dev at openjdk.org>
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
<andy.goryachev at oracle.com> 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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.org/pipermail/openjfx-dev/attachments/20240701/8baacc96/attachment.htm>