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

[Patrick Wright]

I agree that one should write the documentation in such a way as to not
over-specify and force the hand of all implementors down the line. At the
same time, if the default method is implemented by calling other methods on
the interface, it seems reasonable for that to be documented. Perhaps the
guideline should be - "in the documentation of a default method, specify as
little about the implementation as is necessary for a consumer of the
interface to use it safely (e.g. commit to as little as possible in the
implementation)."

Alternately, one could introduce a sort of note in the JavaDoc,
specifically referring to the OpenJDK implementation.

But the principle should be that either future versions of the JDK, or
others who take and modify (or tune) the JDK for their platforms, be
allowed to provide alternate implementations for the method while still
remaining true to the specification in the JavaDoc.

Patrick


On Thu, Nov 29, 2012 at 8:36 AM, Kevin Bourrillion <kevinb at google.com>wrote:

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