JavaDoc for default methods (Was: Re: Request for Review : CR#8004015 : Add interface extends and defaults for basic functional interfaces)

[David M. Lloyd]

On 11/27/2012 11:42 AM, David M. Lloyd wrote:
> On 11/27/2012 05:56 AM, Stephen Colebourne wrote:
>> There is also no Javadoc on the default method override. In this case,
>> passing a null to either parameter will result in an NPE. This should
>> be documented.
>>
>> More generally, you/Oracle should define a standard form of words for
>> describing what a default method does. Interfaces have not had them
>> before, and their behaviour needs documenting (even if it seems
>> obvious).
>
> I think we could/should introduce a JavaDoc taglet to support default
> method implementations specifically.  For example:
>
> /**
>   * ...
>   * @default Calls operate(double, double) throwing NPE if either input
> is null.
>   */
>
> IDEs can use their existing inspection infrastructure to warn if a
> default method implementation exists without a corresponding @default
> taglet, just as they might for a missing @param/@return/@throws etc.

Somehow reply-to-list has failed me, so I'm sending this to the right 
list manually...

-- 
- DML