Documentation of methods in java.lang.Number

[Brian Burkhalter]

On Dec 17, 2014, at 2:26 AM, Andreas Lundblad <andreas.lundblad at oracle.com> wrote:

> Another suggestion would be:
> 
> "Returns the value of the specified number as a {@code long}. The specific semantics of the conversion is defined by the subclass in question."

Does something like the following seem reasonable?

Brian

--- a/src/java.base/share/classes/java/lang/Number.java
+++ b/src/java.base/share/classes/java/lang/Number.java
@@ -54,8 +54,10 @@
  */
 public abstract class Number implements java.io.Serializable {
     /**
-     * Returns the value of the specified number as an {@code int},
-     * which may involve rounding or truncation.
+     * Returns the value of the specified number as an {@code int}.  The
+     * specific semantics of the conversion is defined by the subclass in
+     * question, and may involve a narrowing conversion such as rounding or
+     * truncation.
      *
      * @return  the numeric value represented by this object after conversion
      *          to type {@code int}.
@@ -63,8 +65,10 @@
     public abstract int intValue();
 
     /**
-     * Returns the value of the specified number as a {@code long},
-     * which may involve rounding or truncation.
+     * Returns the value of the specified number as a {@code long}.  The
+     * specific semantics of the conversion is defined by the subclass in
+     * question, and may involve a narrowing conversion such as rounding or
+     * truncation.
      *
      * @return  the numeric value represented by this object after conversion
      *          to type {@code long}.
@@ -72,8 +76,9 @@
     public abstract long longValue();
 
     /**
-     * Returns the value of the specified number as a {@code float},
-     * which may involve rounding.
+     * Returns the value of the specified number as a {@code float}.  The
+     * specific semantics of the conversion is defined by the subclass in
+     * question, and may involve a narrowing conversion such as rounding.
      *
      * @return  the numeric value represented by this object after conversion
      *          to type {@code float}.
@@ -81,8 +86,9 @@
     public abstract float floatValue();
 
     /**
-     * Returns the value of the specified number as a {@code double},
-     * which may involve rounding.
+     * Returns the value of the specified number as a {@code double}.  The
+     * specific semantics of the conversion is defined by the subclass in
+     * question, and may involve a narrowing conversion such as rounding.
      *
      * @return  the numeric value represented by this object after conversion
      *          to type {@code double}.