RFR: JDK-8322979: Add informative discussion to Modifier

[Pavel Rappo]

On Wed, 10 Jan 2024 06:00:18 GMT, Joe Darcy <darcy at openjdk.org> wrote:

> Add a few apiNote concerning source-level modifiers that are not represented in java.lang.reflect.Modifier.

src/java.base/share/classes/java/lang/reflect/Modifier.java line 237:

> 235:      * To make a high-fidelity representation of the Java source
> 236:      * modifiers of a class or member, source-level modifiers that do
> 237:      * not <em>not</em> have a constant in the this class should be

Suggestion:

     * <em>not</em> have a constant in this class should be

src/java.base/share/classes/java/lang/reflect/Modifier.java line 238:

> 236:      * modifiers of a class or member, source-level modifiers that do
> 237:      * not <em>not</em> have a constant in the this class should be
> 238:      * included and ordered consistent with the full recommended

Suggestion:

     * included and ordered consistently with the full recommended

src/java.base/share/classes/java/lang/reflect/Modifier.java line 243:

> 241:      * {@linkplain Method#toGenericString() method} the "{@link
> 242:      * Method#isDefault() default}" modifier is ordered immediately
> 243:      * before "{@code static}" (JLS {@jls 9.4}). For a {@linkplain

Nothing wrong with that, but note that unlike other similar sections, for whatever reason, JLS 9.4 does **not** suggest this:
> If two or more (distinct) ... modifiers appear in a ... declaration, it is customary, though not required, that they appear in the order consistent with that shown above in the production for ...

I [mused] about the reasons behind it recently, but only JLS experts know them for sure. (CC'in @dansmithcode)

[mused]: https://mail.openjdk.org/pipermail/core-libs-dev/2024-January/117398.html

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

PR Review Comment: https://git.openjdk.org/jdk/pull/17338#discussion_r1447162013
PR Review Comment: https://git.openjdk.org/jdk/pull/17338#discussion_r1447165140
PR Review Comment: https://git.openjdk.org/jdk/pull/17338#discussion_r1447218402