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

[Lance @ Oracle]

Looks fine Joe 


Lance Andersen| Principal Member of Technical Staff | +1.781.442.2037
Oracle Java Engineering 
1 Network Drive
Burlington, MA 01803
Lance.Andersen at oracle.com
Sent from my iPad

> On Jun 15, 2015, at 8:12 PM, joe darcy <joe.darcy at oracle.com> wrote:
> 
> 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.
>      *
>