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

[David Holmes]

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
>