Should we document Styleable properties?

[Kevin Rushforth]

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