Detail perbedaan antara @see dan @inheritDoc

90

Saya telah melihat referensi JavaDoc , dan sementara saya memahami perbedaan mendasar antara @see(berbagai tautan) dan {@inheritDoc}(ekspor komentar JavaDoc superclass), saya memerlukan klarifikasi tentang bagaimana hal-hal sebenarnya diimplementasikan.

Di Eclipse IDE ketika saya memilih "Hasilkan Komentar Elemen" untuk metode yang diwariskan (dari antarmuka, atau toString () override, dan sebagainya) itu membuat komentar berikut

/* (non-Javadoc)
 * @see SomeClass#someMethod()
 */

Jika saya diharuskan untuk memproduksi JavaDoc, haruskah saya berhenti di situ, mengganti @seedengan {@inheritDoc}, atau mengubahnya menjadi JavaDoc yang bonafid seperti:

/**
 * {@inheritDoc}
 */

Dan ketika saya melakukannya, haruskah saya tetap mempertahankan flag metode kelas #?

java javadoc comments theUg
sumber

Jawaban:

144

Pertama-tama, Anda harus menghapus template gerhana asli karena itu hanya sampah yang berisik. Masukkan dokumen yang bermakna atau jangan masukkan apa pun. Tetapi pengulangan yang tidak berguna dari yang sudah jelas menggunakan template IDE hanya akan mengacaukan kode.

Kedua, jika Anda diminta untuk membuat javadoc, maka Anda harus membuat komentar dimulai dengan/** . Kalau tidak, itu bukan javadoc.

Terakhir, jika Anda menimpa maka Anda harus menggunakan @inheritDoc(dengan asumsi Anda ingin menambahkan ke dokumen asli, seperti yang dicatat @seh dalam komentar, jika Anda hanya ingin menduplikasi dokumen asli, Anda tidak memerlukan apa pun). @seesebaiknya hanya digunakan untuk mereferensikan metode terkait lainnya .

jtahlborn.dll
sumber
75
Anda hanya boleh menggunakan @inheritDocjika Anda ingin menambahkan ke dokumentasi superclass asli. Jika Anda hanya ingin menduplikasi, Javadoc akan melakukannya, dengan memperhatikan bahwa dokumentasi superclass berlaku untuk metode subclass yang diganti karena subclass tidak menyediakan dokumentasi tambahan.
seh
4
Saya membuat dokumen dengan dan tanpa @inheritDocdan tidak melihat perbedaan apa pun. Bahkan tanpa @inheritDoc, saya melihat bahwa Javadoc dari kelas turunan ditambahkan ke kelas dasar.
randominstanceOfLivingThing
Saya datang ke sini karena checkstyle mengeluh "metode tampaknya tidak dirancang untuk perpanjangan". Ide yang bagus adalah menggunakan @inheritDocdan kemudian menambahkan beberapa dokumentasi spesifik implementasi, misalnya bagaimana mengimplementasikan / menimpa metode induk, dan terutama MENGAPA melakukannya seperti itu.
Ben