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

[Joe Bowbeer]

Ah, yes, I misunderstood the intent.  Sorry.

I agree that the null wording should be minimized, esp. in the parameter
descriptions.

The @throws NPE descriptions make it clear in every occurrence that nulls
are prevented, which I like in this case, but do not distract the casual
reader.


On Thu, Dec 6, 2012 at 6:02 PM, David Holmes <david.holmes at oracle.com>wrote:

> Joe,
>
>
> On 7/12/2012 2:18 AM, Joe Bowbeer wrote:
>
>> 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)<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.
>>
>
> The difference here is that the intent is for nulls to be prohibited -
> full stop.
>
> In other places "we" avoid the API clutter by making broad statements
> regarding null handling "Unless otherwise stated null parameters to method
> or constructors of this class will result in NullPointerException being
> thrown". In some places we even handle this at the package doc level.
> Perhaps we should do the same here?
>
> Otherwise, the "right way" IMHO to indicate this is via @throws, not
> additional commentary on @param.
>
> Again YMMV.
>
> David
> -----
>
>
>  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/webrev/>
>>>>>>>
>>>>>>>
>>>>>>>  http://cr.openjdk.java.net/~**mduigou/8004015/2/specdiff/**
>>> java/util/function/package-**summary.html<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<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
>>>>>
>>>>>
>>>
>>>
>>