Cleanup of some doclint warnings in java.lang (original) (raw)

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 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: * - * * 


* final String Digits = "(\p{Digit}+)";
* final String HexDigits = "(\p{XDigit}+)";
@@ -500,7 +499,6 @@
* // Perform suitable alternative action
* }
* 
- * 
*
* @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 @@
* 
  • ceil(log2(x)) = {@code 32 - numberOfLeadingZeros(x - 1)}
    • 
* 
*
+ * @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 population count.
*
+ * @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 @@
* 
  • ceil(log2(x)) = {@code 64 - numberOfLeadingZeros(x - 1)}
    • 
* 
*
+ * @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 population count.
*
+ * @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:
* 
    
* 
    
- * 
    SpecificationVersion:
    
- * 
    Digits RefinedVersionopt
    
+ * 
    SpecificationVersion:
    
+ * 
    Digits RefinedVersionopt
    
- * 
    RefinedVersion:
    
+ * 
    RefinedVersion:
    
* 
    {@code .} Digits
    
* 
    {@code .} Digits RefinedVersion
    
*
- * 
    Digits:
    
- * 
    Digit
    
- * 
    Digits
    
+ * 
    Digits:
    
+ * 
    Digit
    
+ * 
    Digits
    
*
- * 
    Digit:
    
+ * 
    Digit:
    
* 
    any character for which {@link Character#isDigit} returns {@code
    
true},
* e.g. 0, 1, 2, ...
* 
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 @@
*
* 
      
*
- * 
       
    •  The program exits normally, when the last non-daemon
      • 
+ * 
    •  The program exits normally, when the last non-daemon
      • 
* thread exits or when the {@link #exit exit} (equivalently,
- * {@link System#exit(int) System.exit}) method is invoked, or
+ * {{@link System#exit(int) System.exit}) method is invoked, or
*
- * 
       
    •  The virtual machine is terminated in response to a
      • 
+ * 
    •  The virtual machine is terminated in response to a
      • 
* user interrupt, such as typing ^C, 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#MINEXPONENT} -1.
* 
* @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#MINEXPONENT} -1.
* 
* @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 @@
*
* 
      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