8292576: Improve wording of AccessFlag-related specs

Reviewed-by: alanb

Author: jddarcy

src/java.base/share/classes/java/lang/module/ModuleDescriptor.java

@@ -213,8 +213,10 @@ public Set<Modifier> modifiers() {
         }
 
         /**
-         * {@return an unmodifiable set of the module {@linkplain AccessFlag
-         * requires flags, possibly empty}}
+         * Returns the set of the module {@linkplain AccessFlag
+         * requires flags}.
+         *
+         * @return A possibly-empty unmodifiable set of requires flags
          * @see #modifiers()
          * @jvms 4.7.25 The Module Attribute
          * @since 20
@@ -447,8 +449,10 @@ public Set<Modifier> modifiers() {
         }
 
         /**
-         * {@return an unmodifiable set of the module {@linkplain AccessFlag
-         * export flags} for this module descriptor, possibly empty}
+         * Returns the set of the module {@linkplain AccessFlag
+         * export flags} for this module descriptor.
+         *
+         * @return A possibly-empty unmodifiable set of export flags
          * @see #modifiers()
          * @jvms 4.7.25 The Module Attribute
          * @since 20
@@ -669,8 +673,10 @@ public Set<Modifier> modifiers() {
         }
 
         /**
-         * {@return an unmodifiable set of the module {@linkplain AccessFlag
-         * opens flags}, possibly empty}
+         * Returns the set of the module {@linkplain AccessFlag opens
+         * flags}.
+         *
+         * @return A possibly-empty unmodifiable set of opens flags
          * @see #modifiers()
          * @jvms 4.7.25 The Module Attribute
          * @since 20
@@ -1354,8 +1360,9 @@ public Set<Modifier> modifiers() {
     }
 
     /**
-     * {@return an unmodifiable set of the {@linkplain AccessFlag
-     * module flags}, possibly empty}
+     * Returns the set of the {@linkplain AccessFlag module flags}.
+     *
+     * @return A possibly-empty unmodifiable set of module flags
      * @see #modifiers()
      * @jvms 4.7.25 The Module Attribute
      * @since 20

src/java.base/share/classes/java/lang/reflect/AccessFlag.java

@@ -99,7 +99,7 @@ public enum AccessFlag {
 
     /**
      * The access flag {@code ACC_PUBLIC}, corresponding to the source
-     * modifier {@link Modifier#PUBLIC public} with a mask value of
+     * modifier {@link Modifier#PUBLIC public}, with a mask value of
      * <code>{@value "0x%04x" Modifier#PUBLIC}</code>.
      */
     PUBLIC(Modifier.PUBLIC, true,
@@ -115,7 +115,7 @@ public Set<Location> apply(ClassFileFormatVersion cffv) {
 
     /**
      * The access flag {@code ACC_PRIVATE}, corresponding to the
-     * source modifier {@link Modifier#PRIVATE private} with a mask
+     * source modifier {@link Modifier#PRIVATE private}, with a mask
      * value of <code>{@value "0x%04x" Modifier#PRIVATE}</code>.
      */
     PRIVATE(Modifier.PRIVATE, true, Location.SET_FIELD_METHOD_INNER_CLASS,
@@ -130,7 +130,7 @@ public Set<Location> apply(ClassFileFormatVersion cffv) {
 
     /**
      * The access flag {@code ACC_PROTECTED}, corresponding to the
-     * source modifier {@link Modifier#PROTECTED protected} with a mask
+     * source modifier {@link Modifier#PROTECTED protected}, with a mask
      * value of <code>{@value "0x%04x" Modifier#PROTECTED}</code>.
      */
     PROTECTED(Modifier.PROTECTED, true, Location.SET_FIELD_METHOD_INNER_CLASS,
@@ -145,7 +145,7 @@ public Set<Location> apply(ClassFileFormatVersion cffv) {
 
     /**
      * The access flag {@code ACC_STATIC}, corresponding to the source
-     * modifier {@link Modifier#STATIC static} with a mask value of
+     * modifier {@link Modifier#STATIC static}, with a mask value of
      * <code>{@value "0x%04x" Modifier#STATIC}</code>.
      */
     STATIC(Modifier.STATIC, true, Location.SET_FIELD_METHOD_INNER_CLASS,
@@ -159,7 +159,7 @@ public Set<Location> apply(ClassFileFormatVersion cffv) {
 
     /**
      * The access flag {@code ACC_FINAL}, corresponding to the source
-     * modifier {@link Modifier#FINAL final} with a mask
+     * modifier {@link Modifier#FINAL final}, with a mask
      * value of <code>{@value "0x%04x" Modifier#FINAL}</code>.
      */
     FINAL(Modifier.FINAL, true,
@@ -217,7 +217,7 @@ public Set<Location> apply(ClassFileFormatVersion cffv) {
 
     /**
      * The access flag {@code ACC_SYNCHRONIZED}, corresponding to the
-     * source modifier {@link Modifier#SYNCHRONIZED synchronized} with
+     * source modifier {@link Modifier#SYNCHRONIZED synchronized}, with
      * a mask value of <code>{@value "0x%04x" Modifier#SYNCHRONIZED}</code>.
      */
     SYNCHRONIZED(Modifier.SYNCHRONIZED, true, Location.SET_METHOD, null),
@@ -238,7 +238,7 @@ public Set<Location> apply(ClassFileFormatVersion cffv) {
 
    /**
      * The access flag {@code ACC_VOLATILE}, corresponding to the
-     * source modifier {@link Modifier#VOLATILE volatile} with a mask
+     * source modifier {@link Modifier#VOLATILE volatile}, with a mask
      * value of <code>{@value "0x%04x" Modifier#VOLATILE}</code>.
      */
     VOLATILE(Modifier.VOLATILE, true, Location.SET_FIELD, null),
@@ -259,7 +259,7 @@ public Set<Location> apply(ClassFileFormatVersion cffv) {
 
     /**
      * The access flag {@code ACC_TRANSIENT}, corresponding to the
-     * source modifier {@link Modifier#TRANSIENT transient} with a
+     * source modifier {@link Modifier#TRANSIENT transient}, with a
      * mask value of <code>{@value "0x%04x" Modifier#TRANSIENT}</code>.
      */
     TRANSIENT(Modifier.TRANSIENT, true, Location.SET_FIELD, null),
@@ -280,7 +280,7 @@ public Set<Location> apply(ClassFileFormatVersion cffv) {
 
     /**
      * The access flag {@code ACC_NATIVE}, corresponding to the source
-     * modifier {@link Modifier#NATIVE native} with a mask value of
+     * modifier {@link Modifier#NATIVE native}, with a mask value of
      * <code>{@value "0x%04x" Modifier#NATIVE}</code>.
      */
     NATIVE(Modifier.NATIVE, true, Location.SET_METHOD, null),
@@ -301,7 +301,7 @@ public Set<Location> apply(ClassFileFormatVersion cffv) {
 
     /**
      * The access flag {@code ACC_ABSTRACT}, corresponding to the
-     * source modifier {@link Modifier#ABSTRACT abstract} with a mask
+     * source modifier {@link Modifier#ABSTRACT abstract}, with a mask
      * value of <code>{@value "0x%04x" Modifier#ABSTRACT}</code>.
      */
     ABSTRACT(Modifier.ABSTRACT, true,
@@ -316,7 +316,7 @@ public Set<Location> apply(ClassFileFormatVersion cffv) {
 
     /**
      * The access flag {@code ACC_STRICT}, corresponding to the source
-     * modifier {@link Modifier#STRICT strictfp} with a mask value of
+     * modifier {@link Modifier#STRICT strictfp}, with a mask value of
      * <code>{@value "0x%04x" Modifier#STRICT}</code>.
      *
      * @apiNote