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

[Andreas Lundblad]

On Fri, Jan 16, 2015 at 02:55:28PM -0800, Brian Burkhalter wrote:
> 
> On Jan 8, 2015, at 7:13 AM, Andreas Lundblad <andreas.lundblad at oracle.com> wrote:
> 
> > Although I was the one who brought it up, I think the whole Comparator<Number> discussion is slightly off topic. I still think that explicitly mentioning rounding and truncation is a bit confusing, as even the JDK implementations resort to other methods.
> 
> I don’t think we quite agreed on the resolution of this issue. I don’t have a strong opinion about it, but I do think it should be resolved either as Fixed or Not An Issue.
> 
> One alternative which removes the seemingly contentious verbiage is here:
> 
> http://cr.openjdk.java.net/~bpb/8067669/webrev.01/
> 
> Note that the change at line 40 should be made even if the other diffs are rejected.

This patch is an improvement in my opinion since it does not indicate that any effort is made to round or truncate the number. The obvious place to look for further documentation would be in the implementing class. I am however still in favour of making this explicit by adding "The specific semantics of the conversion is defined by the subclass in question." which is also in line with the class level documentation.

-- Andreas