RFR [8014066] Mistake in documentation of ArrayList#removeRange

[Peter Levart]

On 03/14/2014 01:14 PM, Ivan Gerasimov wrote:
>
> On 14.03.2014 16:02, David Holmes wrote:
>> Ivan,
>>
>> On 14/03/2014 9:19 PM, Ivan Gerasimov wrote:
>>> Thanks Peter for the comments.
>>>
>>> On 14.03.2014 14:53, Peter Levart wrote:
>>>> On 03/14/2014 08:05 AM, Ivan Gerasimov wrote:
>>>>> One thing I noticed is that some methods I mentioned above
>>>>> (List.subList(), Arrays.sort(), etc) throw IllegalArgumentException
>>>>> when fromIndex > toIndex, not IndexOutOfBoundException.
>>>>> Wouldn't it be more correct to adopt this into removeRange() too?
>>>>
>>>> The question is, what exception should be thrown for removeRange(0,
>>>> -1) then... The order of checks matters and should be specified if two
>>>> kinds of exceptions are thrown...
>>>>
>>>
>>> In my opinion, the order of the checks should match the order of the
>>> listed exceptions in the spec.
>>
>> That's a nice proposal but unfortunately there has never been a rule 
>> that you have to document exceptions in the order you expect them to 
>> be checked; nor do you have to implement exception checks in the 
>> order they are documented. So it is too late to try and enforce this 
>> now.
>>
> Sigh.
> The order can still be stated explicitly in the doc, if it's decided 
> to throw IllegalArgumentException.

Or the checks could be documented in a way that they have disjunctive 
conditions so that the order doesn't matter:

@throws IndexOutOfBoundException if either index is negative or either 
index is greater than size()
@throws IllegalArgumentException if (fromIndex > toIndex) and neither 
index is negative nor greater than size()

Regards, Peter

> And, of course, there's no such problem if IndexOutOfBoundException is 
> the only exception thrown.
>
> Sincerely yours,
> Ivan
>
>
>> David
>> -----
>>
>>> If the order is:
>>> @throws IndexOutOfBoundException if either index is negative or either
>>> index is greater than size()
>>> @throws IllegalArgumentException if (fromIndex > toIndex)
>>>
>>> then removeRange(0, -1) should throw IndexOutOfBoundException.
>>>
>>> Sincerely yours,
>>> Ivan
>>>
>>
>>
>