web-dev-qa-db-fra.com

javadoc: @version et @since

Y a-t-il une raison d'inclure les deux @version et @since dans le cadre d'un cours?

Ils semblent s'exclure mutuellement.

De plus, qu'est-ce que %I% et %G% signifie, et comment les configurer/les utiliser?

 @version %I%, %G%

Merci

javadocumentationjavadoc
43
Sasha

Le @version tag doit être la version actuelle de la version ou du fichier en question. Le %I%, %G% la syntaxe sont des macros que le logiciel de contrôle de code source remplacerait par la version actuelle du fichier et la date à laquelle le fichier est extrait.

Le @since la balise doit être utilisée pour définir la version à laquelle vous avez ajouté la méthode, la classe, etc. Ceci est un indice pour les autres développeurs qu'ils ne doivent s'attendre à la méthode que lorsqu'ils s'exécutent sur une version particulière du package. Je considérerais ces parties extrêmement importantes de la documentation si vous expédiez votre code comme une bibliothèque destinée à être utilisée par quelqu'un d'autre.

64
dhable

Bien expliqué dans un article d'Oracle, Comment écrire des commentaires de doc pour l'outil Javadoc .

@version

… Classes et interfaces uniquement.

Chez Java Software, nous utilisons @version pour la version SCCS. Voir "man sccs-get" pour plus de détails. Le consensus semble être le suivant:

% I% est incrémenté chaque fois que vous modifiez et supprimez un fichier

% G% est la date mm/jj/aa

Lorsque vous créez un fichier,% I% est défini sur 1.1. Lorsque vous le modifiez et le supprimez, il augmente à 1,2.

Certains développeurs omettent la date% G% (et l'ont fait) s'ils la trouvent trop confuse - par exemple, 3/4/96, que% G% produirait pour le 4 mars, serait interprété par des personnes extérieures aux États-Unis. Les États signifient le 3 avril. Certains développeurs n'incluent l'heure% U% que s'ils souhaitent une résolution plus fine (en raison de plusieurs enregistrements en une journée).

Le format de date numérique le plus clair serait d'avoir la date formatée en premier avec l'année, quelque chose comme aaaa-mm-jj, comme proposé dans ISO 8601 et ailleurs (comme http://www.cl.cam.ac .uk/~ mgk25/iso-time.html ), mais cette amélioration devrait provenir de SCCS.

@since

Spécifiez la version du produit lorsque le nom Java a été ajouté à la spécification API (s'il est différent de l'implémentation). Par exemple, si un package, une classe, une interface ou un membre a été ajouté au Java 2 Platform, Standard Edition, API Specification at version 1.2, use:

/**
 * @since 1.2
 */

Le doclet standard Javadoc affiche une sous-en-tête "Depuis" avec l'argument chaîne comme texte. Cette sous-rubrique apparaît dans le texte généré uniquement à l'endroit correspondant à l'endroit où la balise @since apparaît dans les commentaires du document source (l'outil Javadoc ne le fait pas proliférer dans la hiérarchie).

(La convention était autrefois "@since JDK1.2" mais comme il s'agit d'une spécification de la plate-forme Java, non particulière au JDK ou au SDK Oracle, nous avons supprimé "JDK".)

Lorsqu'un package est introduit, spécifiez une balise @since dans sa description de package et dans chacune de ses classes. (L'ajout de balises @since à chaque classe n'est techniquement pas nécessaire, mais c'est notre convention, car cela permet une plus grande visibilité dans le code source.) En l'absence de balises redéfinies, la valeur de la balise @since s'applique à chacune des classes du package et membres.

Lorsqu'une classe (ou interface) est introduite, spécifiez une balise @since dans sa description de classe et aucune balise @since dans les membres. Ajoutez une balise @since uniquement aux membres ajoutés dans une version ultérieure à la classe. Cela minimise le nombre de balises @since.

Si un membre passe de protégé à public dans une version ultérieure, la balise @since ne changera pas, même si elle est désormais utilisable par n'importe quel appelant, et pas seulement par les sous-classes.

17
ifeegoo

Je ne vois pas comment ils s'excluent mutuellement. L'un est utilisé pour définir la version, et l'autre est utilisé pour décrire depuis quand la méthode est là. Par exemple:

/**
 * Does Whatever
 * @version 1.2.3
 * @since 1.2.0
 *
 */
public void myMethod() {
    // .......
}

En ce qui concerne les personnages que vous avez mentionnés, ils semblent propriétaires, et en tout cas je n'ai aucune idée de ce qu'ils signifient.

8
Yuval Adam

@version sera enregistré à chaque modification. [1.3.21]

@since signifie que la version qui supportera cette interface ou etc. [1.3] Yuval Adam est intéressante, mais ce n'est pas la norme, Java le but du doc ​​est que tout le monde puisse comprendre.

2
zg_spring