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

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