On Tue, 8 Jul 2025 20:30:14 GMT, Michael Strauß <mstra...@openjdk.org> wrote:
>> modules/javafx.graphics/src/main/java/javafx/application/Platform.java line
>> 617:
>>
>>> 615: *
>>> 616: * @return the {@code persistentScrollBars} property
>>> 617: * @mediaFeature <a
>>> href="../scene/doc-files/cssref.html#mediafeatures">{@code
>>> -fx-prefers-persistent-scrollbars}</a>
>>
>> I note that this tag seems to be ineffective (perhaps because this is a
>> property and gets special javadoc treatment).
>
> That's correct, the javadoc tool copies javadocs from the property field to
> its accessor methods. But it doesn't do a throrough job: it only copies
> standard tags and a few custom tags (`@defaultValue` for example). I think
> that's either a bug or a missing feature of the javadoc tool. I can't find a
> single example where it would be useful to _not_ copy a javadoc tag from the
> property field to its accessor methods.
>
> So it seems like we have several options:
> 1. Keep the custom `@mediaFeature` tag in JavaFX, and file an enhancement
> with the javadoc tool to copy _all_ tags to property accessors. Then the
> media feature tags would start to show up in generated docs once the javadoc
> enhancement is in.
> 2. File an enhancement, but only start using the `@mediaFeature` tag once
> javadoc is fixed.
> 3. Don't use a custom javadoc tag at all.
>
> I would prefer option 1, because it is the most structured form of
> documentation, and doesn't require us to come back later. In general, custom
> javadoc tags are a very useful feature to present structured information, and
> I think we should prefer it to prose.
I notice that I've described the behavior of the javadoc tool for property
fields, but this is a property method. However, my conclusion is the same: not
rendering custom tags is a bug in the tool.
-------------
PR Review Comment: https://git.openjdk.org/jfx/pull/1655#discussion_r2193400531
