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

[David Holmes]

On 29/11/2012 10:25 AM, Stephen Colebourne wrote:
> On 27 November 2012 18:36, Brian Goetz<brian.goetz at oracle.com>  wrote:
>> 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.
>
> Yes, thats what I'm getting at. I don't overly care if it is a form of
> words  or a Javadoc annotation (or some other idea), so long as it is
> easy to identify that the text refers to what the default
> implementation does.

As I wrote in reply to the original thread:

I don't agree that we need to describe what the default implementation 
does, for two reasons:

1. Normal methods don't usually specify how they are implemented - it is 
an implementation detail. The "default" simply indicates that this 
method does have an implementation and you should expect that 
implementation to obey the contract of the method.

2. It is not obvious to me that the JDK's choice for a default 
implementation has to be _the_ only possible implementation choice. In 
many/most cases there will be a very obvious choice, but that doesn't 
mean that all suppliers of OpenJDK classes have to be locked in to that 
choice.

---

I will add that there may be times when we want to say something about 
"this default implementation" if it is noteworthy enough - like doing a 
parallel sort sequentially. But that should be the exception not the rule.

David

> Stephen
>