新しいJavadocのタグ @apiNote @implSpec @impleNote

初めに

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

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

概要

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

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

各タグの詳細

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

@apiNote

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

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

@implSpec

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

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

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

@implNote

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

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

使用上の注意

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

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

参考記事