Documenting exception behaviour (original) (raw)

Paul Sandoz paul.sandoz at oracle.com
Mon Apr 22 01:50:28 PDT 2013

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.

More information about the lambda-dev mailing list