Javadoc: package.html oder package-info.java

230

Was ist die bevorzugte Methode, wenn Sie versuchen, Javadoc-Kommentare auf Paketebene zu erstellen? Wie geht's?

package-info.java

  • Vorteile
    • Neuer
  • Nachteile
    • Missbrauch einer Klasse - Klassen sind für Code gedacht, nicht nur für Kommentare

package.html

  • Vorteile
    • HTML-Erweiterung bedeutet, dass es kein Code ist
    • Syntaxhervorhebung in IDEs / Texteditoren
  • Nachteile
    • Keiner?

Für mich habe ich immer Package.html verwendet. Aber ich frage mich, ob es die richtige Wahl ist.

java javadoc TheLQ
quelle
46
package-info.javakann [Paket] -Anmerkungen enthalten - es sind nicht unbedingt alle API-Dokumente.
Tom Hawtin - Tackline
52
Ich würde package-info.java nicht als Missbrauch einer Klasse qualifizieren. Es ist eine Java-Quelldatei (mit der Dateierweiterung ".java"), aber keine Klassendatei, da sie keine Klassendeklaration enthält. Tatsächlich kann es keine Klassendeklaration enthalten, da "package-info" kein legaler Klassenname ist.
Scrubbie
19
Ein weiterer Grund für die Verwendung von package-info.java anstelle von package.html könnte sein, dass .java kein bestimmtes Ausgabeformat der Dokumentation impliziert. Beispielsweise möchten Sie das Javadoc möglicherweise als LaTeX oder als PDF-Datei ausgeben. Abhängig von der Implementierung des Javadoc-Compilers kann dies im Fall .html zu Problemen führen.
Honeyp0t
3
Eigentlich @Scrubbie - obwohl Sie Recht haben sollten, können Sie dort paketprivate Klassen angeben. :-( Ich stimme jedoch Ihrer Meinung zu, die Verwendung package-info.javafür Javadoc und Anmerkungen ist kein Missbrauch einer Klasse.
mjaggard
2
@ JonasN siehe stackoverflow.com/a/14708381/751579 (Ich weiß, dass Sie dieses Problem vor 3 Jahren hatten, aber vielleicht braucht jetzt jemand anderes den Tipp)
Davidbak

Antworten:

269

package-info.java: "Diese Datei ist neu in JDK 5.0 und wird gegenüber package.html bevorzugt." - javadoc - Der Java API Documentation Generator

Nachtrag: Der große Unterschied scheinen Paketanmerkungen zu sein . In 7.4 Package Declarations gibt es ein wenig mehr Gründe .

Nachtrag: Die Anmerkungsfunktion wird auch hier und hier erwähnt .

Nachtrag: Siehe auch Wofür package-info.java? .

Müllgott
quelle
3
Gibt es einen bestimmten Grund, warum es bevorzugt wird?
TheLQ
2
@TheLQ: Ich vermute Paketanmerkungen, da der Compiler mehr Informationen hat, mit denen er arbeiten kann. mehr oben.
Trashgod
3
Paketanmerkungen sind für mich neu und scheinen aufgrund ihres Umfangs ein guter Grund für package-info.java zu sein.
Stapler
6
Bearbeiten Sie die Antwort nur ein bisschen mehr: Erklären Sie "Paketanmerkung" - eine Anmerkung, die auf alle Klassen in einem Paket oder auf andere Weise auf die Pakete als Ganzes angewendet werden soll. Der Link tech.puredanger.com war der einzige, der wirklich erklärte, warum es mich interessieren sollte. Das heißt, es ist ein guter, hilfreicher Link.
Roboprog
5
Mit package-info.java können Sie {@link} und andere Dokumente verwenden. Wenn Sie eine java.lang-Klasse verknüpfen, wird beim Generieren von javadoc automatisch der {@link} angezeigt, der auf das Online-javadoc der Klasse verweist, die dem von Ihnen verwendeten jdk entspricht. ide kann auch helfen, falsche Links zu erkennen, wenn Sie Refactoring durchführen.
Luigi R. Viggiano