CODEWITHSUNDEEP
javajavadocjava-8
Rafael Borja
Rafael Borja

Reputation: 4907

New javadoc annotation @apiNote

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

Upvotes: 28

Views: 13093

Answers (3)

steve
steve

Reputation: 1169

I use @apiNote as well as @implNote.

I use @apiNote for info that the developer writing consuming code must know and conform to. For example, if the app must be in a particular state before calling the method I might say: Must call init() before calling this method.

I use @implNote to describe to the maintainer of the method as to why the method is implemented the way it is. A consumer need not know how it's implemented, but the maintainer may need this info to make future changes and fixes. For example: Uses bubble sort.

Sadly, I often want to document info that fits neither of these two categories. I default to @implNote for such info.

Upvotes: 0

Garret Wilson
Garret Wilson

Reputation: 21346

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.

Upvotes: 8

user207421
user207421

Reputation: 310883

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.

Upvotes: 23

Related Questions