RFR : 8008632 : Additional JavaDoc tags @apiNote, @implSpec and @implNote for JDK API Docs

[Mike Duigou]

On Dec 9 2013, at 11:49 , Martin Buchholz <martinrb at google.com> wrote:

> On Wed, Apr 17, 2013 at 4:51 PM, Mike Duigou <mike.duigou at oracle.com> wrote:
> 
> @apiNote : Non-normative notes about the API. Usually used for examples.
> @implSpec : Describes required behaviour of conforming implementations. Key is that the description is not inherited.
> @implNote : Non-normative notes about the implementation. Typically used for descriptions of the behaviour. Also not inherited.
> 
> The tags are used primarily by default method implementations but will be used elsewhere as well.
> 
> Although I have often wished for tags such as these, (and in the distant past held back from working on this myself due to difficulty), as currently implemented I fear they will only increase the confusion about subtle distinctions of normative vs. non-normative and documenting this class vs. all subclasses.

If this is the case then we need to tighten up the usage

> There does not appear to be any documentation in the jdk itself about these tags.  This email thread is the only documentation I can find.  Even when only used internally, there needs to be clear documentation somewhere.  Unfortunately, there is no obvious place to look for documentation on non-standard javadoc tags.  

Writing up a doc page on these tags has been on my TO-DO list for quite some time. Unfortunately it hasn't bubbled to the top yet. As we get closer to Java 8 release the priority will certainly increase. 

> The tags should be made public, since correct documentation is a need everyone has.

There are no plans to attempt to popularize these particular tags outside of use by JDK documentation. 

> While the tags themselves are private, their output is not.  When users read:
> 
> Implementation Requirements:
> 

This is still changeable. "Required behaviour of all implementations:" perhaps?

> in the javadoc, it's not at all clear what is meant - i.e. it is requirements on implementers of *this* class in any JDK, but not necessarily subclasses.  We should not use the word "Requirements" unless speaking about things required of "users".  Other JDK implementers are not the primary target of this documentation.
> 
> It's not at all easy to do this better.  Perhaps we should do away with the one-size-fits-all @implSpec expansion.  It would be clearer if the spec read:
> 
> The default method forEach in class Map (but not necessarily subinterfaces or subclasses) shall behave ...

In part the tags were added to avoid the unfortunate inclusion of implementation specifics into the functional description.

> Perhaps there should be a lower-level @noInheritDoc tag to allow people to write such prose.

That is how these are effectively being used.

Mike