JDK 9 RFR of 8067669: Documentation for methods in Number incomplete regarding too large values.

[Brian Burkhalter]

Please review at your convenience:

Issue:	https://bugs.openjdk.java.net/browse/JDK-8067669
Patch:	http://cr.openjdk.java.net/~bpb/8067669/webrev.00/

Summary:

Add some verbiage.

I would advocate either changing the verbiage either to the content in the patch or something better, or resolving the issue as “Not an Issue.”

Thanks,

Brian

On Dec 19, 2014, at 3:34 PM, Brian Burkhalter <brian.burkhalter at oracle.com> wrote:

> On Dec 19, 2014, at 3:26 PM, joe darcy <joe.darcy at oracle.com> wrote:
> 
>> 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.
> 
> This is already in the class level documentation which is why I left it out. No harm adding it to the method docs however.
> 
>> 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.
> 
> Seems reasonable to me.