Javadoc: package.html o package-info.java

230

Quando si tenta di creare commenti Javadoc a livello di pacchetto, qual è il metodo preferito? cosa fai?

package-info.java

Professionisti
- Più nuovo
Contro
- Abuso di una classe - Le classi sono per il codice, non solo per i commenti

package.html

Professionisti
- Estensione HTML significa che non è un codice
- Evidenziazione della sintassi negli IDE / editor di testo
Contro
- Nessuna?

Per me, ho sempre usato Package.html. Ma mi chiedo se è la scelta giusta.

java javadoc

— TheLQ
fonte

package-info.javapuò contenere annotazioni [pacchetto] - non sono necessariamente tutti i documenti API.

— Tom Hawtin - tackline

Non qualificherei package-info.java come un abuso di una classe. È un file sorgente Java (ha un'estensione ".java") ma non è un file di classe perché non contiene una dichiarazione di classe. E, in effetti, non può contenere una dichiarazione di classe perché "informazioni sul pacchetto" non è un nome di classe legale.

— Scrubbie,

Un altro motivo per usare package-info.java invece di package.html potrebbe essere che .java non implica un formato di output specifico della documentazione. Ad esempio, potresti voler produrre javadoc come LaTeX o come file PDF. A seconda dell'implementazione del compilatore javadoc, ciò potrebbe causare problemi nel caso .html.

— honeyp0t

In realtà @Scrubbie - anche se dovresti avere ragione, penso che puoi specificare classi private-pacchetto lì dentro. :-( Sono d'accordo con il tuo sentimento, usare package-info.javaper Javadoc e Annotations non è un abuso di classe.

— Mjaggard,

@JonasN vedere stackoverflow.com/a/14708381/751579 (so che hai avuto questo problema 3 anni fa, ma forse qualcun altro ha bisogno la punta ora)

— davidbak

269

package-info.java: "Questo file è nuovo in JDK 5.0 ed è preferito su package.html." - javadoc - The Java API Documentation Generator

Addendum: la grande differenza sembra essere le annotazioni dei pacchetti . C'è un po 'più di logica in 7.4 Dichiarazioni sui pacchetti .

Addendum: la funzione di annotazione è menzionata anche qui e qui .

Addendum: vedi anche A cosa serve package-info.java? .

— trashgod
fonte

Qualche motivo particolare per cui è preferito?

— TheLQ

@TheLQ: Sto indovinando le annotazioni del pacchetto, poiché il compilatore ha più informazioni con cui lavorare; più sopra.

— trashgod,

Le annotazioni del pacchetto sono nuove per me e sembrano una buona ragione per package-info.java a causa del suo ambito.

— impilatore

Modifica la risposta solo un po 'di più: spiega "annotazione pacchetto" - un'annotazione che deve essere applicata a tutte le classi in un pacchetto o in altro modo ai pacchetti nel loro insieme. Il link tech.puredanger.com è stato l'unico a spiegare davvero perché dovrei preoccuparmene. Detto questo, è un buon link utile.

— Roboprog,

usando package-info.java puoi usare {@link} e altri doclet. Quando colleghi una classe java.lang, quando viene generato javadoc ottieni automaticamente {@link} che punta al javadoc online della classe corrispondente al jdk che stai utilizzando; ide può anche aiutare a individuare collegamenti errati quando si esegue il refactoring refactoring.

— Luigi R. Viggiano,