RFR: 8345348: CSS media feature queries [v34]

[Kevin Rushforth]

On Tue, 8 Jul 2025 20:37:31 GMT, Michael Strauß <mstrauss at openjdk.org> wrote:

>> 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.

Very likely this is a javadoc limitation. I don't know how likely it will be to get it fixed, but it would be no earlier than in JDK 26, which means that it would be (at least) JavaFX 27 before it started working. That makes option 1 less attractive.

I would probably recommend option 2. Otherwise, we won't see any reference to media feature queries in the Preferences doc any time soon.

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

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