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

[Paul Benedict]

I am very use to reading methods from abstract classes stating "The
default implementation of this method does XYZ..." which is actually
pretty important to know if you want to chain/add-on to the default
behavior.

IIRC, default methods can overridden and invoked via super, so it's
important to explicitly say what to do if you want to compose
behavior.

Paul

On Thu, Nov 29, 2012 at 8:04 AM, Kevin Bourrillion <kevinb at google.com> wrote:
> On Thu, Nov 29, 2012 at 2:54 AM, Patrick Wright <pdoubleya at gmail.com> wrote:
>
> 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)."
>
>
> I think most users are already inclined to commit to as little as possible,
> so this seems overstated or misstated to me.  Hopefully we can just make
> that developer aware of the implications of either committing or not
> committing to an implementation.  Either they'll have the freedom to
> change, or their users will have the freedom to actually depend on the
> behavior, performance, etc. they are presently getting.  And of course
> there's middle ground too.
>
>
> --
> Kevin Bourrillion | Java Librarian | Google, Inc. | kevinb at google.com
>