Javadoc: package.html atau package-info.java

230

Ketika mencoba membuat komentar Javadoc tingkat paket, apa metode yang disukai? Apa yang kamu kerjakan?

package-info.java

  • Pro
    • Lebih baru
  • Cons
    • Penyalahgunaan kelas - Kelas adalah untuk kode, bukan hanya untuk komentar

package.html

  • Pro
    • Ekstensi HTML berarti bukan kodenya
    • Menyoroti sintaks dalam IDE / editor teks
  • Cons
    • Tidak ada

Bagi saya, saya selalu menggunakan Package.html. Tapi saya bertanya-tanya apakah ini pilihan yang tepat.

java javadoc TheLQ
sumber
46
package-info.javadapat berisi anotasi [paket] - itu belum tentu semua dokumen API.
Tom Hawtin - tackline
52
Saya tidak akan memenuhi syarat package-info.java sebagai penyalahgunaan kelas. Ini adalah file sumber java (memiliki ekstensi file ".java") tetapi bukan file kelas karena tidak mengandung deklarasi kelas. Dan, pada kenyataannya, itu tidak dapat berisi deklarasi kelas karena "paket-info" bukan nama kelas yang sah.
Scrubbie
19
Alasan lain untuk menggunakan package-info.java alih-alih package.html bisa jadi .java tidak menyiratkan format output spesifik dari dokumentasi. Misalnya Anda mungkin ingin menampilkan javadoc sebagai LaTeX atau sebagai file PDF. Bergantung pada implementasi kompilator javadoc, ini dapat menyebabkan masalah dalam kasus .html.
honeyp0t
3
Sebenarnya @Scrubbie - walaupun Anda seharusnya benar, saya pikir Anda dapat menentukan kelas-kelas paket privat di sana. :-( Saya setuju dengan sentimen Anda, menggunakan package-info.javauntuk Javadoc dan Annotations bukanlah penyalahgunaan kelas.
mjaggard
2
@JonasN lihat stackoverflow.com/a/14708381/751579 (saya tahu Anda memiliki masalah ini 3 tahun yang lalu, tapi mungkin orang lain membutuhkan tip sekarang)
davidbak

Jawaban:

269

package-info.java: "File ini baru di JDK 5.0, dan lebih disukai daripada package.html." - javadoc - The Java API Documentation Generator

Tambahan: Perbedaan besar tampaknya merupakan anotasi paket . Ada sedikit lebih banyak cara rasional dalam 7.4 Deklarasi Paket .

Tambahan: Fitur anotasi juga disebutkan di sini dan di sini .

Tambahan: Lihat juga Untuk apa package-info.java? .

trashgod
sumber
3
Ada alasan khusus mengapa itu disukai?
TheLQ
2
@TheLQ: Saya menebak anotasi paket, karena kompiler memiliki lebih banyak informasi untuk dikerjakan; lebih di atas.
trashgod
3
Anotasi paket adalah hal baru bagi saya, dan sepertinya alasan yang bagus untuk package-info.java karena cakupannya.
stacker
6
Edit jawaban sedikit lagi: jelaskan "anotasi paket" - anotasi yang akan diterapkan ke semua kelas dalam satu paket atau sebaliknya pada paket secara keseluruhan. Tautan tech.puredanger.com adalah satu-satunya yang benar-benar menjelaskan mengapa saya harus peduli. Yang mengatakan, itu adalah tautan yang bagus dan bermanfaat.
Roboprog
5
menggunakan package-info.java Anda dapat menggunakan {@link} dan doclets lainnya. Saat Anda menautkan kelas java.lang, ketika javadoc dibuat, Anda secara otomatis mendapatkan {@link} yang menunjuk ke javadoc online dari kelas yang cocok dengan jdk yang Anda gunakan; Ide juga dapat membantu menemukan tautan yang salah saat Anda melakukan refactoring refactoring.
Luigi R. Viggiano