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

[David Holmes]

On 30/11/2012 1:01 PM, Paul Benedict wrote:
> Can someone please clarify if I implement a default method in a
> concrete class, I can still call the default method via super? Because

Yes if it is immediate supertype.

> if that's true, documenting the default method's behavior is
> absolutely imperative. They function like methods in abstract classes;
> their implementation will always be available for delegation like any
> other superclass method.

The behaviour is documented - the method has a contract that it honours. 
How it honours that contract is what is under dispute. Generally methods 
don't specify how they do things. But when it involves calling methods 
that may/must be overridden in the implementation then they tend to 
document that in some way - AFAIK there are three main variants of this:
- This method does ...
- This method acts as-if ...
- In this implementation ...

Default methods don't add anything new to the question of what level of 
specification/documentation is appropriate on a concrete method.

David
-----
>
> Paul
>
> On Thu, Nov 29, 2012 at 7:50 PM, David Holmes<david.holmes at oracle.com>  wrote:
>> On 30/11/2012 12:01 AM, Kevin Bourrillion wrote:
>>> On Thu, Nov 29, 2012 at 2:49 AM, David Holmes<david.holmes at oracle.com
>>> <mailto:david.holmes at oracle.com>>  wrote:
>>>
>>>          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.
>>>
>>>
>>>      Okay. In that sense all default methods are like concrete methods in
>>>      the AbstractXXX classes. Which are described as "This implementation
>>>      ..."
>>>
>>>
>>>               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.
>>>
>>>
>>>      I don't see that they are any different to abstract class method
>>>      implementations in that regard. The JDK doesn't mandate how the
>>>      non-abstract methods in the AbstractXXX classes are implemented.
>>>
>>>
>>> I'm not following. How is the "This implementation..." text you referred
>>> to above /not/ a case of the JDK mandating how they're implemented?
>>
>> Because such statements are non-normative implementation notes. If
>> somebody else wants to implement the Java APIs and provide their own
>> class library then they are not required to match what is written in
>> implementation notes.
>>
>>>      Yes we definitely need a distinction between the normative and
>>>      non-normative text.
>>>
>>>
>>> Any thoughts on how to make this feature cover both cases?  Seems like
>>> "@default" would not be the right tag anymore.
>>
>> To me @default would by definition be non-normative text.
>>
>> But maybe we are kidding ourselves to think this facilitates alternative
>> implementations.
>>
>> David
>> -----
>>
>>>
>>> --
>>> Kevin Bourrillion | Java Librarian | Google, Inc. |kevinb at google.com
>>> <mailto:kevinb at google.com>
>>>
>>