javadocコメントを書くときに参照を表す{@link}と{@linkplain}の違いがよくわからなかったので調べてみた。
{@link}タグ
クラスやメソッドへの参照を記述することができ、メソッドなどのjavadocコメントに記述することができる。
{@link}タグの記述例
/**
* タイトル.<br>
* 詳細はこの{@link Test#getId() メソッド}を参照
*/
表示イメージ
タイトル.
詳細はこのメソッドを参照
{@link}タグを使って出力されたHTMLソース
<a href="../../Test.html#getId"><CODE>メソッド</CODE></a>
※hrefのURL部分はイメージ
javadoc生成後の「メソッド」部分のHTMLソースが上記である。
<CODE>タグが入っているため、等幅フォントで表示される。
{@linkplain}タグ
クラスやメソッドへの参照を記述することができ、メソッドなどのjavadocコメントに記述することができる。
{@link}タグとは違いプレーンテキストで表示される。
{@linkplain}タグの記述例
/**
* タイトル.<br>
* 詳細はこの{@linkplain Test#getId() メソッド}を参照
*/
表示イメージ
タイトル.
詳細はこのメソッドを参照
{@linkplain}タグを使って出力されたHTMLソース
<a href="../../Test.html#getId">メソッド</a>
以上のことから{@link}タグは生成されたHTMLソースに<CODE>タグが付加されて出力されるが、{@linkplain}タグでは<CODE>タグが入っていないことが分かる。
使い分けについては調べてもあまり出てこなかったので公式の{@linkplain}が追加された時のバグフィックスを見てみる。
使い分け
Some people might prefer that use (particularly in headings, where code can look odd).
あまり英語に強くないけど「{@linkplain}タグは見出しなどを表示するときに<CODE>タグを付けてほしくない場合などに使用を好まれるかもしれません」、的なことが書かれている？
ここの「見出し」というのがよくわからないけどメソッドコメントの開始から「.」までのタイトルのことかな？
タイトルに参照とかあまり使わない気がするけど、書くとするなら以下のような感じかな？
/**
* {@linkplain String}を{@linkplain Integer}に変換.<br>
* なんらかの詳細な説明文。
* @param str 数値に変換したい文字列。{@code null}の場合は0に変換される。
* @return 変換後の数値。変換できない場合は0に変換される。{@code null}は返却されない。
*/
上記の例はString型をInteger型に変換するメソッドコメントで、String型とInteger型にリンクを付けている。
バグフィックスを見ても分かるようにもともと<CODE>タグ付加なしバージョンがないので追加しましたよ的な感じなのであまり気にせずに使ってもいいかもしれない。
もっと単純に考えて<CODE>タグがないので、「等幅フォントじゃなくてもいいよ」とか「タイトルとして表示する時に<CODE>タグは使いたくないよ」とかいう場面で使い分けすればいい感じなのかな。
あまりHTMLに詳しくないので違いの部分しか分からなかった。こういう明確な使い分けがありますよ！ということがあれば教えて下さい。