Documenting exception behaviour

[Mike Duigou]

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. 

> 
> 
> Cheers,
> David
>