Javadoc: package.html veya package-info.java

230

Paket düzeyinde Javadoc yorumları oluşturmaya çalışırken, tercih edilen yöntem nedir? Ne yaparsın?

package-info.java

Artıları
- Daha yeni
Eksileri
- Bir sınıfın kötüye kullanılması - Sınıflar kod içindir, yalnızca yorumlar için değildir

package.html

Artıları
- HTML uzantısı kod değil
- IDE / metin editörlerinde sözdizimi vurgulama
Eksileri
- Yok?

Benim için her zaman Package.html kullandım. Ama doğru seçim olup olmadığını merak ediyorum.

java javadoc

— TheLQ
kaynak

package-info.java[paket] ek açıklamaları içerebilir - mutlaka tüm API dokümanları olmayabilir.

— Tom Hawtin - tackline

Package-info.java'yı bir sınıfın kötüye kullanılması olarak nitelendirmezdim. Bir java kaynak dosyasıdır (".java" dosya uzantısına sahiptir), ancak sınıf bildirimi içermediğinden bir sınıf dosyası değildir. Ve aslında, "paket-bilgi" yasal bir sınıf adı olmadığından bir sınıf bildirimi içeremez.

— Scrubbie

Package.html yerine package-info.java kullanmanın başka bir nedeni, .java'nın belgelerin belirli bir çıktı biçimini ima etmemesi olabilir. Örneğin, javadoc'u LaTeX veya PDF dosyası olarak çıkarmak isteyebilirsiniz. Javadoc derleyici uygulamasına bağlı olarak, bu .html durumunda sorunlara neden olabilir.

— honeyp0t

Aslında @Scrubbie - haklı olmanıza rağmen, orada paket-özel sınıfları belirtebileceğinizi düşünüyorum. :-( Gerçi ben de sizin package-info.java

— fikrinize

@JonasN bkz. Stackoverflow.com/a/14708381/751579 (Bu sorunun 3 yıl önce olduğunu biliyorum, ama belki başka birinin

— bahşişe

269

package-info.java: "Bu dosya JDK 5.0'da yenidir ve package.html yerine tercih edilir." - javadoc - Java API Belgeler Oluşturucu

Zeyilname: Büyük fark paket ek açıklamaları gibi görünüyor . 7.4 Paket Beyanlarında mantıksal yoldan biraz daha fazlası var .

Ek: Ek açıklama özelliği burada ve burada da belirtilmiştir .

Zeyilname: Ayrıca bkz Ne package-info.javaiçin? .

— trashgod
kaynak

Tercih edilmesinin özel bir nedeni var mı?

— TheLQ

@TheLQ: Derleyici ile çalışmak için daha fazla bilgi olduğu için paket ek açıklamalarını tahmin ediyorum; daha yukarıda.

— trashgod

Paket ek açıklamaları benim için yeni ve kapsamı nedeniyle package-info.java için iyi bir neden gibi görünüyor.

— İstifleyici

Cevabı biraz daha düzenleyin: "paket ek açıklamasını" açıklayın - bir paketteki tüm sınıflara ya da bir bütün olarak paketlere uygulanacak bir ek açıklama. Tech.puredanger.com bağlantısı, neden umursamam gerektiğini açıklayan tek bağlantıydı. Bununla birlikte, bu iyi ve yararlı bir bağlantı.

— Roboprog

package-info.java kullanarak {@link} ve diğer dokümanları kullanabilirsiniz. Bir java.lang sınıfını bağladığınızda, javadoc oluşturulduğunda, otomatik olarak kullandığınız jdk ile eşleşen sınıfın çevrimiçi javadocunu gösteren {@link} elde edersiniz; Refide yeniden düzenleme yaparken yanlış bağlantıları fark etmeye yardımcı olabilir.

— Luigi R. Viggiano