Javadoc conventions in the presence of default methods (original) (raw)

Doug Lea dl at cs.oswego.edu
Sun Feb 3 07:02:42 PST 2013

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

More information about the lambda-libs-spec-observers mailing list