Request for Review : CR#8004015 : [final (?) pass] Add interface extends and defaults for basic functional interfaces

[Joe Bowbeer]

The documentation for Collection.add is not a reasonable model to emulate?

http://docs.oracle.com/javase/6/docs/api/java/util/Collection.html#add(E)

It is written from the standpoint that nulls are OK, but notes that some
implementations might barf, and lists NPE among the possible exceptions.

I think that's the right approach for streams as well.

In a wide range of popular APIs, there are lots of methods that return
null, and it is these nulls that are the most likely to show up in
functionally-constructed streams.  Java programmers do have the notion that
nulls might not be allowed everywhere, and will look to the javadoc for
clarification.



On Thu, Dec 6, 2012 at 7:56 AM, Mike Duigou <mike.duigou at oracle.com> wrote:

> Something seems entirely out of balance regarding handling of null. If a
> methods says that it takes a reference type then why ever might it be
> assumed that null is permitted?
>
> It feels more than a bit like we are adding "no naked people" stickers to
> every building entrance and "do not insert fingers" to every electrical
> outlet. The "@throws NPE" are yet another layer of "Violators will be
> arrested" or "You will be electrocuted" stickers.
>
> It seems entirely wrongheaded to assume that null could be passed in place
> of a valid reference unless explicitly and categorically forbidden.
> Accepting null should be considered extraordinary and worthy of mention
> only when it occurs. Being rare it would also be a lot easier to document.
>
> So really, why mention null at all?
>
> Mike
>
> On Dec 6 2012, at 04:47 , David Holmes wrote:
>
> > Stephen,
> >
> > I believe that exceptions thrown should be identified using @throws -
> not implied.
> >
> > I think @param is for giving the basic description of a parameter not
> for explaining the semantics, or what different values of the parameter
> mean.
> >
> > YMMV
> >
> > David
> >
> > On 6/12/2012 8:23 PM, Stephen Colebourne wrote:
> >> On 6 December 2012 06:06, David Holmes<david.holmes at oracle.com>  wrote:
> >>> On 6/12/2012 4:20 AM, Mike Duigou wrote:
> >>>>
> >>>> I have updated webrev again to fix some reported javadoc technical
> issues
> >>>> and added null handling specification to the
> {Int|Double|Long}Supplier.
> >>>>
> >>>> http://cr.openjdk.java.net/~mduigou/8004015/2/webrev/
> >>>>
> >>>>
> http://cr.openjdk.java.net/~mduigou/8004015/2/specdiff/java/util/function/package-summary.html
> >>>>
> >>>> I believe that this iteration is complete (or very nearly so).
> >>>
> >>> Sorry to be a pain but this:
> >>>
> >>>     left - the left operand, must be non-null
> >>>
> >>> doesn't tell you what happens if it is null. Is it not better to simply
> >>> have:
> >>>
> >>> @param left the left operand
> >>> @param right the right operand
> >>> @throws NullPointerException if either left or right are null
> >>
> >> Whereas I use:
> >>  @param left the left operand, not null
> >>  @param right the right operand, not null
> >>
> >> There is an element of taste here. As I wrote up
> >> http://blog.joda.org/2012/11/javadoc-coding-standards.html
> >> Javadoc is read as source code as often as it is read as HTML. Thus,
> >> not overly cluttering is important.
> >> IMO, the @throws NPE is implied by the assertion of "not null" or
> >> "must be non-null".
> >>
> >> More importantly, the use of @param scales better. For example, there
> >> is often a case where null is treated as a default or special value.
> >> The Javadoc would then look something like
> >>
> >>  @param left the left operand, null treated as zero
> >>  @param right the right operand, null treated as zero
> >>
> >> This kind of information belongs with the @param, and for consistency
> >> it is much better to also have the "not null" aspect on the @param as
> >> well. (Everything together is easier for developers to parse)
> >>
> >> In summary, while I prefer my "not null" to Mike's "must be non-null",
> >> what is proposed is fine, and better than your (David's) proposal.
> >>
> >> Stephen
> >>
>
>