Should we document Styleable properties?

[Andy Goryachev]

Would even work with Eclipse out of the box:

[cid:image002.png at 01DACBC1.BB882780]


I also like the fact that we won't need to maintain links manually as there would not be any.

-andy





From: openjfx-dev <openjfx-dev-retn at openjdk.org> on behalf of Kevin Rushforth <kevin.rushforth at oracle.com>
Date: Monday, July 1, 2024 at 14:12
To: openjfx-dev at openjdk.org <openjfx-dev at openjdk.org>
Subject: Re: Should we document Styleable properties?
Sure, something like this would be possible if it helps minimize
boilerplate.

-- Kevin


On 7/1/2024 1:58 PM, Michael Strauß wrote:
> 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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.org/pipermail/openjfx-dev/attachments/20240701/4efe11a1/attachment-0001.htm>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: image002.png
Type: image/png
Size: 169476 bytes
Desc: image002.png
URL: <https://mail.openjdk.org/pipermail/openjfx-dev/attachments/20240701/4efe11a1/image002-0001.png>