Javadoc: package.html ou package-info.java

230

Lorsque vous essayez de créer des commentaires Javadoc au niveau du package, quelle est la méthode préférée? Que faire?

package-info.java

  • Avantages
    • Plus récent
  • Les inconvénients
    • Abus d'une classe - Les classes sont pour le code, pas seulement pour les commentaires

package.html

  • Avantages
    • L'extension HTML signifie que ce n'est pas du code
    • Mise en évidence de la syntaxe dans les éditeurs IDE / texte
  • Les inconvénients
    • Aucun?

Pour moi, j'ai toujours utilisé Package.html. Mais je me demande si c'est le bon choix.

java javadoc TheLQ
la source
46
package-info.javapeut contenir des annotations [package] - ce n'est pas nécessairement tous les documents API.
Tom Hawtin - tackline
52
Je ne qualifierais pas package-info.java d'abus de classe. C'est un fichier source java (a une extension de fichier ".java") mais n'est pas un fichier de classe car il ne contient pas de déclaration de classe. Et, en fait, il ne peut pas contenir de déclaration de classe car "package-info" n'est pas un nom de classe légal.
Scrubbie
19
Une autre raison d'utiliser package-info.java au lieu de package.html pourrait être que .java n'implique pas un format de sortie spécifique de la documentation. Par exemple, vous souhaiterez peut-être exporter le javadoc en tant que LaTeX ou en tant que fichier PDF. Selon l'implémentation du compilateur javadoc, cela peut entraîner des problèmes dans le cas .html.
honeyp0t
3
En fait @Scrubbie - bien que vous ayez raison, je pense que vous pouvez spécifier des classes de paquet privé là-dedans. :-( Je suis d'accord avec votre sentiment cependant, utiliser package-info.javapour Javadoc et Annotations n'est pas un abus de classe.
mjaggard
2
@JonasN voir stackoverflow.com/a/14708381/751579 (je sais que vous avez eu ce problème il y a 3 ans, mais peut-être que quelqu'un d'autre a besoin du conseil maintenant)
davidbak

Réponses:

269

package-info.java: "Ce fichier est nouveau dans JDK 5.0 et est préférable à package.html." - javadoc - Le générateur de documentation de l'API Java

Addendum: La grande différence semble être les annotations de paquets . Il y a un peu plus de justification dans 7.4 Déclarations de paquets .

Addendum: La fonction d'annotation est également mentionnée ici et ici .

Addendum: Voir aussi À quoipackage-info.java ça sert ? .

poubelle
la source
3
Une raison particulière pourquoi son préféré?
TheLQ
2
@TheLQ: Je devine les annotations de paquets, car le compilateur a plus d'informations à utiliser; plus ci-dessus.
trashgod
3
Les annotations de package sont nouvelles pour moi et semblent une bonne raison pour package-info.java en raison de sa portée.
stacker
6
Modifiez la réponse un peu plus: expliquez «annotation de package» - une annotation qui doit être appliquée à toutes les classes d'un package ou autrement aux packages dans leur ensemble. Le lien tech.puredanger.com était le seul à vraiment expliquer pourquoi je devais m'en soucier. Cela dit, c'est un bon lien utile.
Roboprog
5
en utilisant package-info.java, vous pouvez utiliser {@link} et d'autres doclets. Lorsque vous liez une classe java.lang, lorsque javadoc est généré, vous obtenez automatiquement le {@link} pointant vers le javadoc en ligne de la classe correspondant au jdk que vous utilisez; ide peut également aider à repérer les mauvais liens lorsque vous effectuez une refactorisation refactoring.
Luigi R. Viggiano