Javadoc conventions in the presence of default methods

[Brian Goetz]

"not completely sure" is a reasonable place to be with @apinote.  Of the 
four, its definitely the least useful.  But I think the "2x2" structure 
as proposed is a more sound basis than the "3" you'd get by taking it out.

Your other notes amount to "people could get it wrong."  Which is true, 
though there's plenty of room to get it wrong with the current scheme 
too.  I have a hard time believing we'll make it worse.  And it clearly 
addresses some long-standing gaps in our ability to document, which are 
about to get broader with the introduction of default methods.



On 2/3/2013 10:02 AM, Doug Lea wrote:
> 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
>