8245620: Improve Annotation.annotationType() documentation

Reviewed-by: alanb, prappo

Author: jddarcy

src/java.base/share/classes/java/lang/annotation/Annotation.java

@@ -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&trade; Language Specification</cite>.
  *
  * The {@link java.lang.reflect.AnnotatedElement} interface discusses
@@ -72,7 +72,7 @@ public interface Annotation {
      *
      *    <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 @@ public interface Annotation {
     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 @@ public interface Annotation {
      * of the representation are implementation-dependent, but the following
      * may be regarded as typical:
      * <pre>
-     *   &#064;com.acme.util.Name(first=Alfred, middle=E., last=Neuman)
+     *   &#064;com.example.Name(first="Duke", middle="of", last="Java")
      * </pre>
      *
      * @return a string representation of this annotation
@@ -130,7 +128,15 @@ public interface Annotation {
 
     /**
      * Returns the annotation type of this annotation.
+     *
+     * @apiNote Implementation-dependent classes are used to provide
+     * the implementations of annotations. Therefore, calling {@link
+     * Object#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();
 }