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