Cleanup of some doclint warnings in java.lang
Joe Darcy
joe.darcy at oracle.com
Mon Jun 17 03:48:02 UTC 2013
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