JDK 9 RFR of 8098790: Improve cross references and wording in java.lang.reflect.AnnotatedFoo type

[joe darcy]

Hello,

Please review the small doc clarification for

     8098790: Improve cross references and wording in 
java.lang.reflect.AnnotatedFoo type
     http://cr.openjdk.java.net/~darcy/8098790.0/

Patch below. In brief, various methods in java.lang.reflect.AnnotatedFoo 
would be clearer if they had @see links to the analogous method in 
java.lang.reflect.Foo. In addition some "Note that..." phrases are 
improperly used since they are normative text rather than just 
informative text.

Thanks,

-Joe

--- 
old/src/java.base/share/classes/java/lang/reflect/AnnotatedArrayType.java 2015-06-15 
17:06:47.895027600 -0700
+++ 
new/src/java.base/share/classes/java/lang/reflect/AnnotatedArrayType.java 2015-06-15 
17:06:47.763027597 -0700
@@ -39,6 +39,7 @@
       * Returns the potentially annotated generic component type of 
this array type.
       *
       * @return the potentially annotated generic component type of 
this array type
+     * @see GenericArrayType#getGenericComponentType()
       */
      AnnotatedType  getAnnotatedGenericComponentType();
  }
--- 
old/src/java.base/share/classes/java/lang/reflect/AnnotatedParameterizedType.java 
2015-06-15 17:06:48.307027613 -0700
+++ 
new/src/java.base/share/classes/java/lang/reflect/AnnotatedParameterizedType.java 
2015-06-15 17:06:48.163027609 -0700
@@ -38,6 +38,7 @@
       * Returns the potentially annotated actual type arguments of this 
parameterized type.
       *
       * @return the potentially annotated actual type arguments of this 
parameterized type
+     * @see ParameterizedType#getActualTypeArguments()
       */
      AnnotatedType[] getAnnotatedActualTypeArguments();
  }
--- 
old/src/java.base/share/classes/java/lang/reflect/AnnotatedTypeVariable.java 
2015-06-15 17:06:48.723027625 -0700
+++ 
new/src/java.base/share/classes/java/lang/reflect/AnnotatedTypeVariable.java 
2015-06-15 17:06:48.583027621 -0700
@@ -36,10 +36,11 @@

      /**
       * Returns the potentially annotated bounds of this type variable.
-     * Note that if no bound is explicitly declared, the bound is 
unannotated
+     * If no bound is explicitly declared, the bound is unannotated
       * {@code Object}.
       *
       * @return the potentially annotated bounds of this type variable
+     * @see TypeVariable#getBounds()
       */
      AnnotatedType[] getAnnotatedBounds();
  }
--- 
old/src/java.base/share/classes/java/lang/reflect/AnnotatedWildcardType.java 
2015-06-15 17:06:49.131027638 -0700
+++ 
new/src/java.base/share/classes/java/lang/reflect/AnnotatedWildcardType.java 
2015-06-15 17:06:48.995027634 -0700
@@ -36,20 +36,22 @@

      /**
       * Returns the potentially annotated lower bounds of this wildcard 
type.
-     * Note that if no lower bound is explicitly declared, the lower 
bound is the
+     * If no lower bound is explicitly declared, the lower bound is the
       * type of null. In this case, a zero length array is returned.
       *
       * @return the potentially annotated lower bounds of this wildcard 
type or
       * an empty array if no lower bound is explicitly declared.
+     * @see WildcardType#getLowerBounds()
       */
      AnnotatedType[] getAnnotatedLowerBounds();

      /**
       * Returns the potentially annotated upper bounds of this wildcard 
type.
-     * Note that if no upper bound is explicitly declared, the upper 
bound is
+     * If no upper bound is explicitly declared, the upper bound is
       * unannotated {@code Object}
       *
       * @return the potentially annotated upper bounds of this wildcard 
type
+     * @see WildcardType#getUpperBounds()
       */
      AnnotatedType[] getAnnotatedUpperBounds();
  }
--- old/src/java.base/share/classes/java/lang/reflect/TypeVariable.java 
2015-06-15 17:06:49.535027650 -0700
+++ new/src/java.base/share/classes/java/lang/reflect/TypeVariable.java 
2015-06-15 17:06:49.399027646 -0700
@@ -51,7 +51,7 @@
  public interface TypeVariable<D extends GenericDeclaration> extends 
Type, AnnotatedElement {
      /**
       * Returns an array of {@code Type} objects representing the
-     * upper bound(s) of this type variable.  Note that if no upper 
bound is
+     * upper bound(s) of this type variable.  If no upper bound is
       * explicitly declared, the upper bound is {@code Object}.
       *
       * <p>For each upper bound B: <ul> <li>if B is a parameterized
@@ -67,7 +67,7 @@
       *     for any reason
       * @return an array of {@code Type}s representing the upper
       *     bound(s) of this type variable
-    */
+     */
      Type[] getBounds();

      /**
--- old/src/java.base/share/classes/java/lang/reflect/WildcardType.java 
2015-06-15 17:06:49.959027663 -0700
+++ new/src/java.base/share/classes/java/lang/reflect/WildcardType.java 
2015-06-15 17:06:49.819027659 -0700
@@ -1,5 +1,5 @@
  /*
- * Copyright (c) 2003, 2004, Oracle and/or its affiliates. All rights 
reserved.
+ * Copyright (c) 2003, 2015, Oracle and/or its affiliates. All rights 
reserved.
   * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   *
   * This code is free software; you can redistribute it and/or modify it
@@ -34,7 +34,7 @@
  public interface WildcardType extends Type {
      /**
       * Returns an array of {@code Type} objects representing the upper
-     * bound(s) of this type variable.  Note that if no upper bound is
+     * bound(s) of this type variable.  If no upper bound is
       * explicitly declared, the upper bound is {@code Object}.
       *
       * <p>For each upper bound B :
@@ -57,7 +57,7 @@

      /**
       * Returns an array of {@code Type} objects representing the
-     * lower bound(s) of this type variable.  Note that if no lower 
bound is
+     * lower bound(s) of this type variable.  If no lower bound is
       * explicitly declared, the lower bound is the type of {@code null}.
       * In this case, a zero length array is returned.
       *