On Dec 9 2013, at 11:49 , Martin Buchholz <marti...@google.com> wrote:
> On Wed, Apr 17, 2013 at 4:51 PM, Mike Duigou <mike.dui...@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
