Should we document Styleable properties?

[Michael Strauß]

The javadoc tool already supports custom tags out of the box with the
"-tag" command line option. For example, adding this line in the
gradle javadoc task (build.gradle L4241) would introduce a custom tag:

    options.tags("styleableProperty:a:CSS property name:")

Of course, there's no special processing of custom tags, so we would
have to add a link manually if we want one. But that's certainly not a
worse situation compared to adding a manual link in prose text.


On Mon, Jul 1, 2024 at 9:16 PM Andy Goryachev <andy.goryachev at oracle.com> wrote:
>
> Thank you for your feedback, Michael!
>
>
>
> Let me first make sure I understand your suggestion correctly:
>
>
>
> add an annotation, let's say @css-prop
> modify javadoc tool to create an automated link from the property name to a place in cssref.html
> 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