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 1:06 AM, David Holmes <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>  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.


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.

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.


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