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

[Pavel Rappo]

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:


 ! Returns the hash code of this annotation, as defined below:
 *
 * <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:
 *
 * 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:

This also makes the method summary look weird on the HTML page.

-Pavel

> On 11 Jun 2020, at 06:26, Joe Darcy <joe.darcy at oracle.com> wrote:
> 
> Hello,
> 
> Please review a number of small updates to the javadoc of java.lang.annotation.Annotation to address
> 
>     JDK-8245620: Improve Annotation.annotationType() documentation
> 
> The use of  Annotation.annotationType() vs calling getClass on an annotation object may not be clear so the method's javadoc is augmented to explain this situation. java.lang.Enum defines an analogous method which always returns the enum class of an enum object.
> 
> There are a number of other small improvements, including updating the example toString output to account for
> 
>     8162817: Annotation toString output not reusable for source input
> 
> Patch below; thanks,
> 
> -Joe
> 
> diff -r 2f75432d7eb3 src/java.base/share/classes/java/lang/annotation/Annotation.java
> --- a/src/java.base/share/classes/java/lang/annotation/Annotation.java Wed Jun 10 18:18:30 2020 -0400
> +++ b/src/java.base/share/classes/java/lang/annotation/Annotation.java Wed Jun 10 22:24:55 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.hashCode}.
>       * </ul>
>       *
>       * @return true if the specified object represents an annotation
> @@ -121,7 +121,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 +130,15 @@
> 
>      /**
>       * Returns the annotation type of this annotation.
> +     *
> +     * Note that 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();
>  }
>