On Wed, 13 Dec 2023 21:25:13 GMT, Jorn Vernee <jver...@openjdk.org> wrote:
>> Right, I suggested putting that in parentheses. Historically we haven't been
>> very formal about distinguishing between normative (Java SE) specifications
>> and informative text that talks about implementations. In this case I felt
>> that enclosing the text in parentheses and also adding hedging words
>> ("typically") made it clear that this text isn't normative.
>
> FWIW, for the FFM API, we describe the `--enable-native-access` command line
> flag in a separate `@implNote`:
> https://github.com/openjdk/jdk/blob/cf948548c390c42ca63525d41a9d63ff31349c3a/src/java.base/share/classes/java/lang/foreign/package-info.java#L164-L171
Thanks for the suggestion, Jorn. I tried embedding `@implNote` within the
ordered list, but looks like it is not allowed. It would be nice if we could
use it inside a list, but since it is about overriding the property values, I
would rather not have the description apart from that list item.
-------------
PR Review Comment: https://git.openjdk.org/jdk/pull/17065#discussion_r1425921350
