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

[Martin Buchholz]

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.

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.

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

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

Implementation Requirements:


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


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