Documenting exception behaviour

[Paul Sandoz]

On Apr 22, 2013, at 5:57 AM, Mike Duigou <mike.duigou at oracle.com> wrote:

> 
> On Apr 21 2013, at 19:00 , David Holmes wrote:
> 
>> Part of the change for 
>> http://hg.openjdk.java.net/lambda/lambda/jdk/rev/96be5e1ae7d5
>> 
>> is:
>> 
>> - * Removes all of the elements of this collection which match the provided
>> - * predicate. Exceptions thrown by the predicate are relayed to the caller.
>> + * Removes all of the elements of this collection that satisfy the given
>> + * predicate. RuntimeExceptions and Errors thrown by the predicate are
>> + * propagated to the caller.
>> 
>> 
>> This change was unnecessary. The word "exception" with or without 
>> initial cap, and whether plural or singular, when in normal font refers 
>> to those things that can be a target of the "throws" statement i.e. any 
>> object that is an instance of class Throwable.
> 
> Excellent. This is the secret sauce for documenting undeclared unchecked exceptions we have been missing.
> 
>> It does not mean the 
>> Exception class, unless in code font, and capaitalized. So it is 
>> perfectly fine to say that "Exceptions thrown by the predicate are 
>> relayed to the caller." You could also say "Unchecked exceptions thrown 
>> by the predicate ...". It is not necessary to say "RuntimeExceptions and 
>> Errors thrown by the predicate ..." but if you do then RuntimeExceptions 
>> and Errors should be in code font.
> 
> I believe this was done at my suggestion. 
> 

From reviews Iterator/Iterable methods were updated to:

  "Errors or runtime exceptions thrown by the action are relayed to the caller"

(Spliterator was not, but that is because i forgot!). 

So we should try and be consistent with the agreed text.

Paul.