The implementation of default methods

[Remi Forax]

On 12/15/2012 12:42 PM, Doug Lea wrote:
> On 12/15/12 01:50, David Holmes wrote:
>
>>>>
>>>> 2. Document "The default implementation behaves as if..." (Or whatever
>>>> Doug's
>>>> proposed wording is.)
>>>
>>> In j.u.c, we always say "is behaviorally equivalent to" but I dropped
>>> the "behaviorally" in Map candidate because someone once told me
>>> it was overly pedantic :-)
>>>
>>>>
>>>> 3. Document "The default implementation MUST"
>>>
>>> Isn't this just the normal spec part, that should precede the default
>>> implementation part?
>>
>> I think not. The "normal spec" describes the abstract operation. "The 
>> default
>> implementation MUST" specifies the concrete implementation.
>
> Sorry, I don't get it. If you say what the method requires and
> then say what default implementation is behaviorally equivalent to
> in terms of other methods (or imported functionality),
> you should in principle be done.
>
> The equivalence-based wording is critical though, and requires some
> hard work (and a little judgement) to get right. AbstractCollection
> (and other AbstractX's in j.u) specs include some now-regrettable
> wording saying exactly what they do rather than what they are equivalent
> to, which has prevented some improvements over the years.
>
> While I'm at it: It is currently a nuisance to get
> javadocs right when you override a method defaulted in
> AbstractCollection. Usually, no combination of @inheritDoc's
> will save you from copy/paste/hack to edit out the default
> implementation description while keeping the main spec.
> This will probably happen a lot when using defaulted
> implementations.

that a good reason to have a tag @implementation
then you can write

/**
  * @inheritDoc
  * @implementation  implementation specific doc ...
  */

>
> -Doug
>
>

Rémi