JDK 10 RFR of JDK-8187982: Update SourceVersion to mention restricted keywords

[Joseph D. Darcy]

Hello,

Please review this small change to make the 
javax.lang.model.SourceVersion name-related predicates more explicit in 
their handling of restricted keywords:

     JDK-8187982 : Update SourceVersion to mention restricted keywords
     http://cr.openjdk.java.net/~darcy/8187982.0/

Patch below.

(A subsequent fix for JDK-8187951: "Update 
javax.lang.model.SourceVersion for "var" name" will add appropriate spec 
and/or behavior changes for "var".)

Thanks,

-Joe

--- 
old/src/java.compiler/share/classes/javax/lang/model/SourceVersion.java 
2017-09-26 18:27:23.156381931 -0700
+++ 
new/src/java.compiler/share/classes/javax/lang/model/SourceVersion.java 
2017-09-26 18:27:22.764381920 -0700
@@ -216,8 +216,9 @@
       * Character#isJavaIdentifierStart(int)} returns {@code true},
       * followed only by characters for which {@link
       * Character#isJavaIdentifierPart(int)} returns {@code true}.
-     * This pattern matches regular identifiers, keywords, and the
-     * literals {@code "true"}, {@code "false"}, and {@code "null"}.
+     * This pattern matches regular identifiers, keywords, restricted
+     * keywords, and the literals {@code "true"}, {@code "false"}, and
+     * {@code "null"}.
       * The method returns {@code false} for all other strings.
       *
       * @param name the string to check
@@ -251,10 +252,13 @@
       * qualified name in the latest source version.  Unlike {@link
       * #isIdentifier isIdentifier}, this method returns {@code false}
       * for keywords, boolean literals, and the null literal.
+     * This method returns {@code true} for <i>restricted
+     * keywords</i>.
       *
       * @param name the string to check
       * @return {@code true} if this string is a
       * syntactically valid name, {@code false} otherwise.
+     * @jls 3.9 Keywords
       * @jls 6.2 Names and Identifiers
       */
      public static boolean isName(CharSequence name) {
@@ -266,11 +270,14 @@
       * qualified name in the given source version.  Unlike {@link
       * #isIdentifier isIdentifier}, this method returns {@code false}
       * for keywords, boolean literals, and the null literal.
+     * This method returns {@code true} for <i>restricted
+     * keywords</i>.
       *
       * @param name the string to check
       * @param version the version to use
       * @return {@code true} if this string is a
       * syntactically valid name, {@code false} otherwise.
+     * @jls 3.9 Keywords
       * @jls 6.2 Names and Identifiers
       * @since 9
       */
@@ -287,6 +294,8 @@
      /**
       * Returns whether or not {@code s} is a keyword, boolean literal,
       * or null literal in the latest source version.
+     * This method returns {@code false} for <i>restricted
+     * keywords</i>.
       *
       * @param s the string to check
       * @return {@code true} if {@code s} is a keyword, or boolean
@@ -302,6 +311,8 @@
      /**
       * Returns whether or not {@code s} is a keyword, boolean literal,
       * or null literal in the given source version.
+     * This method returns {@code false} for <i>restricted
+     * keywords</i>.
       *
       * @param s the string to check
       * @param version the version to use
--- 
old/src/java.compiler/share/classes/javax/lang/model/element/ModuleElement.java 
2017-09-26 18:27:23.916381952 -0700
+++ 
new/src/java.compiler/share/classes/javax/lang/model/element/ModuleElement.java 
2017-09-26 18:27:23.560381942 -0700
@@ -87,7 +87,7 @@
       *
       * @return {@code true} if this is an open module and {@code
       * false} otherwise
-     */ // TODO: add @jls to unnamed module section
+     */
      boolean isOpen();

      /**
@@ -96,7 +96,9 @@
       *
       * @return {@code true} if this is an unnamed module and {@code
       * false} otherwise
-     */ // TODO: add @jls to unnamed module section
+     *
+     * @jls 7.7.5 Unnamed Modules
+     */
      boolean isUnnamed();

      /**
--- 
old/test/langtools/tools/javac/processing/model/TestSourceVersion.java 
2017-09-26 18:27:24.684381973 -0700
+++ 
new/test/langtools/tools/javac/processing/model/TestSourceVersion.java 
2017-09-26 18:27:24.300381963 -0700
@@ -41,6 +41,7 @@
      public static void main(String... args) {
          testLatestSupported();
          testVersionVaryingKeywords();
+        testRestrictedKeywords();
      }

      private static void testLatestSupported() {
@@ -73,6 +74,27 @@
              }
          }
      }
+
+    private static void testRestrictedKeywords() {
+        // Restricted keywords are not full keywords
+
+        /*
+         * JLS 3.9
+         * " A further ten character sequences are restricted
+         * keywords: open, module, requires, transitive, exports,
+         * opens, to, uses, provides, and with"
+         */
+        Set<String> restrictedKeywords =
+            Set.of("open", "module", "requires", "transitive", "exports",
+                   "opens", "to", "uses", "provides", "with");
+
+        for(String key : restrictedKeywords) {
+            for(SourceVersion version : SourceVersion.values()) {
+                check(false, isKeyword(key, version), "keyword", version);
+                check(true,  isName(key, version),    "name", version);
+            }
+        }
+    }

      private static void check(boolean result, boolean expected,
                                String message, SourceVersion version) {