web-dev-qa-db-fra.com

Comment ajouter des commentaires au niveau du package dans Javadoc?

J'utilise CheckStyle , FindBugs , et PMD pour valider mon Java code. J'ai corrigé presque tous les bugs détectés par ces outils.

Je ne suis pas en mesure de comprendre comment écrire "commentaire de package" qui est un bug détecté par checkstyle. J'ai parcouru la documentation de CheckStyle, mais je ne la comprends pas.

Quelqu'un pourrait-il m'aider à écrire un commentaire au niveau du package en Java?

javadocumentationcommentsjavadoc
44
Anil Kumar.C

Les commentaires javadoc au niveau du package sont placés dans un fichier nommé package-info.Java dans le répertoire du package. Il contient le commentaire et une déclaration de package:

/**
 * Provides the classes necessary to create an applet and the classes an applet uses 
 * to communicate with its applet context. 
 * <p>
 * The applet framework involves two entities: 
 * the applet and the applet context. An applet is an embeddable window (see the 
 * {@link Java.awt.Panel} class) with a few extra methods that the applet context 
 * can use to initialize, start, and stop the applet.
 *
 * @since 1.0
 * @see Java.awt
 */
package Java.lang.applet;

Ceci est documenté ici: Fichiers de commentaires de packages

68
Michael Borgwardt
  1. Créez un fichier package-info.Java dans votre colis à documenter
  2. Ajouter le descripteur de package
  3. Ajouter un commentaire (/ ** ... * /) avant la déclaration du package

Le lien suivant fournit plus d'informations: http://docs.Oracle.com/javase/specs/jls/se5.0/html/packages.html

Il est recommandé que package-info.Java, s'il est présent, prenne la place de package.html pour javadoc et d'autres systèmes de génération de documentation similaires

Les annotations à l'échelle du package seront également déclarées sur package-info.Java

Greetz, GHad

28
GHad

Vous devez faire un package.html page située dans le package. Vous pouvez lire sur le contenu et la structure de ce fichier sur le Comment écrire des commentaires de doc pour la page de l'outil Javadoc .

6
Thomas Owens

Il existe deux façons d'ajouter de la documentation au niveau du package à l'aide de javadoc:

  1. package-info.Java
    • Seulement à partir de 5.0
    • Manière préférée
    • Peut contenir une déclaration de package, des annotations de package, des commentaires de package et des balises Javadoc
  2. package.html
    • Toute Java
    • Ne peut pas contenir une déclaration de package et/ou des annotations de package

Plus de détails et d'exemples sont ici . Lequel utiliser: Javadoc: package.html ou package-info.Java

3
Aravind R. Yarram

Google a trouvé cela comme le premier hit:

http://www.Oracle.com/technetwork/Java/javase/documentation/index-137868.html#packagecomments

Vous venez de créer un fichier nommé package.html dans chaque package.

2
duffymo

En utilisant un fichier package.html pour vos commentaires. Veuillez consulter ce document: Comment écrire des commentaires de document pour l'outil Javadoc .

1
Carlos

Vous pouvez ajouter de la documentation au niveau du package.

De documentation Sun :

En général, package-info.Java contient uniquement une déclaration de package, précédée immédiatement des annotations sur le package. Bien que le fichier puisse techniquement contenir le code source d'une ou plusieurs classes privées de package, ce serait une très mauvaise forme.

Il est recommandé que package-info.Java, s'il est présent, prenne la place de package.html pour javadoc et d'autres systèmes de génération de documentation similaires. Si ce fichier est présent, l'outil de génération de documentation doit rechercher le commentaire de documentation de package précédant immédiatement la déclaration de package (éventuellement annotée) dans package-info.Java. De cette façon, package-info.Java devient le seul référentiel pour les annotations et la documentation au niveau du package. Si, à l'avenir, il devient souhaitable d'ajouter toute autre information au niveau du package, ce fichier devrait s'avérer pratique pour ces informations.

0
pavanlimo