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

[David Holmes]

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)
>
> 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/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
>>>>
>>
>>
>