New javadoc annotation @apiNote

Question

I found a new and undocumented javadoc tag at LongStream class documentation. The javadoc tag @apiNote seems to be used to detail some explanation about a method, but there's no documentation or release notes about this tag.

What's the real purpose of it? Where is its documentation?

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

Answer 1

I would say they are now "official" if not standard. See JDK-8068562. As Nicolai pointed out above, his blog post New Javadoc Tags @apiNote, @implSpec and @implNote gives a great overview. They are supported by Netbeans, supported by IntelliJ, and supported by Eclipse. They are discussed and recommended in Effective Java, Third Edition. They are used throughout the core Java library source code.

Answer 2

From the mailing list item quoted by @bargenson:

These tags are enabled by use of the -tag feature on the javadoc tool command line. They are not proposed as standard javadoc tags and may be implemented differently in future Java releases. Since they are implemented as custom tags just for the JDK API documentation you can't automatically use them in your own code. (You can, of course, add the same command line options to your javadoc invocations if you like these tags).

So they aren't standard Javadoc tags at all.