Javadoc @see atau {@link}?

184

Bisakah seseorang memberi tahu saya perbedaan antara javadoc @seedan {@link}?

Atau lebih tepatnya, kapan harus menggunakan yang mana dari mereka?

java javadoc

— anggota
sumber

213

The pedoman resmi mengenai hal ini cukup jelas.

Perbedaan fungsional adalah:

{@link} adalah tautan sebaris dan dapat ditempatkan di mana pun Anda suka
@see membuat bagiannya sendiri

Menurut pendapat saya, {@link}paling baik digunakan ketika Anda benar-benar menggunakan nama kelas, bidang, konstruktor atau metode dalam deskripsi Anda. Pengguna akan dapat mengklik javadoc dari apa yang telah Anda tautkan.

Saya menggunakan @seeanotasi dalam 2 kasus:

Sesuatu sangat relevan tetapi tidak disebutkan dalam deskripsi.
Saya merujuk hal yang sama beberapa kali dalam deskripsi, dan ini digunakan sebagai pengganti beberapa tautan yang sama.

Saya mendasarkan pendapat ini pada memeriksa secara acak dokumentasi untuk berbagai hal di perpustakaan standar.

— MarioDS
sumber

3

Javadoc memang memperingatkan bahwa @link agak intensif dan harus digunakan hanya bila perlu.

— Thomas

4

Bagi siapa pun yang mencari, Anda bisa mendapatkan detail tentang ini (termasuk peringatan tentang @linkdalam komentar di atas) di panduan Javadoc Oracle .

— Ash Ryan Arnwine

48

@seemembuat garis yang terisolasi di Javadocs. {@link}adalah untuk menanamkan dalam teks.

Saya menggunakan @seeketika itu adalah entitas terkait tetapi saya tidak merujuknya dalam teks ekspositori. Saya menggunakan tautan dalam teks ketika ada kopling ketat, atau (saya rasa) kemungkinan pembaca akan mendapat manfaat dari petunjuk navigasi, misalnya, Anda harus merujuknya secara langsung.

— Dave Newton
sumber

3

Ada referensi lain (bantahan bagian) yang sama docs resmi untuk memilih {@link}lebih @see(karena Jawa 1.2):

Untuk Javadoc 1.2 dan yang lebih baru, format standarnya adalah menggunakan tag @deprecated dan tag {@link} in-line. Ini menciptakan tautan sebaris, di mana Anda menginginkannya. Sebagai contoh:

Untuk Javadoc 1.1, format standar adalah membuat sepasang tag @deprecated dan @see. Sebagai contoh:

— pengguna7294900
sumber