Penggunaan @see di JavaDoc?

110

Kapan saya menggunakan @seesaat berurusan dengan JavaDocs? Apa gunanya?

Sebagai contoh jika MethodApanggilan MethodBmaka saya harus meletakkan @seedi MethodB's javadoc dan referensi MethodAkarena itulah yang menyebutnya, atau apakah saya harus meletakkan referensi untuk MethodBdari MethodAkarena itu menyebutnya. Saya telah membaca hal-hal tentang @seedi situs web Oracle dan bagi saya tampaknya sangat tidak jelas, katanya berarti "lihat juga" tetapi tidak benar-benar apa artinya!

java methods javadoc Jeff
sumber
4
menempatkan @seedi MethodB's javadoc dan referensi MethodAkarena itulah yang menyebutnya -> Bagaimana akan pernah mungkin untuk mengetahui semua metode yang memanggil salah satu metode Anda? Bahkan jika ini memungkinkan (katakanlah metode pribadi yang hanya digunakan sekali) menghubungkan dari callee ke penelepon terdengar paling tidak aneh ...
Mr_and_Mrs_D
1
Artinya seperti yang biasanya dalam bahasa Inggris: oxforddictionaries.com/us/definition/american_english/see (definisi 1.4)
stackexchanger

Jawaban:

119

Ya, itu sangat kabur.

Anda harus menggunakannya kapan pun untuk pembaca dokumentasi metode Anda. Mungkin berguna juga untuk melihat beberapa metode lain. Jika dokumentasi metode A Anda mengatakan "Bekerja seperti metodeB tapi ...", maka Anda pasti harus meletakkan tautan. Alternatif untuk @seeakan menjadi {@link ...}tag inline :

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

Jika fakta bahwa methodA memanggil methodB adalah detail implementasi dan tidak ada hubungan nyata dari luar, Anda tidak memerlukan link di sini.

Paŭlo Ebermann
sumber
13
@seejuga berguna untuk menghubungkan ke alternatif @Deprecatedmetode.
Mauve Ranger
1
@MauveRanger Karena @seecukup kabur, untuk hal-hal yang sudah usang, saya merasa lebih berguna untuk melakukan sesuatu yang lebih eksplisit, seperti:@deprecated since X.Y.Z; use {@link #alternateMethod()} instead
Christopher
10

@see berguna untuk informasi tentang metode / kelas terkait dalam API. Ini akan menghasilkan tautan ke metode / kode yang direferensikan pada dokumentasi. Gunakan jika ada kode terkait yang mungkin membantu pengguna memahami cara menggunakan API.

Rob Dawson
sumber
9

Contoh yang baik dari situasi ketika @seedapat berguna adalah mengimplementasikan atau mengganti metode kelas antarmuka / abstrak. Deklarasi tersebut akan memiliki javadocbagian yang merinci metode dan metode yang ditimpa / diimplementasikan dapat menggunakan @seetag, mengacu pada tag dasar.

Pertanyaan terkait: Menulis javadoc yang tepat dengan @see?

Dokumentasi Java SE: @see

AtomHeartFather
sumber
2
bukan saya, tapi mungkin karena kami memiliki @inheritDoc docs.oracle.com/javase/6/docs/technotes/tools/solaris/…
1
dokumentasi java untuk @see benar-benar bagus. harus menjadi yang pertama.
dok
2
@vaxquis @inheritDocmenyalin dokumentasi dari lokasi lain. Saya membayangkan bahwa mendeskripsikan detail daripada menambahkan bulu halus memiliki kegunaannya?
Nielsvh
@Nielsvg jawaban ini menyebutkan bahwa the overridden/implemented method could use a @see tag, referring to the base one.- dan untuk itulah tepatnya @inheritDoc; IMO lebih baik menyertakan deskripsi kelas dasar secara verbatim dengan cara @inheritDoc dan menambahnya jika diperlukan, daripada merujuknya dengan @see- lihat (sic!) Stackoverflow.com/questions/11121600/… ; banyak pengembang (termasuk saya) lebih suka memiliki semua detail implementasi di satu tempat, daripada rantai tanpa akhir dari tautan ke atas yang mengarah ke atas melalui hierarki warisan.
2

Saya menggunakan @see untuk membuat anotasi metode kelas implementasi antarmuka di mana deskripsi metode sudah disediakan di javadoc antarmuka. Ketika kami melakukan itu, saya perhatikan bahwa Eclipse menarik dokumentasi antarmuka bahkan ketika saya mencari metode pada referensi implementasi selama kode selesai

Maruthi
sumber