初めに

javadocを眺めていたらふと見たことが無い@apiNoteというタグを見つけました。
少し調べてみると @apiNote @implSpec @impleNote というタグがJava 8から追加されているようです。

公式ドキュメントなどを探しても記載がないため少し調べてみました。

概要

これらのタグはLambda式の仕様策定の副産物で生まれたそうです。
2013年4月にJDK Javadoc maker が更新され使えるようになったとのこと。

ただし、これらのタグはJDKドキュメントで使用する以外に普及させる計画が無いそうです。
そのため公式ドキュメントにも記載がされていないということのようです。

それぞれのタグで記載されている内容を見ていきます。

APIに関する解説、根拠、または例を記載します。
通常javadocに記載するAPI仕様の補足的な記載をします。

Object#isNull
APIの注が@apiNoteで記載されている箇所です。

デフォルトメソッドの仕様を記載します。
もしくはオーバーライドして実装するべきメソッドの詳細を記載します。

ConcurrentMap#replaceAll
「実装要件」が@implSpecで記載されている箇所です。

Clock
クラス説明の中の「実装要件」が@implSpecで記載されている箇所です。

提供される実装の有益な情報や補足、注意するべき内容を記載します。

ConcurrentMap#forEach
Clock
「実装上の注意」が@implNoteで記載されている箇所です

これらのタグはデフォルトではjavadocコメントとして生成されません。
コマンドラインで出力する場合には以下の引数を与える必要があるようです。

-tag "apiNote:a:API Note:"
-tag "implSpec:a:Implementation Requirements:"
-tag "implNote:a:Implementation Note:"