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
source

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
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
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
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