RFR: 8301302: Platform preferences API [v5]

[Kevin Rushforth]

On Wed, 6 Sep 2023 18:02:31 GMT, Kevin Rushforth <kcr at openjdk.org> wrote:

>> +1
>> 
>> we could put the doc (in markdown format) in the doc-files/platform directory (or create any other subdirectory, see JDK-8309749)
>
> I think Michael meant that the javadoc-generated API docs in this file need to be kept up to date. If we are going to say _all_, then yes it will. I don't see a need for any other doc related to this.

On further reflection, I don't think we want to specify this list so tightly that adding a new key that isn't in the list would be a spec violation. We _do_ want to keep the implementation and the docs in sync, but I can imagine a case where a new platform might cause a new key to show up even though we haven't documented it yet.

It's unlikely that this would happen, since the proposed implementation doesn't blindly surface properties that it doesn't know about, but perhaps a future implementation on some platform might do this.

So my suggestion is to soften the wording a little bit. One suggestion is something like:


     * The following preferences are potentially available on the specified platforms:


I note that Joe Darcy also raised this question in [this comment](https://bugs.openjdk.org/browse/JDK-8319138?focusedId=14625402&page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#comment-14625402) in the CSR.

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

PR Review Comment: https://git.openjdk.org/jfx/pull/1014#discussion_r1397753195