Wie dokumentiere ich Pakete in Java?

182

In den Java-APIs kann ich Javadoc-Kommentare für Pakete sehen.

Wie / wo platziere ich Javadoc-Kommentare, um ein Paket zu dokumentieren?

java packages javadoc jjnguy
quelle

Antworten:

257

Ab 1.5 können Sie eine package-info.javaDatei definieren und einen Standardkommentar im Javadoc-Stil für ein Paket bereitstellen:

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

Sprachspezifikation für Pakete

Gareth Davis
quelle
3
Direkter Link zur Spezifikation: docs.oracle.com/javase/specs/jls/se7/html/jls-7.html#jls-7.4.1
Gavenkoa
7
In Intellij können Sie mit der rechten Maustaste auf ein Paket klicken und die Option, dies zu erstellen, sollte sich unter dem neuen
Dateimenü befinden
Ich fand, dass die Datei in Paketname / src / Paketname (mit dem Rest der Quelldateien) sein musste
trindflo
48

Bis einschließlich Java 1.4 mussten Sie eine HTML-Datei package.html bereitstellen, wie in den anderen Antworten beschrieben.

Seit Java 1.5 können Sie auch einen bereitstellen package-info.java, der einen regulären Javadoc-Kommentar enthält (kein HTML). Letzteres wird bevorzugt, da es Ihnen einige zusätzliche Funktionen bietet (insbesondere Paketanmerkungen).

Details: Suns Dokumente für Javadoc

sleske
quelle
2
+1 für die Erwähnung beider Wege und den wesentlichen Unterschied zwischen ihnen. Übrigens hat zumindest IntelliJ IDEA derzeit eine bessere Unterstützung für package.html (Strg-Q auf einem Paketnamen zeigt das Paket Javadocs an).
Jonik
3
Update zu meinem vorherigen Kommentar: Heutzutage unterstützt IDEA einwandfrei package-info.java.
Jonik
4

Mit einer package.htmlDatei auf Paketebene (dh im Verzeichnis für dieses Paket). Dies sollte eine vollständig geformte HTMLDatei sein, in der das <html>Tag definiert ist

oxbow_lakes
quelle
1
Mehr Details? Wie soll die Datei aussehen?
jjnguy
1
Es ist eine HTML-Datei, die die Beschreibung Ihres Pakets enthält. Das ist es!
oxbow_lakes
3
Dies ist der alte Weg, es zu tun. Ab Java 1.5 können Sie package-info.java
k2col