Bagaimana Saya Mendokumentasikan Paket di Jawa?

182

Di Java APIs saya bisa melihat komentar Javadoc untuk paket.

Bagaimana / di mana saya menempatkan komentar Javadoc untuk mendokumentasikan suatu paket?

java packages javadoc jjnguy
sumber

Jawaban:

257

Pada 1,5 Anda dapat mendefinisikan a package-info.java file dan memberikan komentar gaya javadoc standar untuk sebuah paket:

com / foo / package-info.java:

/**
 * com.foo is a group of bar utils for operating on foo things.
 */
package com.foo;

//rest of the file is empty

Spesifikasi bahasa untuk paket

Gareth Davis
sumber
3
Tautan langsung ke spec: docs.oracle.com/javase/specs/jls/se7/html/jls-7.html#jls-7.4.1
gavenkoa
7
di intellij Anda dapat mengklik kanan pada sebuah paket dan opsi untuk membuatnya harus berada di bawah menu file baru
bsautner
Saya menemukan file tersebut harus dalam nama paket / src / nama paket (dengan sisa file sumber)
trindflo
48

Hingga dan termasuk Java 1.4, Anda harus menyediakan file HTML package.html, seperti yang dijelaskan dalam jawaban lain.

Karena Java 1.5 Anda juga dapat menyediakan package-info.java , yang berisi komentar Javadoc biasa (tanpa HTML). Yang terakhir lebih disukai, karena memberi Anda beberapa fitur tambahan (terutama paket anotasi).

Detail: Dokumen Sun untuk javadoc

sleske
sumber
2
+1 untuk menyebutkan kedua cara, dan perbedaan mendasar di antara keduanya. By the way, setidaknya IntelliJ IDEA saat ini memiliki dukungan yang lebih baik untuk package.html (Ctrl-Q pada nama paket menunjukkan paket Javadocs).
Jonik
3
Perbarui komentar saya sebelumnya: IDEA saat ini mendukung dengan package-info.javabaik.
Jonik
4

Dengan package.htmlfile di tingkat paket (yaitu di direktori untuk paket itu). Ini harus berupa file yang sepenuhnya terbentuk HTML, dengan <html>tag yang ditentukan di dalamnya

oxbow_lakes
sumber
1
Keterangan lebih lanjut? Seperti apa file itu?
jjnguy
1
Ini adalah file HTML yang berisi deskripsi paket Anda. Itu dia!
oxbow_lakes
3
Ini adalah cara lama untuk melakukannya. Dari Java 1.5 dan seterusnya, Anda dapat menggunakan
package-info.java