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

[Paul Benedict]

Can someone please clarify if I implement a default method in a
concrete class, I can still call the default method via super? Because
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.

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