JavaDocでの@seeの使用？

110

@seeJavaDocsを扱うときにいつ使用しますか？その使用法は何ですか？

たとえば場合はMethodA呼び出しがMethodB、私は入れなければならないの@seeでMethodBのjavadocを参照してMethodAそれはそれと呼ばれるものですので、または私はへの参照を配置する必要がありますMethodBからMethodA、それはそれを呼び出しているため。私は@seeOracleのWebサイトで内容を読みましたが、信じられないほど漠然としているように見えます。それは「参照」を意味するが、実際にはそれが何を意味するのかを示していません。

java methods javadoc

— ジェフ
ソース

4

入れ@seeにMethodBjavadocを参照のMethodAことがそれを呼んだものであるため、 >これまでのことは可能であろうどのようにあなたの方法のいずれかを呼び出すすべてのメソッドを知っていますか- ？これが可能であっても（たとえば、プライベートメソッドは1回しか使用されません）、呼び出し先から呼び出し元へのリンクは少なくとも奇妙な音になります...

— Mr_and_Mrs_D

1

英語で通常意味することを意味します：oxforddictionaries.com/us/definition/american_english/see（definition 1.4）

— stackexchanger

119

ええ、それはかなりあいまいです。

メソッドのドキュメンテーションの読者にとっては、他のメソッドを見ることも役立つ場合があるときにいつでも使用する必要があります。methodAのドキュメントに「methodBのように機能するが...」と書かれている場合は、リンクを設定する必要があります。の代わりに@seeインライン{@link ...}タグがあります：

/**
 * ...
 * Works like {@link #methodB}, but ...
 */

methodAがmethodBを呼び出すという事実が実装の詳細であり、外部からの実際の関係がない場合は、ここにリンクは必要ありません。

— パイロ・エバーマン
ソース

13

@see@Deprecatedメソッドの代替へのリンクにも役立ちます。

— モーブレンジャー2017

1

@MauveRanger以降は@see：のように、私はより明示的な何かをすることがより便利推奨されないもののため、かなり曖昧である@deprecated since X.Y.Z; use {@link #alternateMethod()} instead

— クリストファー・

10

@seeは、APIの関連するメソッド/クラスに関する情報に役立ちます。ドキュメントで参照されているメソッド/コードへのリンクが生成されます。ユーザーがAPIの使用方法を理解するのに役立つ関連コードがある場合に使用します。

— ロブ・ドーソン
ソース

9

@see役に立つ状況の良い例は、インターフェース/抽象クラスのメソッドを実装またはオーバーライドすることです。宣言にはjavadocメソッドの詳細セクションがあり、オーバーライド/実装されたメソッドは@see、基本のタグを参照するタグを使用できます。

関連質問： @seeを使用して適切なjavadocを作成しますか？

Java SEドキュメント： @see

— アトムハートファーザー
ソース

2

私ではなかったが、我々は@inheritDocを持っているので、それはおそらくだったdocs.oracle.com/javase/6/docs/technotes/tools/solaris/...

1

@seeのJavaドキュメントは本当に良いです。最初にする必要があります。

— ドク

2

@vaxquis @inheritDocは、ドキュメントを別の場所からコピーします。綿毛を追加するのではなく、詳細を説明するのに用途があると思いますか？

— Nielsvh 2017

@Nielsvgこの回答はそれについて言及していますthe overridden/implemented method could use a @see tag, referring to the base one.-そしてそれがまさにその@inheritDocためのものです; IMOそれはによって逐語的な基本クラスの説明を含める方が良いでしょう@inheritDoc し、必要に応じてでそれを参照するよりも、それを補う@see（！原文のまま） -参照stackoverflow.com/questions/11121600/...。多くの開発者（私も含まれます）は、継承階層を介して上向きにつながる上向きリンクのチェーンを終わらせるのではなく、すべての実装の詳細を1か所に置くことを好みます。

2

@seeを使用して、インターフェースのjavadocでメソッドの説明がすでに提供されているインターフェース実装クラスのメソッドに注釈を付けます。そうすると、コードの完了時に実装参照でメソッドを検索しているときでも、Eclipseがインターフェースのドキュメントをプルアップしていることに気づきます

— マルティ
ソース