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

[Joe Darcy]

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