1. Accueil
  2. Question et réponse
  3. Comment ajouter des commentaires au niveau du paquet dans Javadoc?

Comment ajouter des commentaires au niveau du paquet dans Javadoc?

2010-09-06 9 views
38

J'utilise Check-Style, FindBugs et PMD pour valider mon code Java. J'ai corrigé presque tous les bugs détectés par ces outils.Comment ajouter des commentaires au niveau du paquet dans Javadoc?

Je ne suis pas capable de comprendre comment écrire "commentaire de paquet" qui est un bug attrapé par checkstyle. J'ai parcouru la documentation de Check-Style, mais je ne la comprends pas.

Quelqu'un pourrait-il m'aider à écrire un commentaire de niveau paquet en Java?

Source

2010-09-06 Anil Kumar.C

Répondre

6

Vous devez créer une page package.html dans le paquet. Vous pouvez lire sur le contenu et la structure de ce fichier sur le How to Write Doc Comments for the Javadoc Tool page.

Source

2010-09-06 11:04:55

+3

Pourquoi le vote baissier? –

+1

Je suppose que c'est à cause de ne pas mentionner package-info.java (qui est la variante préférée de nos jours). –

27
  1. Créez un fichier package-info.java dans votre package pour documenter
  2. Ajouter le descripteur de package
  3. Ajouter un commentaire (/ ** ... * /) avant la déclaration paquet

ci-dessous lien fournit plus d'informations: http://docs.oracle.com/javase/specs/jls/se5.0/html/packages.html

Il est recommandé que le paquet -info.java, si elle est présente, prendre la place de package.html pour javadoc et d'autres systèmes de production similaires de documentation

Package large annotations seront également déclarés à package-info.java

Greetz, Ghad

Source

2010-09-06 11:05:07 GHad

+1

Je n'ai jamais entendu parler de cette méthode avant. Pouvez-vous fournir un lien vers un document qui le décrit? –

+1

@Thomas Owens http://java.sun.com/docs/books/jls/third_edition/html/packages.html – emory

+0

Former le lien: Il est recommandé que package-info.java, s'il est présent, prendre la place de package.html pour javadoc et d'autres systèmes de génération de documentation similaires. – GHad

2

Google a trouvé ce que le premier coup:

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.

Source

2010-09-06 11:05:39 duffymo

+1

Où placez-vous 'package-info.html'? – Danijel

+0

Je pense qu'ils vont dans la racine du paquet. Donne un sens à essayer. Je ne sais pas comment cela a changé en trois ans depuis que j'ai répondu à cette question. – duffymo

+0

@Danijel, Nous ne pouvons pas avoir de sous-dossiers dans les paquets que nous pourrions ... – Pacerier

60

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

/** 
* 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: Package Comment Files

Source

2010-09-06 11:07:04

+0

Intéressant. La page sur la rédaction de commentaires pour Javadoc (voir ma réponse) ne mentionne même pas cela. –

+0

@Thomas: garder la documentation chevauchante constamment à jour est une chienne. –

+0

En effet, c'est. J'aurais suspecté que Sun (et maintenant Oracle) aurait fait un meilleur travail avec le maintien de la documentation. Surtout depuis que je fais du développement Java depuis plus de 5 ans maintenant et que je n'ai jamais vu ou entendu parler de cette méthode de production de documentation au niveau du paquet auparavant. –

0

Vous pouvez ajouter de la documentation au niveau du package.

De Sun documentation:

En règle générale package-info.java ne contient qu'une déclaration de l'emballage, précédée immédiatement par les annotations sur le paquet. Bien que le fichier puisse techniquement contenir le code source d'une ou de plusieurs classes privées, cela serait très mauvais.

Il est recommandé que package-info.java, s'il est présent, remplace 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 la documentation du package précédant immédiatement la déclaration de package (éventuellement annotée) dans package-info.java. De cette manière, 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 d'autres informations au niveau du paquet, ce fichier devrait constituer une base pratique pour cette information.

Source

2010-09-06 11:10:27 pavanlimo

3

Il existe deux façons d'ajouter des documents au niveau du package en utilisant javadoc:

  1. package-info.java
    • seulement de 5,0
    • meilleur moyen
    • Peut contenir une déclaration de forfait, forfait annotations, commentaires de package et balises Javadoc
  2. package.html
    • Toute version Java
    • Can ne contiennent déclaration de paquet et/ou des annotations de paquet

Plus de détails et exemples sont here. Lequel utiliser: Javadoc: package.html or package-info.java

Source

2011-12-01 19:17:05

Questions connexes

 Questions connexes