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 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.

-- 
- DML