RFR: 8345348: CSS media feature queries [v34]

[Michael Strauß]

On Tue, 8 Jul 2025 20:30:14 GMT, Michael Strauß <mstrauss at 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