Java'da Paketleri Nasıl Belgelerim?

182

Java API'lerinde paketler için Javadoc yorumlarını görebilirsiniz.

Bir paketi belgelemek için Javadoc yorumlarını nasıl / nereye yerleştirebilirim?

java packages javadoc

— jjnguy
kaynak

257

1.5'ten itibaren bir package-info.javadosya tanımlayabilir ve bir paket için standart bir javadoc tarzı yorum sağlayabilirsiniz:

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

Paketler için dil özellikleri

— Gareth Davis
kaynak

3

Spesifikasyonlara doğrudan bağlantı: docs.oracle.com/javase/specs/jls/se7/html/jls-7.html#jls-7.4.1

— gavenkoa

7

intellij'de bir pakete sağ tıklayabilirsiniz ve bunu oluşturma seçeneği yeni dosya menüsü altında olmalıdır

— bsautner

Dosyayı paket_adı / src / paket_adı (kaynak dosyaların geri kalanıyla) içinde

— buldum

48

Java 1.4'e kadar ve bunun da dahil olduğu diğer yanıtlarda açıklandığı gibi bir HTML file package.html sağlamalısınız.

Java 1.5'ten beri package-info.java, düzenli bir Javadoc yorumu (HTML yok) içeren bir de sağlayabilirsiniz . İkincisi, size bazı ekstra özellikler (özellikle paket ek açıklamaları) verdiği için tercih edilir.

Ayrıntılar: Javadoc için Sun'ın dokümanları

— sleske
kaynak

2

Her iki yönden ve aralarındaki temel farktan bahsettiği için +1. Bu arada, en azından IntelliJ IDEA şu anda package.html için daha iyi bir desteğe sahip (bir paket adındaki Ctrl-Q, Javadocs paketini gösterir).

— Jonik

3

Önceki yorumuma güncelleme: bugünlerde IDEA package-info.javagayet iyi destekliyor .

— Jonik

4

package.htmlPaket düzeyinde bir dosya ile (yani, bu paketin dizininde). Bu HTML, <html>etiketin tanımlandığı şekilde tam olarak biçimlendirilmiş bir dosya olmalıdır

— oxbow_lakes
kaynak

1

Daha fazla detay? Dosya neye benzemeli?

— jjnguy

1

Paketinizin açıklamasını içeren bir HTML dosyasıdır. Bu kadar!

— oxbow_lakes

3

Bunu yapmanın eski yolu budur. Java 1.5'ten itibaren

— package-info.java