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

[Paul Benedict]

Default methods are interface methods after all. There needs to be an
explicit stated contract what the default method (and any overriding
method) must adhere to for it to function as expected.

Paul

On Tue, Nov 27, 2012 at 12:19 PM, David M. Lloyd <david.lloyd at redhat.com>wrote:

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