New annotation javadoc @apiNote

Question

I found a new and undocumented javadoc tag in the LongStream class documentation. The javadoc @apiNote tags are apparently used to explain the method in detail, but there is no documentation or release notes for this tag.

What is its true purpose? Where is his documentation?

A compiled javadoc example using @apiNote can be found in Reduce method documentation

Answer 1

I would say that they are now “official”, if not standard. See JDK-8068562 . As Nikolai noted above, his blog The new Javadoc tags @apiNote, @implSpec and @implNote provide an excellent overview. They are supported by Netbeans , and recently the Content Assist in Eclipse recognizes them . They are discussed and recommended in Effective Java, third edition. They are used throughout the source code of the Java library.

Answer 2

From the mailing list item quoted by @bargenson:

These tags are activated using the -tag function on the javadoc command line tool. They are not offered as standard javadoc tags and may be implemented differently in future releases of Java. Since they are implemented as custom tags for JDK API documentation only, you cannot automatically use them in your own code. (You can, of course, add the same command line options to your javadoc calls if you like these tags).

Thus, they are not standard Javadoc tags at all.

Answer 3

You can find something about this on the OpenJDK mailing list: http://mail.openjdk.java.net/pipermail/core-libs-dev/2013-April/016149.html