Documentation of methods in java.lang.Number

[Andreas Lundblad]

On Tue, Dec 16, 2014 at 03:18:49PM -0800, Brian Burkhalter wrote:
> Andreas,
> 
> Doesn’t the class documentation of Number [1] provide sufficient clarity, to wit:
> 
> "The specific semantics of the conversion from the numeric value of a particular Number implementation to a given primitive type is defined by the Number implementation in question.”
> 
> and
> 
> “[…] 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 Number implementation for conversion details.”

Agree. I see no way of improving the class level documentation.

> That said, it might not however hurt slightly to modify the descriptions of {float,double,int,long}Value() to read something like, for longValue() for example:
> 
> "Returns the value of the specified number as a {@code long}, which may
>  involve rounding, truncation, or some other narrowing conversion."

Right. As it stands now the class level description says "the semantics of the conversion is defined by the Number implementation in question", and then the documentation of longValue narrows this down to "rounding or truncation". By adding "or some other narrowing conversion" we make room for the BigDecimal/BigInteger implementations, but I would argue that it's still more constrained than the class level description.

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."

-- Andreas