Cleanup of doclint warnings in java.lang.{annotation, reflect}

[Chris Hegarty]

Looks ok to me.

-Chris.

On 17/06/2013 00:34, Joe Darcy wrote:
> Hello,
>
> Please review the diff below of changes to get java.lang.annotation and
> java.lang.reflect clean on doclint warnings.
>
> I soon plan to send out another patch to cleanup java.lang; I'll file
> one or more bugs to cover this work depending on how reviews come in.
>
> Thanks,
>
> -Joe
>
> diff -r 45a3584bfacf src/share/classes/java/lang/annotation/Annotation.java
> --- a/src/share/classes/java/lang/annotation/Annotation.java Fri Jun 14
> 15:14:56 2013 +0400
> +++ b/src/share/classes/java/lang/annotation/Annotation.java Sun Jun 16
> 16:34:09 2013 -0700
> @@ -1,5 +1,5 @@
> /*
> - * Copyright (c) 2003, 2011, Oracle and/or its affiliates. All rights
> reserved.
> + * Copyright (c) 2003, 2013, Oracle and/or its affiliates. All rights
> reserved.
> * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
> *
> * This code is free software; you can redistribute it and/or modify it
> @@ -126,6 +126,7 @@
>
> /**
> * Returns the annotation type of this annotation.
> + * @return the annotation type of this annotation
> */
> Class<? extends Annotation> annotationType();
> }
> diff -r 45a3584bfacf src/share/classes/java/lang/annotation/Repeatable.java
> --- a/src/share/classes/java/lang/annotation/Repeatable.java Fri Jun 14
> 15:14:56 2013 +0400
> +++ b/src/share/classes/java/lang/annotation/Repeatable.java Sun Jun 16
> 16:34:09 2013 -0700
> @@ -1,5 +1,5 @@
> /*
> - * Copyright (c) 2012, Oracle and/or its affiliates. All rights reserved.
> + * Copyright (c) 2012, 2013, Oracle and/or its affiliates. All rights
> reserved.
> * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
> *
> * This code is free software; you can redistribute it and/or modify it
> @@ -43,6 +43,7 @@
> /**
> * Indicates the <em>containing annotation type</em> for the
> * repeatable annotation type.
> + * @return the containing annotation type
> */
> Class<? extends Annotation> value();
> }
> diff -r 45a3584bfacf src/share/classes/java/lang/annotation/Retention.java
> --- a/src/share/classes/java/lang/annotation/Retention.java Fri Jun 14
> 15:14:56 2013 +0400
> +++ b/src/share/classes/java/lang/annotation/Retention.java Sun Jun 16
> 16:34:09 2013 -0700
> @@ -44,5 +44,9 @@
> @Retention(RetentionPolicy.RUNTIME)
> @Target(ElementType.ANNOTATION_TYPE)
> public @interface Retention {
> + /**
> + * Returns the retention policy.
> + * @return the retention policy
> + */
> RetentionPolicy value();
> }
> diff -r 45a3584bfacf src/share/classes/java/lang/annotation/Target.java
> --- a/src/share/classes/java/lang/annotation/Target.java Fri Jun 14
> 15:14:56 2013 +0400
> +++ b/src/share/classes/java/lang/annotation/Target.java Sun Jun 16
> 16:34:09 2013 -0700
> @@ -67,5 +67,11 @@
> @Retention(RetentionPolicy.RUNTIME)
> @Target(ElementType.ANNOTATION_TYPE)
> public @interface Target {
> + /**
> + * Returns an array of the kinds of elements an annotation type
> + * can be applied to.
> + * @return an array of the kinds of elements an annotation type
> + * can be applied to
> + */
> ElementType[] value();
> }
> diff -r 45a3584bfacf
> src/share/classes/java/lang/reflect/AnnotatedElement.java
> --- a/src/share/classes/java/lang/reflect/AnnotatedElement.java Fri Jun
> 14 15:14:56 2013 +0400
> +++ b/src/share/classes/java/lang/reflect/AnnotatedElement.java Sun Jun
> 16 16:34:09 2013 -0700
> @@ -130,6 +130,7 @@
> * Returns this element's annotation for the specified type if
> * such an annotation is present, else null.
> *
> + * @param <T> the type of the annotation to query for and return if
> present
> * @param annotationClass the Class object corresponding to the
> * annotation type
> * @return this element's annotation for the specified annotation type if
> @@ -154,6 +155,7 @@
> * The caller of this method is free to modify the returned array; it will
> * have no effect on the arrays returned to other callers.
> *
> + * @param <T> the type of the annotation to query for and return if
> present
> * @param annotationClass the Class object corresponding to the
> * annotation type
> * @return all this element's annotations for the specified annotation
> type if
> @@ -184,6 +186,7 @@
> * This method ignores inherited annotations. (Returns null if no
> * annotations are directly present on this element.)
> *
> + * @param <T> the type of the annotation to query for and return if
> present
> * @param annotationClass the Class object corresponding to the
> * annotation type
> * @return this element's annotation for the specified annotation type if
> @@ -209,6 +212,8 @@
> * The caller of this method is free to modify the returned array; it will
> * have no effect on the arrays returned to other callers.
> *
> + * @param <T> the type of the annotation to query for and return
> + * if directly present
> * @param annotationClass the Class object corresponding to the
> * annotation type
> * @return all this element's annotations for the specified annotation
> type if
> diff -r 45a3584bfacf src/share/classes/java/lang/reflect/Executable.java
> --- a/src/share/classes/java/lang/reflect/Executable.java Fri Jun 14
> 15:14:56 2013 +0400
> +++ b/src/share/classes/java/lang/reflect/Executable.java Sun Jun 16
> 16:34:09 2013 -0700
> @@ -384,6 +384,8 @@
> /**
> * Returns a string describing this {@code Executable}, including
> * any type parameters.
> + * @return a string describing this {@code Executable}, including
> + * any type parameters
> */
> public abstract String toGenericString();
>
> @@ -496,6 +498,8 @@
> * If this Executable represents a method, the AnnotatedType object
> * represents the use of a type to specify the return type of the method.
> *
> + * @return an object representing the return type of this method
> + * or constructor
> * @since 1.8
> */
> public abstract AnnotatedType getAnnotatedReturnType();
> @@ -531,6 +535,9 @@
> *
> * Returns null if this Executable represents a static method.
> *
> + * @return an object representing the receiver type of the
> + * method or constructor represented by this Executable
> + *
> * @since 1.8
> */
> public AnnotatedType getAnnotatedReceiverType() {
> @@ -553,6 +560,9 @@
> * Returns an array of length 0 if the method/constructor declares no
> * parameters.
> *
> + * @return an array of objects representing the types of the
> + * formal parameters of this method or constructor
> + *
> * @since 1.8
> */
> public AnnotatedType[] getAnnotatedParameterTypes() {
> @@ -575,6 +585,9 @@
> * Returns an array of length 0 if the method/constructor declares no
> * exceptions.
> *
> + * @return an array of objects representing the declared
> + * exceptions of this method or constructor
> + *
> * @since 1.8
> */
> public AnnotatedType[] getAnnotatedExceptionTypes() {
> diff -r 45a3584bfacf src/share/classes/java/lang/reflect/Field.java
> --- a/src/share/classes/java/lang/reflect/Field.java Fri Jun 14 15:14:56
> 2013 +0400
> +++ b/src/share/classes/java/lang/reflect/Field.java Sun Jun 16 16:34:09
> 2013 -0700
> @@ -1151,7 +1151,9 @@
> /**
> * Returns an AnnotatedType object that represents the use of a type to
> specify
> * the declared type of the field represented by this Field.
> - *
> + * @return an object representing the declared type of the field
> + * represented by this Field
> + *
> * @since 1.8
> */
> public AnnotatedType getAnnotatedType() {
> diff -r 45a3584bfacf src/share/classes/java/lang/reflect/Parameter.java
> --- a/src/share/classes/java/lang/reflect/Parameter.java Fri Jun 14
> 15:14:56 2013 +0400
> +++ b/src/share/classes/java/lang/reflect/Parameter.java Sun Jun 16
> 16:34:09 2013 -0700
> @@ -152,6 +152,8 @@
> * defined in a class file, then that name will be returned by
> * this method. Otherwise, this method will synthesize a name of
> * the form argN, where N is the index of the parameter.
> + *
> + * @return the name of the parameter
> */
> public String getName() {
> // Note: empty strings as paramete names are now outlawed.
> diff -r 45a3584bfacf src/share/classes/java/lang/reflect/TypeVariable.java
> --- a/src/share/classes/java/lang/reflect/TypeVariable.java Fri Jun 14
> 15:14:56 2013 +0400
> +++ b/src/share/classes/java/lang/reflect/TypeVariable.java Sun Jun 16
> 16:34:09 2013 -0700
> @@ -95,6 +95,7 @@
> *
> * Returns an array of length 0 if the type parameter declares no bounds.
> *
> + * @return an array of objects representing the upper bounds of the
> type variable
> * @since 1.8
> */
> AnnotatedType[] getAnnotatedBounds();
>