RFR of JDK-8245620: Improve Annotation.annotationType() documentation

[Pavel Rappo]

Looks good.

> On 11 Jun 2020, at 18:11, Joe Darcy <joe.darcy at oracle.com> wrote:
> 
> Hi Pavel,
> 
> On 6/11/2020 2:54 AM, Pavel Rappo wrote:
>> Joe,
>> 
>> There is a typo:
>> 
>> *    appropriate overloading of {@link java.util.Arrays#equals Arrays.hashCode}.
>> ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~^  ~~~~~~~~~~~^
>> 
>> Since we are in this area, is it possible to rephrase (or at least re-punctuate) the doc comment for java.lang.annotation.Annotation#hashCode? The reason is that it uses way too many successive colons:
> 
> Good catch.
> 
> Revised patch below will fix this issue, remove several of the colons, and use @apiNote as Alan suggested.
> 
> Thanks,
> 
> -Joe
> 
> diff -r 16081904714f src/java.base/share/classes/java/lang/annotation/Annotation.java
> --- a/src/java.base/share/classes/java/lang/annotation/Annotation.java Thu Jun 11 18:08:29 2020 +0200
> +++ b/src/java.base/share/classes/java/lang/annotation/Annotation.java Thu Jun 11 10:09:04 2020 -0700
> @@ -31,7 +31,7 @@
>   * an annotation type.  Also note that this interface does not itself
>   * define an annotation type.
>   *
> - * More information about annotation types can be found in section 9.6 of
> + * More information about annotation types can be found in section {@jls 9.6} of
>   * <cite>The Java™ Language Specification</cite>.
>   *
>   * The {@link java.lang.reflect.AnnotatedElement} interface discusses
> @@ -72,7 +72,7 @@
>       *
>       *    <li>Two corresponding array typed members {@code x} and {@code y}
>       *    are considered equal if {@code Arrays.equals(x, y)}, for the
> -     *    appropriate overloading of {@link java.util.Arrays#equals}.
> +     *    appropriate overloading of {@link java.util.Arrays#equals Arrays.equals}.
>       * </ul>
>       *
>       * @return true if the specified object represents an annotation
> @@ -81,17 +81,15 @@
>      boolean equals(Object obj);
> 
>      /**
> -     * Returns the hash code of this annotation, as defined below:
> +     * Returns the hash code of this annotation.
>       *
>       * <p>The hash code of an annotation is the sum of the hash codes
> -     * of its members (including those with default values), as defined
> -     * below:
> +     * of its members (including those with default values).
>       *
>       * The hash code of an annotation member is (127 times the hash code
>       * of the member-name as computed by {@link String#hashCode()}) XOR
> -     * the hash code of the member-value, as defined below:
> -     *
> -     * <p>The hash code of a member-value depends on its type:
> +     * the hash code of the member-value.
> +     * The hash code of a member-value depends on its type as defined below:
>       * <ul>
>       * <li>The hash code of a primitive value <i>{@code v}</i> is equal to
>       * <code><i>WrapperType</i>.valueOf(<i>v</i>).hashCode()</code>, where
> @@ -121,7 +119,7 @@
>       * of the representation are implementation-dependent, but the following
>       * may be regarded as typical:
>       * <pre>
> -     *   @com.acme.util.Name(first=Alfred, middle=E., last=Neuman)
> +     *   @com.example.Name(first="Duke", middle="of", last="Java")
>       * </pre>
>       *
>       * @return a string representation of this annotation
> @@ -130,7 +128,15 @@
> 
>      /**
>       * Returns the annotation type of this annotation.
> +     *
> +     * @apiNote Implementation-dependent classes are used to provide
> +     * the implementations of annotations. Therefore, calling {@link
> +     * #getClass getClass} on an annotation will return an
> +     * implementation-dependent class. In contrast, this method will
> +     * reliably return the annotation type of the annotation.
> +     *
>       * @return the annotation type of this annotation
> +     * @see Enum#getDeclaringClass
>       */
>      Class<? extends Annotation> annotationType();
>  }
>