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

[Brian Goetz]

I think what Stephen meant (and I agree) is that in addition to defining 
the contract for the interface method, there should be a standardized 
place (or at least convention) for implementation notes about the 
default implementation.

For example, the default implementation of List.parallelSort() might in 
fact be a serial sort.  While that conforms to the spec ("sort the 
list"), it may well be a crappy implementation, and there should be a 
sensible place to put such information.

On 11/27/2012 1:23 PM, Paul Benedict wrote:
> 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
>>
>>
>