Comment documenter des packages en Java?

182

Dans les API Java, je peux voir les commentaires Javadoc pour les packages.

Comment / où placer les commentaires Javadoc pour documenter un package?

java packages javadoc jjnguy
la source

Réponses:

257

À partir de la version 1.5, vous pouvez définir un package-info.javafichier et fournir un commentaire de style javadoc standard pour un package:

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

Spécification de la langue pour les packages

Gareth Davis
la source
3
Lien direct vers les spécifications: docs.oracle.com/javase/specs/jls/se7/html/jls-7.html#jls-7.4.1
gavenkoa
7
dans intellij, vous pouvez faire un clic droit sur un package et l'option pour créer ceci devrait être sous le nouveau menu de fichier
bsautner
J'ai trouvé que le fichier devait être dans packagename / src / packagename (avec le reste des fichiers source)
trindflo
48

Jusqu'à et y compris Java 1.4, vous deviez fournir un fichier HTML package.html, comme décrit dans les autres réponses.

Depuis Java 1.5, vous pouvez également fournir un package-info.java, qui contient un commentaire Javadoc régulier (pas de HTML). Ce dernier est préféré, car il vous donne des fonctionnalités supplémentaires (notamment les annotations de package).

Détails: documentation de Sun pour javadoc

sleske
la source
2
+1 pour mentionner les deux manières, et la différence essentielle entre elles. À propos, au moins IntelliJ IDEA a actuellement un meilleur support pour package.html (Ctrl-Q sur un nom de package montre le package Javadocs).
Jonik
3
Mise à jour de mon commentaire précédent: de nos jours, IDEA prend en charge package-info.javatrès bien.
Jonik
4

Avec un package.htmlfichier au niveau du package (c'est-à-dire dans le répertoire de ce package). Il doit s'agir d'un HTMLfichier entièrement formé , avec la <html>balise définie

oxbow_lakes
la source
1
Plus de détails? À quoi doit ressembler le fichier?
jjnguy
1
C'est un fichier HTML contenant la description de votre package. C'est tout!
oxbow_lakes
3
C'est la vieille façon de le faire. À partir de Java 1.5, vous pouvez utiliser package-info.java
k2col