Documentation of methods in java.lang.Number

[joe darcy]

Hello,

On 12/19/2014 2:39 PM, Brian Burkhalter wrote:
> 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}.

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