Should we document Styleable properties?

[Kevin Rushforth]

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 <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/ddcb98b4/attachment-0001.htm>