Hello,
On 12/19/2014 2:39 PM, Brian Burkhalter wrote:
On Dec 17, 2014, at 2:26 AM, Andreas Lundblad <andreas.lundb...@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}.
I don't really think the current text is problematic; however, if it is
to be changed, I recommending including a citation to the "Narrowing
primitive conversion" section of the Java Language Specification. This
can be accomplished using the @jls javadoc tag; the syntax is something like
* @jls 5.1.3. Narrowing Primitive Conversion
Examples of the use of @jls can be found elsewhere in the core libraries.
For the exact wording how about
... The particular semantics of the conversion operation from the
specified number to a {@code long} are defined in subclasses. The
operation may involve a narrowing conversion, rounding, or truncation.
Cheers,
-Joe
@@ -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}.
