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 <[email protected]> on behalf of
Michael Strauß <[email protected]>
*Date: *Monday, July 1, 2024 at 09:45
*To: *
*Cc: *[email protected] <[email protected]>
*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
<[email protected]> 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