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

Reply via email to