RFR: 8345348: CSS media feature queries [v34]

[Michael Strauß]

On Tue, 8 Jul 2025 18:32:10 GMT, Kevin Rushforth <kcr at openjdk.org> wrote:

>> Michael Strauß has updated the pull request with a new target base due to a merge or a rebase. The pull request now contains 50 commits:
>> 
>>  - Merge branch 'master' into feature/media-queries
>>  - Merge branch 'master' into feature/media-queries
>>  - Merge branch 'master' into feature/media-queries
>>  - use custom mediaFeature javadoc tag
>>  - Merge branch 'master' into feature/media-queries
>>  - fix wrong <br> HTML tags
>>  - Merge branch 'master' into feature/media-queries
>>  - doc
>>  - reorder Scene.Preferences.colorScheme
>>  - move doc from Scene.Preferences to Platform.Preferences
>>  - ... and 40 more: https://git.openjdk.org/jfx/compare/fc4642db...b01f0414
>
> 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.

-------------

PR Review Comment: https://git.openjdk.org/jfx/pull/1655#discussion_r2193389437