Apakah ada tag javadoc untuk mendokumentasikan parameter tipe generik?

165

Saya telah mencari melalui dokumentasi javadoc di situs Sun, mencoba menemukan apakah ada tag javadoc yang dapat digunakan untuk mendokumentasikan tanda tangan tipe generik kelas atau metode.

Sesuatu seperti @typeparam, mirip dengan yang biasa @param, tetapi berlaku untuk jenis dan metode, misalnya

/**
 *  @typeparam T This describes my type parameter
 */
class MyClass<T> {
}

Saya menduga tidak ada tag seperti itu - saya tidak dapat menemukan menyebutkannya di mana pun, dan dokumen API JavaSE tidak menunjukkan tanda-tanda itu, tetapi sepertinya ini adalah kelalaian yang aneh. Adakah yang bisa membuat saya benar?

java javadoc skaffman
sumber
7
Untuk menulis javadocs yang tepat?
Timo Willemsen
2
Sadarilah bahwa untuk sebagian besar kelas benar-benar tidak ada yang menarik untuk dikatakan tentang parameter tipe, karena parameter tipe pada dasarnya ditentukan oleh bagaimana itu muncul dalam metode objek. Saya melewatkan @param <T>sebagian besar waktu dan hanya menggunakannya ketika itu benar-benar tidak jelas.
Kevin Bourrillion
3
Saya mengerti apa yang Anda katakan, tetapi dengan alasan itu, hal yang sama berlaku untuk penggunaan @paramparameter metode. Standar pengkodean Sun secara eksplisit mengatakan bahwa @paramharus digunakan bahkan jika makna parameter metode jelas.
skaffman
3
Selain itu. Pemrograman API yang baik harus mendokumentasikan diri sendiri sebaik mungkin. Apakah itu berarti api tidak memerlukan dokumentasi? tidak.
Timo Willemsen
The dokumentasi @param memberikan petunjuk untuk jenis parameter. Ingat, Oracle dapat melakukan pekerjaan yang lebih baik dalam mengiklankan dokumen ini.
Michael Allan

Jawaban:

235

Itu harus dilakukan seperti ini:

/**
 * @param <T> This describes my type parameter
 */
class MyClass<T>{

}

Sumber

Timo Willemsen
sumber
6
Doh .... OK, itu jelas memalukan ... memang menimbulkan pertanyaan mengapa kelas JavaSE (misalnya Collection) tidak menggunakannya.
skaffman
6
LinkedList menggunakannya: java.sun.com/j2se/1.5.0/docs/api/java/util/LinkedList.html
Timo Willemsen
9
@skaffman Agak terlambat tentu saja, tetapi memunculkan pertanyaan, itu tidak mengemis pertanyaan .
Thor84no
6
@ Thor84no Dari tautan Anda: Beberapa pihak berwenang menganggap penggunaan "mohon pertanyaan" sebagai cara untuk mengatakan "menimbulkan pertanyaan" atau "menghindari pertanyaan" tidak lagi salah karena telah mencapai penggunaan luas seperti itu.
Matt R
8
Sayang sekali IntelliJ menyelesaikan seperti HTML dalam hal ini.
Snicolas
27

Iya. Cukup gunakan tag @param, dan sertakan tanda kurung sudut di sekitar parameter tipe.

Seperti ini:

/**
 *  @param <T> This describes my type parameter
 */
Dave DiFranco
sumber