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

[Joe Darcy]

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();
  }