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

[Kevin Bourrillion]

On Thu, Nov 29, 2012 at 2:49 AM, David Holmes <david.holmes at oracle.com>wrote:

If the type is subclassable and the method makes any calls to
>> overrideable methods on its own type, they certainly do need to specify
>> how they're implemented (see e.g. Effective Java).  And (a) interfaces
>> are always subtypable, and (b) it's hard to imagine many default
>> implementations /not /invoking any methods on the same instance (what
>>
>> else is there to do?), and those methods are of course always
>> overrideable. So this seems like an open and shut case to me.
>>
>
> Okay. In that sense all default methods are like concrete methods in the
> AbstractXXX classes. Which are described as "This implementation ..."
>
>
>     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.
>>
>> This would leave a library author having no clue whether they can depend
>> on "inheriting" the default or not.  Default method implementations are
>> not like other implementations; they're extremely leaky, and I think
>> they must be specified.
>>
>
> I don't see that they are any different to abstract class method
> implementations in that regard. The JDK doesn't mandate how the
> non-abstract methods in the AbstractXXX classes are implemented.


I'm not following. How is the "This implementation..." text you referred to
above *not* a case of the JDK mandating how they're implemented?

Guava absolutely relies heavily on those specifications of how those
methods are implemented. If we couldn't, we would no longer derive any
value from the classes at all!


 Side note: it would be nice if whatever javadoc taglet we use would be
>> usable for regular class methods as well, where it would mean "don't
>> inheritDoc from me."  We've had a constant problem with extending things
>> like AbstractSet and having "This implementation..." javadoc get copied
>> into our own classes' docs, where it becomes simply false.
>>
>
> Yes we definitely need a distinction between the normative and
> non-normative text.
>

Any thoughts on how to make this feature cover both cases?  Seems like
"@default" would not be the right tag anymore.

-- 
Kevin Bourrillion | Java Librarian | Google, Inc. | kevinb at google.com