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 <[email protected]> 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();
> }
>
