Javadoc conventions in the presence of default methods

[Doug Lea]

On 01/31/13 21:31, Brian Goetz wrote:

>    { API, implementation } x { specification, notes }

>
> /**
>   * ... API specifications ...
>   *
>   * @apinote
>   * ... API notes ...
>   *
>   * @implspec
>   * ... implementation specification ...
>   *
>   * @implnote
>   * ... implementation notes ...
>   *
>   * @param ...
>   * @return ...
>   */

This sounds about right. Even though 90% of future @implspecs will
probably be for default methods, the need to use workarounds
for lack of them regularly arises in other cases.

I'm not completely sure about @apinote though.
For example, something saying that implementations
may have resource bound/capacity/default (without saying what
it is), is part of a spec, not just a note, so I
hope people don't use it as such.
(Further, while there could then be an @implnote
saying what that bound/etc value currently is, it is not
always a great idea to do it when nothing else depends
on the choice.  Even saying what it is sometimes invites future
problems when you need to change it.)

Similarly for some performance-related issues. For example
TreeMap should say as part of its spec that any implementation
must have expected/amortized O(log n) get and put operations.
It currently goes further and says that the implementation is
based on red-black trees, but that should probably be in
an @implnote. If we take these new categories
seriously, we'll want to do a pass through most java.util
(and related JDK) javadocs to carry this out consistently.

And so on. So the only remaining role of @apinote is
for misc rationales, warnings about potential future
changes, and things like that. Which usually textually
flow better in javadoc if just made part of the description.
So I don't see myself using it much if ever. But since I
can imagine uses here and there, I guess I have nothing against
it.

>
> Secondary: one can build on this to eliminate some common inheritance anomalies
> by making these inheritable separately, where @inheritDoc is interpreted as
> "inherit the stuff from the corresponding section."  This is backward compatible
> because these sections do not yet exist in old docs.  SO to inherit API spec and
> implementation spec, you would do:
>
>   /**
>    * {@inheritDoc}
>    * @implspec
>    * {@inheritDoc}
>    * ...
>    */
>

Yes. We've had to do huge amounts of copy/past/hack of
javadocs especially in java.util.concurrent to work around this
problem.

So, all-in-all: Yes, please do this.

-Doug