web-dev-qa-db-ja.com

Javadoc @seeまたは{@link}?

誰かがjavadoc @see{@link}の違いを教えてもらえますか?

むしろ、いつそれらを使用するのですか?

166
membersound

これに関する 公式ガイドライン はかなり明確です。

機能の違いは次のとおりです。

  • {@link}はインラインリンクであり、好きな場所に配置できます
  • @seeは独自のセクションを作成します

私の意見では、{@link}は、説明で文字通りクラス、フィールド、コンストラクター、またはメソッド名を使用する場合に最適です。ユーザーは、リンクしたもののjavadocをクリックすることができます。

2つの場合に@see注釈を使用します。

  • 何かが非常に重要ですが、説明には記載されていません。
  • 説明では同じものを複数回参照していますが、同じものへの複数のリンクの代わりとして使用されています。

この意見は、標準ライブラリ内の多種多様なドキュメントをランダムにチェックアウトすることに基づいています。

196
MarioDS

@seeは、Javadocsに独立した行を作成します。 {@link}は、テキスト内に埋め込むためのものです。

関連するエンティティである場合、@seeを使用しますが、説明テキストでは参照しません。密結合がある場合はテキスト内のリンクを使用します。または、読者がナビゲーションヒントの恩恵を受ける可能性が高いと思われます。たとえば、直接参照する必要があります。

42
Dave Newton

{@link}よりも@see(Java 1.2以降)を優先する別の参照(非推奨セクション)= 公式ドキュメント があります。

Javadoc 1.2以降の場合、標準形式は@deprecatedタグとインライン{@link}タグを使用することです。これにより、必要な場所にインラインでリンクが作成されます。例えば:

Javadoc 1.1の場合、標準形式は@deprecatedタグと@seeタグのペアを作成することです。例えば:

1
user7294900