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

[Stephen Colebourne]

On 29 November 2012 07:54, Patrick Wright <pdoubleya at gmail.com> wrote:
> 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)."

I also agree with not over-specifying and blocking future changes (and
I agree with Kevin's comments more generally).

While verbose perhaps this is more like what is needed:
"The default implementation (in this implementation and this release) ..."

Stephen