Documenting exception behaviour
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
>> - * 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.
More information about the lambda-dev