8017550: Fix doclint issues in java.lang and subpackages

Reviewed-by: alanb, chegar

src/share/classes/java/lang/Boolean.java

 /*
- * Copyright (c) 1994, 2011, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1994, 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
@@ -205,9 +205,9 @@ public final class Boolean implements java.io.Serializable,
      * Returns a hash code for a {@code boolean} value; compatible with
      * {@code Boolean.hashCode()}.
      *
-     * @since 1.8
-     *
+     * @param value the value to hash
      * @return a hash code value for a {@code boolean} value.
+     * @since 1.8
      */
     public static int hashCode(boolean value) {
         return value ? 1231 : 1237;

src/share/classes/java/lang/Byte.java

 /*
- * Copyright (c) 1996, 2012, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1996, 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
@@ -398,9 +398,9 @@ public final class Byte extends Number implements Comparable<Byte> {
      * Returns a hash code for a {@code byte} value; compatible with
      * {@code Byte.hashCode()}.
      *
-     * @since 1.8
-     *
+     * @param value the value to hash
      * @return a hash code value for a {@code byte} value.
+     * @since 1.8
      */
     public static int hashCode(byte value) {
         return (int)value;

src/share/classes/java/lang/Class.java

@@ -3250,6 +3250,8 @@ public final class Class<T> implements java.io.Serializable,
      * could not be checked at runtime (because generic types are implemented
      * by erasure).
      *
+     * @param <U> the type to cast this class object to
+     * @param clazz the class of the type to cast this class object to
      * @return this {@code Class} object, cast to represent a subclass of
      *    the specified class object.
      * @throws ClassCastException if this {@code Class} object does not
@@ -3405,6 +3407,7 @@ public final class Class<T> implements java.io.Serializable,
      * If this Class represents either the Object class, an interface type, an
      * array type, a primitive type, or void, the return value is null.
      *
+     * @return an object representing the superclass
      * @since 1.8
      */
     public AnnotatedType getAnnotatedSuperclass() {
@@ -3436,6 +3439,7 @@ public final class Class<T> implements java.io.Serializable,
      * If this Class represents either the Object class, an array type, a
      * primitive type, or void, the return value is an array of length 0.
      *
+     * @return an array representing the superinterfaces
      * @since 1.8
      */
     public AnnotatedType[] getAnnotatedInterfaces() {

src/share/classes/java/lang/Double.java

@@ -453,8 +453,7 @@ public final class Double extends Number implements Comparable<Double> {
      * a {@code NumberFormatException} be thrown, the regular
      * expression below can be used to screen the input string:
      *
-     * <code>
-     * <pre>
+     * <pre>{@code
      *  final String Digits     = "(\\p{Digit}+)";
      *  final String HexDigits  = "(\\p{XDigit}+)";
      *  // an exponent is 'e' or 'E' followed by an optionally
@@ -474,7 +473,7 @@ public final class Double extends Number implements Comparable<Double> {
      *       // in addition to strings of floating-point literals, the
      *       // two sub-patterns below are simplifications of the grammar
      *       // productions from section 3.10.2 of
-     *       // <cite>The Java&trade; Language Specification</cite>.
+     *       // The Java Language Specification.
      *
      *       // Digits ._opt Digits_opt ExponentPart_opt FloatTypeSuffix_opt
      *       "((("+Digits+"(\\.)?("+Digits+"?)("+Exp+")?)|"+
@@ -499,8 +498,7 @@ public final class Double extends Number implements Comparable<Double> {
      *  else {
      *      // Perform suitable alternative action
      *  }
-     * </pre>
-     * </code>
+     * }</pre>
      *
      * @param      s   the string to be parsed.
      * @return     a {@code Double} object holding the value
@@ -756,9 +754,9 @@ public final class Double extends Number implements Comparable<Double> {
      * Returns a hash code for a {@code double} value; compatible with
      * {@code Double.hashCode()}.
      *
-     * @since 1.8
-     *
+     * @param value the value to hash
      * @return a hash code value for a {@code double} value.
+     * @since 1.8
      */
     public static int hashCode(double value) {
         long bits = doubleToLongBits(value);

src/share/classes/java/lang/Float.java

@@ -664,9 +664,9 @@ public final class Float extends Number implements Comparable<Float> {
      * Returns a hash code for a {@code float} value; compatible with
      * {@code Float.hashCode()}.
      *
-     * @since 1.8
-     *
+     * @param value the value to hash
      * @return a hash code value for a {@code float} value.
+     * @since 1.8
      */
     public static int hashCode(float value) {
         return floatToIntBits(value);

src/share/classes/java/lang/Integer.java

@@ -951,6 +951,7 @@ public final class Integer extends Number implements Comparable<Integer> {
      * Returns a hash code for a {@code int} value; compatible with
      * {@code Integer.hashCode()}.
      *
+     * @param value the value to hash
      * @since 1.8
      *
      * @return a hash code value for a {@code int} value.
@@ -1336,6 +1337,7 @@ public final class Integer extends Number implements Comparable<Integer> {
      * one-bits in its two's complement binary representation, that is, if it
      * is equal to zero.
      *
+     * @param i the value whose highest one bit is to be computed
      * @return an {@code int} value with a single one-bit, in the position
      *     of the highest-order one-bit in the specified value, or zero if
      *     the specified value is itself equal to zero.
@@ -1358,6 +1360,7 @@ public final class Integer extends Number implements Comparable<Integer> {
      * one-bits in its two's complement binary representation, that is, if it
      * is equal to zero.
      *
+     * @param i the value whose lowest one bit is to be computed
      * @return an {@code int} value with a single one-bit, in the position
      *     of the lowest-order one-bit in the specified value, or zero if
      *     the specified value is itself equal to zero.
@@ -1382,6 +1385,7 @@ public final class Integer extends Number implements Comparable<Integer> {
      * <li>ceil(log<sub>2</sub>(x)) = {@code 32 - numberOfLeadingZeros(x - 1)}
      * </ul>
      *
+     * @param i the value whose number of leading zeros is to be computed
      * @return the number of zero bits preceding the highest-order
      *     ("leftmost") one-bit in the two's complement binary representation
      *     of the specified {@code int} value, or 32 if the value
@@ -1408,6 +1412,7 @@ public final class Integer extends Number implements Comparable<Integer> {
      * one-bits in its two's complement representation, in other words if it is
      * equal to zero.
      *
+     * @param i the value whose number of trailing zeros is to be computed
      * @return the number of zero bits following the lowest-order ("rightmost")
      *     one-bit in the two's complement binary representation of the
      *     specified {@code int} value, or 32 if the value is equal
@@ -1431,6 +1436,7 @@ public final class Integer extends Number implements Comparable<Integer> {
      * representation of the specified {@code int} value.  This function is
      * sometimes referred to as the <i>population count</i>.
      *
+     * @param i the value whose bits are to be counted
      * @return the number of one-bits in the two's complement binary
      *     representation of the specified {@code int} value.
      * @since 1.5
@@ -1458,6 +1464,8 @@ public final class Integer extends Number implements Comparable<Integer> {
      * ignored, even if the distance is negative: {@code rotateLeft(val,
      * distance) == rotateLeft(val, distance & 0x1F)}.
      *
+     * @param i the value whose bits are to be rotated left
+     * @param distance the number of bit positions to rotate left
      * @return the value obtained by rotating the two's complement binary
      *     representation of the specified {@code int} value left by the
      *     specified number of bits.
@@ -1480,6 +1488,8 @@ public final class Integer extends Number implements Comparable<Integer> {
      * ignored, even if the distance is negative: {@code rotateRight(val,
      * distance) == rotateRight(val, distance & 0x1F)}.
      *
+     * @param i the value whose bits are to be rotated right
+     * @param distance the number of bit positions to rotate right
      * @return the value obtained by rotating the two's complement binary
      *     representation of the specified {@code int} value right by the
      *     specified number of bits.
@@ -1494,6 +1504,7 @@ public final class Integer extends Number implements Comparable<Integer> {
      * two's complement binary representation of the specified {@code int}
      * value.
      *
+     * @param i the value to be reversed
      * @return the value obtained by reversing order of the bits in the
      *     specified {@code int} value.
      * @since 1.5
@@ -1513,6 +1524,7 @@ public final class Integer extends Number implements Comparable<Integer> {
      * return value is -1 if the specified value is negative; 0 if the
      * specified value is zero; and 1 if the specified value is positive.)
      *
+     * @param i the value whose signum is to be computed
      * @return the signum function of the specified {@code int} value.
      * @since 1.5
      */
@@ -1525,6 +1537,7 @@ public final class Integer extends Number implements Comparable<Integer> {
      * Returns the value obtained by reversing the order of the bytes in the
      * two's complement representation of the specified {@code int} value.
      *
+     * @param i the value whose bytes are to be reversed
      * @return the value obtained by reversing the bytes in the specified
      *     {@code int} value.
      * @since 1.5

src/share/classes/java/lang/Long.java

@@ -1053,9 +1053,9 @@ public final class Long extends Number implements Comparable<Long> {
      * Returns a hash code for a {@code long} value; compatible with
      * {@code Long.hashCode()}.
      *
-     * @since 1.8
-     *
+     * @param value the value to hash
      * @return a hash code value for a {@code long} value.
+     * @since 1.8
      */
     public static int hashCode(long value) {
         return (int)(value ^ (value >>> 32));
@@ -1357,6 +1357,7 @@ public final class Long extends Number implements Comparable<Long> {
      * one-bits in its two's complement binary representation, that is, if it
      * is equal to zero.
      *
+     * @param i the value whose highest one bit is to be computed
      * @return a {@code long} value with a single one-bit, in the position
      *     of the highest-order one-bit in the specified value, or zero if
      *     the specified value is itself equal to zero.
@@ -1380,6 +1381,7 @@ public final class Long extends Number implements Comparable<Long> {
      * one-bits in its two's complement binary representation, that is, if it
      * is equal to zero.
      *
+     * @param i the value whose lowest one bit is to be computed
      * @return a {@code long} value with a single one-bit, in the position
      *     of the lowest-order one-bit in the specified value, or zero if
      *     the specified value is itself equal to zero.
@@ -1404,6 +1406,7 @@ public final class Long extends Number implements Comparable<Long> {
      * <li>ceil(log<sub>2</sub>(x)) = {@code 64 - numberOfLeadingZeros(x - 1)}
      * </ul>
      *
+     * @param i the value whose number of leading zeros is to be computed
      * @return the number of zero bits preceding the highest-order
      *     ("leftmost") one-bit in the two's complement binary representation
      *     of the specified {@code long} value, or 64 if the value
@@ -1432,6 +1435,7 @@ public final class Long extends Number implements Comparable<Long> {
      * one-bits in its two's complement representation, in other words if it is
      * equal to zero.
      *
+     * @param i the value whose number of trailing zeros is to be computed
      * @return the number of zero bits following the lowest-order ("rightmost")
      *     one-bit in the two's complement binary representation of the
      *     specified {@code long} value, or 64 if the value is equal
@@ -1456,6 +1460,7 @@ public final class Long extends Number implements Comparable<Long> {
      * representation of the specified {@code long} value.  This function is
      * sometimes referred to as the <i>population count</i>.
      *
+     * @param i the value whose bits are to be counted
      * @return the number of one-bits in the two's complement binary
      *     representation of the specified {@code long} value.
      * @since 1.5
@@ -1484,6 +1489,8 @@ public final class Long extends Number implements Comparable<Long> {
      * ignored, even if the distance is negative: {@code rotateLeft(val,
      * distance) == rotateLeft(val, distance & 0x3F)}.
      *
+     * @param i the value whose bits are to be rotated left
+     * @param distance the number of bit positions to rotate left
      * @return the value obtained by rotating the two's complement binary
      *     representation of the specified {@code long} value left by the
      *     specified number of bits.
@@ -1506,6 +1513,8 @@ public final class Long extends Number implements Comparable<Long> {
      * ignored, even if the distance is negative: {@code rotateRight(val,
      * distance) == rotateRight(val, distance & 0x3F)}.
      *
+     * @param i the value whose bits are to be rotated right
+     * @param distance the number of bit positions to rotate right
      * @return the value obtained by rotating the two's complement binary
      *     representation of the specified {@code long} value right by the
      *     specified number of bits.
@@ -1520,6 +1529,7 @@ public final class Long extends Number implements Comparable<Long> {
      * two's complement binary representation of the specified {@code long}
      * value.
      *
+     * @param i the value to be reversed
      * @return the value obtained by reversing order of the bits in the
      *     specified {@code long} value.
      * @since 1.5
@@ -1540,6 +1550,7 @@ public final class Long extends Number implements Comparable<Long> {
      * return value is -1 if the specified value is negative; 0 if the
      * specified value is zero; and 1 if the specified value is positive.)
      *
+     * @param i the value whose signum is to be computed
      * @return the signum function of the specified {@code long} value.
      * @since 1.5
      */
@@ -1552,6 +1563,7 @@ public final class Long extends Number implements Comparable<Long> {
      * Returns the value obtained by reversing the order of the bytes in the
      * two's complement representation of the specified {@code long} value.
      *
+     * @param i the value whose bytes are to be reversed
      * @return the value obtained by reversing the bytes in the specified
      *     {@code long} value.
      * @since 1.5

src/share/classes/java/lang/Package.java

@@ -77,18 +77,18 @@ import java.lang.annotation.Annotation;
  * by the following formal grammar:
  * <blockquote>
  * <dl>
- * <dt><i>SpecificationVersion:
- * <dd>Digits RefinedVersion<sub>opt</sub></i>
+ * <dt><i>SpecificationVersion:</i>
+ * <dd><i>Digits RefinedVersion<sub>opt</sub></i>
 
- * <p><dt><i>RefinedVersion:</i>
+ * <dt><i>RefinedVersion:</i>
  * <dd>{@code .} <i>Digits</i>
  * <dd>{@code .} <i>Digits RefinedVersion</i>
  *
- * <p><dt><i>Digits:
- * <dd>Digit
- * <dd>Digits</i>
+ * <dt><i>Digits:</i>
+ * <dd><i>Digit</i>
+ * <dd><i>Digits</i>
  *
- * <p><dt><i>Digit:</i>
+ * <dt><i>Digit:</i>
  * <dd>any character for which {@link Character#isDigit} returns {@code true},
  * e.g. 0, 1, 2, ...
  * </dl>

src/share/classes/java/lang/Runtime.java

@@ -117,11 +117,11 @@ public class Runtime {
      *
      *   <ul>
      *
-     *   <p> <li> The program <i>exits</i> normally, when the last non-daemon
+     *   <li> The program <i>exits</i> normally, when the last non-daemon
      *   thread exits or when the <tt>{@link #exit exit}</tt> (equivalently,
-     *   <tt>{@link System#exit(int) System.exit}</tt>) method is invoked, or
+     *   {@link System#exit(int) System.exit}) method is invoked, or
      *
-     *   <p> <li> The virtual machine is <i>terminated</i> in response to a
+     *   <li> The virtual machine is <i>terminated</i> in response to a
      *   user interrupt, such as typing <tt>^C</tt>, or a system-wide event,
      *   such as user logoff or system shutdown.
      *

src/share/classes/java/lang/Short.java

 /*
- * Copyright (c) 1996, 2012, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1996, 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
@@ -403,9 +403,9 @@ public final class Short extends Number implements Comparable<Short> {
      * Returns a hash code for a {@code short} value; compatible with
      * {@code Short.hashCode()}.
      *
-     * @since 1.8
-     *
+     * @param value the value to hash
      * @return a hash code value for a {@code short} value.
+     * @since 1.8
      */
     public static int hashCode(short value) {
         return (int)value;
@@ -482,6 +482,7 @@ public final class Short extends Number implements Comparable<Short> {
      * Returns the value obtained by reversing the order of the bytes in the
      * two's complement representation of the specified {@code short} value.
      *
+     * @param i the value whose bytes are to be reversed
      * @return the value obtained by reversing (or, equivalently, swapping)
      *     the bytes in the specified {@code short} value.
      * @since 1.5

src/share/classes/java/lang/StrictMath.java

 /*
- * Copyright (c) 1999, 2012, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1999, 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
@@ -1419,6 +1419,7 @@ public final class StrictMath {
      * {@link Float#MIN_EXPONENT} -1.
      * </ul>
      * @param f a {@code float} value
+     * @return the unbiased exponent of the argument
      * @since 1.6
      */
     public static int getExponent(float f) {
@@ -1436,6 +1437,7 @@ public final class StrictMath {
      * {@link Double#MIN_EXPONENT} -1.
      * </ul>
      * @param d a {@code double} value
+     * @return the unbiased exponent of the argument
      * @since 1.6
      */
     public static int getExponent(double d) {

src/share/classes/java/lang/SuppressWarnings.java

@@ -66,6 +66,7 @@ public @interface SuppressWarnings {
      * additional warning names they support in conjunction with this
      * annotation type. They are encouraged to cooperate to ensure
      * that the same names work across multiple compilers.
+     * @return the set of warnings to be suppressed
      */
     String[] value();
 }

src/share/classes/java/lang/System.java

@@ -634,6 +634,8 @@ public final class System {
      *
      * <p>On UNIX systems, it returns {@code "\n"}; on Microsoft
      * Windows systems it returns {@code "\r\n"}.
+     *
+     * @return the system-dependent line separator string
      * @since 1.7
      */
     public static String lineSeparator() {

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

 /*
- * 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 @@ public interface Annotation {
 
     /**
      * Returns the annotation type of this annotation.
+     * @return the annotation type of this annotation
      */
     Class<? extends Annotation> annotationType();
 }

src/share/classes/java/lang/annotation/Repeatable.java

 /*
- * 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 @@ public @interface Repeatable {
     /**
      * Indicates the <em>containing annotation type</em> for the
      * repeatable annotation type.
+     * @return the containing annotation type
      */
     Class<? extends Annotation> value();
 }

src/share/classes/java/lang/annotation/Retention.java

@@ -44,5 +44,9 @@ package java.lang.annotation;
 @Retention(RetentionPolicy.RUNTIME)
 @Target(ElementType.ANNOTATION_TYPE)
 public @interface Retention {
+    /**
+     * Returns the retention policy.
+     * @return the retention policy
+     */
     RetentionPolicy value();
 }

src/share/classes/java/lang/annotation/Target.java

@@ -67,5 +67,11 @@ package java.lang.annotation;
 @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();
 }

src/share/classes/java/lang/reflect/AnnotatedElement.java

@@ -130,6 +130,7 @@ public interface AnnotatedElement {
      * 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 @@ public interface AnnotatedElement {
      * 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 @@ public interface AnnotatedElement {
      * 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 @@ public interface AnnotatedElement {
      * 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

src/share/classes/java/lang/reflect/Executable.java

@@ -384,6 +384,8 @@ public abstract class Executable extends AccessibleObject
     /**
      * 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 @@ public abstract class Executable extends AccessibleObject
      * 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 @@ public abstract class Executable extends AccessibleObject
      *
      * 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 @@ public abstract class Executable extends AccessibleObject
      * 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 @@ public abstract class Executable extends AccessibleObject
      * 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() {

src/share/classes/java/lang/reflect/Field.java

@@ -1151,6 +1151,8 @@ class Field extends AccessibleObject implements Member {
     /**
      * 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
      */

src/share/classes/java/lang/reflect/Parameter.java

@@ -152,6 +152,8 @@ public final class Parameter implements AnnotatedElement {
      * 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.

src/share/classes/java/lang/reflect/TypeVariable.java

@@ -95,6 +95,7 @@ public interface TypeVariable<D extends GenericDeclaration> extends Type, Annota
      *
      * 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();