Cleanup of some doclint warnings in java.lang

Chris Hegarty chris.hegarty at oracle.com
Mon Jun 17 12:43:42 UTC 2013


Looks fine to me Joe,

Quite trivially, and optionally, the '@since 1.8 ' could be moved to 
after the @return in Short.java L406

-Chris.

On 17/06/2013 04:48, Joe Darcy wrote:
> Hello,
>
> Please review the patch below which resolves a subset of the doclint
> warnings in java.lang.
>
> Thanks,
>
> -Joe
>
> diff -r 45a3584bfacf src/share/classes/java/lang/Boolean.java
> --- a/src/share/classes/java/lang/Boolean.java Fri Jun 14 15:14:56 2013
> +0400
> +++ b/src/share/classes/java/lang/Boolean.java Sun Jun 16 20:46:52 2013
> -0700
> @@ -1,5 +1,5 @@
> /*
> - * 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 @@
> * Returns a hash code for a {@code boolean} value; compatible with
> * {@code Boolean.hashCode()}.
> *
> + * @param value the value to hash
> + * @return a hash code value for a {@code boolean} value.
> * @since 1.8
> - *
> - * @return a hash code value for a {@code boolean} value.
> */
> public static int hashCode(boolean value) {
> return value ? 1231 : 1237;
> diff -r 45a3584bfacf src/share/classes/java/lang/Byte.java
> --- a/src/share/classes/java/lang/Byte.java Fri Jun 14 15:14:56 2013 +0400
> +++ b/src/share/classes/java/lang/Byte.java Sun Jun 16 20:46:52 2013 -0700
> @@ -1,5 +1,5 @@
> /*
> - * 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 @@
> * Returns a hash code for a {@code byte} value; compatible with
> * {@code Byte.hashCode()}.
> *
> + * @param value the value to hash
> + * @return a hash code value for a {@code byte} value.
> * @since 1.8
> - *
> - * @return a hash code value for a {@code byte} value.
> */
> public static int hashCode(byte value) {
> return (int)value;
> diff -r 45a3584bfacf src/share/classes/java/lang/Class.java
> --- a/src/share/classes/java/lang/Class.java Fri Jun 14 15:14:56 2013 +0400
> +++ b/src/share/classes/java/lang/Class.java Sun Jun 16 20:46:52 2013 -0700
> @@ -3141,6 +3141,8 @@
> * 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
> @@ -3296,6 +3298,7 @@
> * 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() {
> @@ -3327,6 +3330,7 @@
> * 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() {
> diff -r 45a3584bfacf src/share/classes/java/lang/Double.java
> --- a/src/share/classes/java/lang/Double.java Fri Jun 14 15:14:56 2013
> +0400
> +++ b/src/share/classes/java/lang/Double.java Sun Jun 16 20:46:52 2013
> -0700
> @@ -453,7 +453,6 @@
> * a {@code NumberFormatException} be thrown, the regular
> * expression below can be used to screen the input string:
> *
> - * <code>
> * <pre>
> * final String Digits = "(\\p{Digit}+)";
> * final String HexDigits = "(\\p{XDigit}+)";
> @@ -500,7 +499,6 @@
> * // Perform suitable alternative action
> * }
> * </pre>
> - * </code>
> *
> * @param s the string to be parsed.
> * @return a {@code Double} object holding the value
> @@ -756,9 +754,9 @@
> * Returns a hash code for a {@code double} value; compatible with
> * {@code Double.hashCode()}.
> *
> + * @param value the value to hash
> + * @return a hash code value for a {@code double} value.
> * @since 1.8
> - *
> - * @return a hash code value for a {@code double} value.
> */
> public static int hashCode(double value) {
> long bits = doubleToLongBits(value);
> diff -r 45a3584bfacf src/share/classes/java/lang/Float.java
> --- a/src/share/classes/java/lang/Float.java Fri Jun 14 15:14:56 2013 +0400
> +++ b/src/share/classes/java/lang/Float.java Sun Jun 16 20:46:52 2013 -0700
> @@ -664,9 +664,9 @@
> * Returns a hash code for a {@code float} value; compatible with
> * {@code Float.hashCode()}.
> *
> + * @param value the value to hash
> + * @return a hash code value for a {@code float} value.
> * @since 1.8
> - *
> - * @return a hash code value for a {@code float} value.
> */
> public static int hashCode(float value) {
> return floatToIntBits(value);
> diff -r 45a3584bfacf src/share/classes/java/lang/Integer.java
> --- a/src/share/classes/java/lang/Integer.java Fri Jun 14 15:14:56 2013
> +0400
> +++ b/src/share/classes/java/lang/Integer.java Sun Jun 16 20:46:52 2013
> -0700
> @@ -947,6 +947,7 @@
> * 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.
> @@ -1332,6 +1333,7 @@
> * 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.
> @@ -1354,6 +1356,7 @@
> * 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.
> @@ -1378,6 +1381,7 @@
> * <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
> @@ -1404,6 +1408,7 @@
> * 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
> @@ -1427,6 +1432,7 @@
> * 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
> @@ -1454,6 +1460,8 @@
> * 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.
> @@ -1476,6 +1484,8 @@
> * 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.
> @@ -1490,6 +1500,7 @@
> * 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
> @@ -1509,6 +1520,7 @@
> * 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
> */
> @@ -1521,6 +1533,7 @@
> * 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
> diff -r 45a3584bfacf src/share/classes/java/lang/Long.java
> --- a/src/share/classes/java/lang/Long.java Fri Jun 14 15:14:56 2013 +0400
> +++ b/src/share/classes/java/lang/Long.java Sun Jun 16 20:46:52 2013 -0700
> @@ -1053,9 +1053,9 @@
> * Returns a hash code for a {@code long} value; compatible with
> * {@code Long.hashCode()}.
> *
> + * @param value the value to hash
> + * @return a hash code value for a {@code long} value.
> * @since 1.8
> - *
> - * @return a hash code value for a {@code long} value.
> */
> public static int hashCode(long value) {
> return (int)(value ^ (value >>> 32));
> @@ -1357,6 +1357,7 @@
> * 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 @@
> * 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 @@
> * <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 @@
> * 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 @@
> * 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 @@
> * 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 @@
> * 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 @@
> * 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 @@
> * 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 @@
> * 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
> diff -r 45a3584bfacf src/share/classes/java/lang/Math.java
> --- a/src/share/classes/java/lang/Math.java Fri Jun 14 15:14:56 2013 +0400
> +++ b/src/share/classes/java/lang/Math.java Sun Jun 16 20:46:52 2013 -0700
> @@ -1,5 +1,5 @@
> /*
> - * Copyright (c) 1994, 2012, 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
> diff -r 45a3584bfacf src/share/classes/java/lang/Package.java
> --- a/src/share/classes/java/lang/Package.java Fri Jun 14 15:14:56 2013
> +0400
> +++ b/src/share/classes/java/lang/Package.java Sun Jun 16 20:46:52 2013
> -0700
> @@ -77,18 +77,18 @@
> * 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>
> diff -r 45a3584bfacf src/share/classes/java/lang/Runtime.java
> --- a/src/share/classes/java/lang/Runtime.java Fri Jun 14 15:14:56 2013
> +0400
> +++ b/src/share/classes/java/lang/Runtime.java Sun Jun 16 20:46:52 2013
> -0700
> @@ -117,11 +117,11 @@
> *
> * <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
> + * {<tt>{@link System#exit(int) System.exit}</tt>) 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.
> *
> diff -r 45a3584bfacf src/share/classes/java/lang/Short.java
> --- a/src/share/classes/java/lang/Short.java Fri Jun 14 15:14:56 2013 +0400
> +++ b/src/share/classes/java/lang/Short.java Sun Jun 16 20:46:52 2013 -0700
> @@ -1,5 +1,5 @@
> /*
> - * 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
> @@ -405,6 +405,7 @@
> *
> * @since 1.8
> *
> + * @param value the value to hash
> * @return a hash code value for a {@code short} value.
> */
> public static int hashCode(short value) {
> @@ -482,6 +483,7 @@
> * 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
> diff -r 45a3584bfacf src/share/classes/java/lang/StrictMath.java
> --- a/src/share/classes/java/lang/StrictMath.java Fri Jun 14 15:14:56
> 2013 +0400
> +++ b/src/share/classes/java/lang/StrictMath.java Sun Jun 16 20:46:52
> 2013 -0700
> @@ -1,5 +1,5 @@
> /*
> - * 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 @@
> * {@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 @@
> * {@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) {
> diff -r 45a3584bfacf src/share/classes/java/lang/SuppressWarnings.java
> --- a/src/share/classes/java/lang/SuppressWarnings.java Fri Jun 14
> 15:14:56 2013 +0400
> +++ b/src/share/classes/java/lang/SuppressWarnings.java Sun Jun 16
> 20:46:52 2013 -0700
> @@ -66,6 +66,7 @@
> * 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();
> }
> diff -r 45a3584bfacf src/share/classes/java/lang/System.java
> --- a/src/share/classes/java/lang/System.java Fri Jun 14 15:14:56 2013
> +0400
> +++ b/src/share/classes/java/lang/System.java Sun Jun 16 20:46:52 2013
> -0700
> @@ -634,6 +634,8 @@
> *
> * <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() {
> 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
> 20:46:52 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();
>



More information about the core-libs-dev mailing list