Merge

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

 /*
- * Copyright (c) 1996, 2009, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1996, 2011, 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
@@ -324,40 +324,45 @@ public final class Byte extends Number implements Comparable<Byte> {
     }
 
     /**
-     * Returns the value of this {@code Byte} as a
-     * {@code short}.
+     * Returns the value of this {@code Byte} as a {@code short} after
+     * a widening primitive conversion.
+     * @jls 5.1.2 Widening Primitive Conversions
      */
     public short shortValue() {
         return (short)value;
     }
 
     /**
-     * Returns the value of this {@code Byte} as an
-     * {@code int}.
+     * Returns the value of this {@code Byte} as an {@code int} after
+     * a widening primitive conversion.
+     * @jls 5.1.2 Widening Primitive Conversions
      */
     public int intValue() {
         return (int)value;
     }
 
     /**
-     * Returns the value of this {@code Byte} as a
-     * {@code long}.
+     * Returns the value of this {@code Byte} as a {@code long} after
+     * a widening primitive conversion.
+     * @jls 5.1.2 Widening Primitive Conversions
      */
     public long longValue() {
         return (long)value;
     }
 
     /**
-     * Returns the value of this {@code Byte} as a
-     * {@code float}.
+     * Returns the value of this {@code Byte} as a {@code float} after
+     * a widening primitive conversion.
+     * @jls 5.1.2 Widening Primitive Conversions
      */
     public float floatValue() {
         return (float)value;
     }
 
     /**
-     * Returns the value of this {@code Byte} as a
-     * {@code double}.
+     * Returns the value of this {@code Byte} as a {@code double}
+     * after a widening primitive conversion.
+     * @jls 5.1.2 Widening Primitive Conversions
      */
     public double doubleValue() {
         return (double)value;

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

 /*
- * Copyright (c) 1994, 2010, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1994, 2011, 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
@@ -634,11 +634,12 @@ public final class Double extends Number implements Comparable<Double> {
     }
 
     /**
-     * Returns the value of this {@code Double} as a {@code byte} (by
-     * casting to a {@code byte}).
+     * Returns the value of this {@code Double} as a {@code byte}
+     * after a narrowing primitive conversion.
      *
      * @return  the {@code double} value represented by this object
      *          converted to type {@code byte}
+     * @jls 5.1.3 Narrowing Primitive Conversions
      * @since JDK1.1
      */
     public byte byteValue() {
@@ -646,11 +647,12 @@ public final class Double extends Number implements Comparable<Double> {
     }
 
     /**
-     * Returns the value of this {@code Double} as a
-     * {@code short} (by casting to a {@code short}).
+     * Returns the value of this {@code Double} as a {@code short}
+     * after a narrowing primitive conversion.
      *
      * @return  the {@code double} value represented by this object
      *          converted to type {@code short}
+     * @jls 5.1.3 Narrowing Primitive Conversions
      * @since JDK1.1
      */
     public short shortValue() {
@@ -658,8 +660,9 @@ public final class Double extends Number implements Comparable<Double> {
     }
 
     /**
-     * Returns the value of this {@code Double} as an
-     * {@code int} (by casting to type {@code int}).
+     * Returns the value of this {@code Double} as an {@code int}
+     * after a narrowing primitive conversion.
+     * @jls 5.1.3 Narrowing Primitive Conversions
      *
      * @return  the {@code double} value represented by this object
      *          converted to type {@code int}
@@ -669,22 +672,24 @@ public final class Double extends Number implements Comparable<Double> {
     }
 
     /**
-     * Returns the value of this {@code Double} as a
-     * {@code long} (by casting to type {@code long}).
+     * Returns the value of this {@code Double} as a {@code long}
+     * after a narrowing primitive conversion.
      *
      * @return  the {@code double} value represented by this object
      *          converted to type {@code long}
+     * @jls 5.1.3 Narrowing Primitive Conversions
      */
     public long longValue() {
         return (long)value;
     }
 
     /**
-     * Returns the {@code float} value of this
-     * {@code Double} object.
+     * Returns the value of this {@code Double} as a {@code float}
+     * after a narrowing primitive conversion.
      *
      * @return  the {@code double} value represented by this object
      *          converted to type {@code float}
+     * @jls 5.1.3 Narrowing Primitive Conversions
      * @since JDK1.0
      */
     public float floatValue() {
@@ -692,8 +697,7 @@ public final class Double extends Number implements Comparable<Double> {
     }
 
     /**
-     * Returns the {@code double} value of this
-     * {@code Double} object.
+     * Returns the {@code double} value of this {@code Double} object.
      *
      * @return the {@code double} value represented by this object
      */

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

 /*
- * Copyright (c) 1994, 2010, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1994, 2011, 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
@@ -556,22 +556,24 @@ public final class Float extends Number implements Comparable<Float> {
     }
 
     /**
-     * Returns the value of this {@code Float} as a {@code byte} (by
-     * casting to a {@code byte}).
+     * Returns the value of this {@code Float} as a {@code byte} after
+     * a narrowing primitive conversion.
      *
      * @return  the {@code float} value represented by this object
      *          converted to type {@code byte}
+     * @jls 5.1.3 Narrowing Primitive Conversions
      */
     public byte byteValue() {
         return (byte)value;
     }
 
     /**
-     * Returns the value of this {@code Float} as a {@code short} (by
-     * casting to a {@code short}).
+     * Returns the value of this {@code Float} as a {@code short}
+     * after a narrowing primitive conversion.
      *
      * @return  the {@code float} value represented by this object
      *          converted to type {@code short}
+     * @jls 5.1.3 Narrowing Primitive Conversions
      * @since JDK1.1
      */
     public short shortValue() {
@@ -579,22 +581,24 @@ public final class Float extends Number implements Comparable<Float> {
     }
 
     /**
-     * Returns the value of this {@code Float} as an {@code int} (by
-     * casting to type {@code int}).
+     * Returns the value of this {@code Float} as an {@code int} after
+     * a narrowing primitive conversion.
      *
      * @return  the {@code float} value represented by this object
      *          converted to type {@code int}
+     * @jls 5.1.3 Narrowing Primitive Conversions
      */
     public int intValue() {
         return (int)value;
     }
 
     /**
-     * Returns value of this {@code Float} as a {@code long} (by
-     * casting to type {@code long}).
+     * Returns value of this {@code Float} as a {@code long} after a
+     * narrowing primitive conversion.
      *
      * @return  the {@code float} value represented by this object
      *          converted to type {@code long}
+     * @jls 5.1.3 Narrowing Primitive Conversions
      */
     public long longValue() {
         return (long)value;
@@ -610,11 +614,12 @@ public final class Float extends Number implements Comparable<Float> {
     }
 
     /**
-     * Returns the {@code double} value of this {@code Float} object.
+     * Returns the value of this {@code Float} as a {@code double}
+     * after a widening primitive conversion.
      *
      * @return the {@code float} value represented by this
-     *         object is converted to type {@code double} and the
-     *         result of the conversion is returned.
+     *         object converted to type {@code double}
+     * @jls 5.1.2 Widening Primitive Conversions
      */
     public double doubleValue() {
         return (double)value;

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

 /*
- * Copyright (c) 1994, 2010, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1994, 2011, 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
@@ -678,16 +678,18 @@ public final class Integer extends Number implements Comparable<Integer> {
     }
 
     /**
-     * Returns the value of this {@code Integer} as a
-     * {@code byte}.
+     * Returns the value of this {@code Integer} as a {@code byte}
+     * after a narrowing primitive conversion.
+     * @jls 5.1.3 Narrowing Primitive Conversions
      */
     public byte byteValue() {
         return (byte)value;
     }
 
     /**
-     * Returns the value of this {@code Integer} as a
-     * {@code short}.
+     * Returns the value of this {@code Integer} as a {@code short}
+     * after a narrowing primitive conversion.
+     * @jls 5.1.3 Narrowing Primitive Conversions
      */
     public short shortValue() {
         return (short)value;
@@ -702,24 +704,27 @@ public final class Integer extends Number implements Comparable<Integer> {
     }
 
     /**
-     * Returns the value of this {@code Integer} as a
-     * {@code long}.
+     * Returns the value of this {@code Integer} as a {@code long}
+     * after a widening primitive conversion.
+     * @jls 5.1.2 Widening Primitive Conversions
      */
     public long longValue() {
         return (long)value;
     }
 
     /**
-     * Returns the value of this {@code Integer} as a
-     * {@code float}.
+     * Returns the value of this {@code Integer} as a {@code float}
+     * after a widening primitive conversion.
+     * @jls 5.1.2 Widening Primitive Conversions
      */
     public float floatValue() {
         return (float)value;
     }
 
     /**
-     * Returns the value of this {@code Integer} as a
-     * {@code double}.
+     * Returns the value of this {@code Integer} as a {@code double}
+     * after a widening primitive conversion.
+     * @jls 5.1.2 Widening Primitive Conversions
      */
     public double doubleValue() {
         return (double)value;

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

 /*
- * Copyright (c) 1994, 2009, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1994, 2011, 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
@@ -703,24 +703,27 @@ public final class Long extends Number implements Comparable<Long> {
     }
 
     /**
-     * Returns the value of this {@code Long} as a
-     * {@code byte}.
+     * Returns the value of this {@code Long} as a {@code byte} after
+     * a narrowing primitive conversion.
+     * @jls 5.1.3 Narrowing Primitive Conversions
      */
     public byte byteValue() {
         return (byte)value;
     }
 
     /**
-     * Returns the value of this {@code Long} as a
-     * {@code short}.
+     * Returns the value of this {@code Long} as a {@code short} after
+     * a narrowing primitive conversion.
+     * @jls 5.1.3 Narrowing Primitive Conversions
      */
     public short shortValue() {
         return (short)value;
     }
 
     /**
-     * Returns the value of this {@code Long} as an
-     * {@code int}.
+     * Returns the value of this {@code Long} as an {@code int} after
+     * a narrowing primitive conversion.
+     * @jls 5.1.3 Narrowing Primitive Conversions
      */
     public int intValue() {
         return (int)value;
@@ -735,16 +738,18 @@ public final class Long extends Number implements Comparable<Long> {
     }
 
     /**
-     * Returns the value of this {@code Long} as a
-     * {@code float}.
+     * Returns the value of this {@code Long} as a {@code float} after
+     * a widening primitive conversion.
+     * @jls 5.1.2 Widening Primitive Conversions
      */
     public float floatValue() {
         return (float)value;
     }
 
     /**
-     * Returns the value of this {@code Long} as a
-     * {@code double}.
+     * Returns the value of this {@code Long} as a {@code double}
+     * after a widening primitive conversion.
+     * @jls 5.1.2 Widening Primitive Conversions
      */
     public double doubleValue() {
         return (double)value;

src/share/classes/java/lang/Number.java

 /*
- * Copyright (c) 1994, 2001, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1994, 2011, 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
@@ -26,69 +26,78 @@
 package java.lang;
 
 /**
- * The abstract class <code>Number</code> is the superclass of classes
- * <code>BigDecimal</code>, <code>BigInteger</code>,
- * <code>Byte</code>, <code>Double</code>, <code>Float</code>,
- * <code>Integer</code>, <code>Long</code>, and <code>Short</code>.
- * <p>
- * Subclasses of <code>Number</code> must provide methods to convert
- * the represented numeric value to <code>byte</code>, <code>double</code>,
- * <code>float</code>, <code>int</code>, <code>long</code>, and
- * <code>short</code>.
+ * The abstract class {@code Number} is the superclass of platform
+ * classes representing numeric values that are convertible to the
+ * primitive types {@code byte}, {@code double}, {@code float}, {@code
+ * int}, {@code long}, and {@code short}.
+ *
+ * The specific semantics of the conversion from the numeric value of
+ * a particular {@code Number} implementation to a given primitive
+ * type is defined by the {@code Number} implementation in question.
+ *
+ * For platform classes, the conversion is often analogous to a
+ * narrowing primitive conversion or a widening primitive conversion
+ * as defining in <cite>The Java&trade; Language Specification</cite>
+ * for converting between primitive types.  Therefore, conversions may
+ * lose information about the overall magnitude of a numeric value, may
+ * lose precision, and may even return a result of a different sign
+ * than the input.
+ *
+ * See the documentation of a given {@code Number} implementation for
+ * conversion details.
  *
  * @author      Lee Boynton
  * @author      Arthur van Hoff
- * @see     java.lang.Byte
- * @see     java.lang.Double
- * @see     java.lang.Float
- * @see     java.lang.Integer
- * @see     java.lang.Long
- * @see     java.lang.Short
+ * @jls 5.1.2 Widening Primitive Conversions
+ * @jls 5.1.3 Narrowing Primitive Conversions
  * @since   JDK1.0
  */
 public abstract class Number implements java.io.Serializable {
     /**
-     * Returns the value of the specified number as an <code>int</code>.
-     * This may involve rounding or truncation.
+     * Returns the value of the specified number as an {@code int},
+     * which may involve rounding or truncation.
      *
      * @return  the numeric value represented by this object after conversion
-     *          to type <code>int</code>.
+     *          to type {@code int}.
      */
     public abstract int intValue();
 
     /**
-     * Returns the value of the specified number as a <code>long</code>.
-     * This may involve rounding or truncation.
+     * Returns the value of the specified number as a {@code long},
+     * which may involve rounding or truncation.
      *
      * @return  the numeric value represented by this object after conversion
-     *          to type <code>long</code>.
+     *          to type {@code long}.
      */
     public abstract long longValue();
 
     /**
-     * Returns the value of the specified number as a <code>float</code>.
-     * This may involve rounding.
+     * Returns the value of the specified number as a {@code float},
+     * which may involve rounding.
      *
      * @return  the numeric value represented by this object after conversion
-     *          to type <code>float</code>.
+     *          to type {@code float}.
      */
     public abstract float floatValue();
 
     /**
-     * Returns the value of the specified number as a <code>double</code>.
-     * This may involve rounding.
+     * Returns the value of the specified number as a {@code double},
+     * which may involve rounding.
      *
      * @return  the numeric value represented by this object after conversion
-     *          to type <code>double</code>.
+     *          to type {@code double}.
      */
     public abstract double doubleValue();
 
     /**
-     * Returns the value of the specified number as a <code>byte</code>.
-     * This may involve rounding or truncation.
+     * Returns the value of the specified number as a {@code byte},
+     * which may involve rounding or truncation.
+     *
+     * <p>This implementation returns the result of {@link #intValue} cast
+     * to a {@code byte}.
      *
      * @return  the numeric value represented by this object after conversion
-     *          to type <code>byte</code>.
+     *          to type {@code byte}.
      * @since   JDK1.1
      */
     public byte byteValue() {
@@ -96,11 +105,14 @@ public abstract class Number implements java.io.Serializable {
     }
 
     /**
-     * Returns the value of the specified number as a <code>short</code>.
-     * This may involve rounding or truncation.
+     * Returns the value of the specified number as a {@code short},
+     * which may involve rounding or truncation.
+     *
+     * <p>This implementation returns the result of {@link #intValue} cast
+     * to a {@code short}.
      *
      * @return  the numeric value represented by this object after conversion
-     *          to type <code>short</code>.
+     *          to type {@code short}.
      * @since   JDK1.1
      */
     public short shortValue() {

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

 /*
- * Copyright (c) 1996, 2009, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1996, 2011, 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
@@ -321,8 +321,9 @@ public final class Short extends Number implements Comparable<Short> {
     }
 
     /**
-     * Returns the value of this {@code Short} as a
-     * {@code byte}.
+     * Returns the value of this {@code Short} as a {@code byte} after
+     * a narrowing primitive conversion.
+     * @jls 5.1.3 Narrowing Primitive Conversions
      */
     public byte byteValue() {
         return (byte)value;
@@ -337,32 +338,36 @@ public final class Short extends Number implements Comparable<Short> {
     }
 
     /**
-     * Returns the value of this {@code Short} as an
-     * {@code int}.
+     * Returns the value of this {@code Short} as an {@code int} after
+     * a widening primitive conversion.
+     * @jls 5.1.2 Widening Primitive Conversions
      */
     public int intValue() {
         return (int)value;
     }
 
     /**
-     * Returns the value of this {@code Short} as a
-     * {@code long}.
+     * Returns the value of this {@code Short} as a {@code long} after
+     * a widening primitive conversion.
+     * @jls 5.1.2 Widening Primitive Conversions
      */
     public long longValue() {
         return (long)value;
     }
 
     /**
-     * Returns the value of this {@code Short} as a
-     * {@code float}.
+     * Returns the value of this {@code Short} as a {@code float}
+     * after a widening primitive conversion.
+     * @jls 5.1.2 Widening Primitive Conversions
      */
     public float floatValue() {
         return (float)value;
     }
 
     /**
-     * Returns the value of this {@code Short} as a
-     * {@code double}.
+     * Returns the value of this {@code Short} as a {@code double}
+     * after a widening primitive conversion.
+     * @jls 5.1.2 Widening Primitive Conversions
      */
     public double doubleValue() {
         return (double)value;

src/share/classes/java/util/concurrent/atomic/AtomicInteger.java

@@ -246,18 +246,37 @@ public class AtomicInteger extends Number implements java.io.Serializable {
     }
 
 
+    /**
+     * Returns the value of this {@code AtomicInteger} as an
+     * {@code int}.
+     */
     public int intValue() {
         return get();
     }
 
+    /**
+     * Returns the value of this {@code AtomicInteger} as a {@code long}
+     * after a widening primitive conversion.
+     * @jls 5.1.2 Widening Primitive Conversions
+     */
     public long longValue() {
         return (long)get();
     }
 
+    /**
+     * Returns the value of this {@code AtomicInteger} as a {@code float}
+     * after a widening primitive conversion.
+     * @jls 5.1.2 Widening Primitive Conversions
+     */
     public float floatValue() {
         return (float)get();
     }
 
+    /**
+     * Returns the value of this {@code AtomicInteger} as a {@code double}
+     * after a widening primitive conversion.
+     * @jls 5.1.2 Widening Primitive Conversions
+     */
     public double doubleValue() {
         return (double)get();
     }

src/share/classes/java/util/concurrent/atomic/AtomicLong.java

@@ -260,18 +260,37 @@ public class AtomicLong extends Number implements java.io.Serializable {
     }
 
 
+    /**
+     * Returns the value of this {@code AtomicLong} as an {@code int}
+     * after a narrowing primitive conversion.
+     * @jls 5.1.3 Narrowing Primitive Conversions
+     */
     public int intValue() {
         return (int)get();
     }
 
+    /**
+     * Returns the value of this {@code AtomicLong} as a {@code long}
+     * value.
+     */
     public long longValue() {
         return get();
     }
 
+    /**
+     * Returns the value of this {@code AtomicLong} as a {@code float}
+     * after a widening primitive conversion.
+     * @jls 5.1.2 Widening Primitive Conversions
+     */
     public float floatValue() {
         return (float)get();
     }
 
+    /**
+     * Returns the value of this {@code AtomicLong} as a {@code
+     * double} after a widening primitive conversion.
+     * @jls 5.1.2 Widening Primitive Conversions
+     */
     public double doubleValue() {
         return (double)get();
     }