JDK 8 RFR for javax.lang.model API refinement

[Joe Darcy]

Hello,

In response to the call for feedback on the JSR 269 maintenance review 
covering Java SE 8 features, a former JSR 269 EG member (hi Bruce!) sent 
in some suggestions in improve the specification.

First, since the javax.lang.model.* API does not include a component for 
abstract syntax trees, the statement in IntersectionType concerning 
using IntersectionType for cast expressions is a statement about the 
reference implementation rather than about the specification per se. 
Therefore, I'm proposing changing this statement to be an @implNote.

Second, Bruce recommended a reordering of paragraphs in 
javax.lang.model.util.Types to make the meaning clearer; a reordering I 
agree is an improvement.

Patch below.

Thanks,

-Joe

diff -r 5bf0af735c61 
src/share/classes/javax/lang/model/type/IntersectionType.java
--- a/src/share/classes/javax/lang/model/type/IntersectionType.java Mon 
Dec 09 19:29:33 2013 +0000
+++ b/src/share/classes/javax/lang/model/type/IntersectionType.java Thu 
Dec 12 15:16:42 2013 -0800
@@ -35,10 +35,12 @@
   * {@code <T extends Number & Runnable>} is an (implicit) intersection
   * type.  As of {@link javax.lang.model.SourceVersion#RELEASE_8
   * RELEASE_8}, this is represented by an {@code IntersectionType} with
- * {@code Number} and {@code Runnable} as its bounds.  Also as of the
- * {@link javax.lang.model.SourceVersion#RELEASE_8 RELEASE_8},
- * intersection types can explicitly appear as the target type of a
- * cast expression.
+ * {@code Number} and {@code Runnable} as its bounds.
+ *
+ * @implNote Also as of {@link
+ * javax.lang.model.SourceVersion#RELEASE_8 RELEASE_8},in the
+ * reference implementation intersection types can explicitly appear
+ * as the target type of a cast expression.
   *
   * @since 1.8
   */
diff -r 5bf0af735c61 src/share/classes/javax/lang/model/util/Types.java
--- a/src/share/classes/javax/lang/model/util/Types.java    Mon Dec 09 
19:29:33 2013 +0000
+++ b/src/share/classes/javax/lang/model/util/Types.java    Thu Dec 12 
15:16:42 2013 -0800
@@ -60,13 +60,6 @@
      /**
       * Tests whether two {@code TypeMirror} objects represent the same 
type.
       *
-     * <p>Since annotations are only meta-data associated with a type,
-     * the set of annotations on either argument is <em>not</em> taken
-     * into account when computing whether or not two {@code
-     * TypeMirror} objects are the same type. In particular, two
-     * {@code TypeMirror} objects can have different annotations and
-     * still be considered the same.
-     *
       * <p>Caveat: if either of the arguments to this method represents a
       * wildcard, this method will return false.  As a consequence, a 
wildcard
       * is not the same type as itself.  This might be surprising at first,
@@ -77,6 +70,13 @@
       *   {@code list.add(list.get(0));}
       * </pre>
       *
+     * <p>Since annotations are only meta-data associated with a type,
+     * the set of annotations on either argument is <em>not</em> taken
+     * into account when computing whether or not two {@code
+     * TypeMirror} objects are the same type. In particular, two
+     * {@code TypeMirror} objects can have different annotations and
+     * still be considered the same.
+     *
       * @param t1  the first type
       * @param t2  the second type
       * @return {@code true} if and only if the two types are the same