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 5:36 PM, Kevin Bourrillion wrote:
> On Thu, Nov 29, 2012 at 1:06 AM, David Holmes <david.holmes at oracle.com
> <mailto:david.holmes at oracle.com>> wrote:
>
>     On 29/11/2012 10:25 AM, Stephen Colebourne wrote:
>      > On 27 November 2012 18:36, Brian Goetz<brian.goetz at oracle.com
>     <mailto: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.
>
>
> 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.

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

David
-----

>
> --
> Kevin Bourrillion | Java Librarian | Google, Inc. |kevinb at google.com
> <mailto:kevinb at google.com>
>