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

[Stephen Colebourne]

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