Utilisation de @see dans JavaDoc?

110

Quand est-ce que j'utilise @see lorsque travaille avec JavaDocs? Quelle est son utilisation?

Par exemple , si les MethodAappels MethodBalors dois - je mettre @seedans MethodBla javadoc et référence » MethodAparce que c'est ce qui l'a appelé, ou dois - je mettre une référence à MethodBpartir MethodAparce qu'il est l' appeler. J'ai lu les trucs @seesur le site Web d'Oracle et cela me semble incroyablement vague, cela dit que cela signifie «voir aussi» mais pas vraiment ce que cela signifie!

java methods javadoc

— Jeff
source

4

mettre @seeen MethodBl » javadoc et référence MethodAparce que c'est appelé -> Comment serait jamais possible de connaître toutes les méthodes qui appellent un de vos méthodes? Même si cela est possible (disons une méthode privée utilisée une seule fois), la liaison de l'appelé à l'appelant semble au moins bizarre ...

— Mr_and_Mrs_D

1

Cela signifie ce que cela signifie habituellement en anglais: oxforddictionaries.com/us/definition/american_english/see (définition 1.4)

— stackexchanger

119

Ouais, c'est assez vague.

Vous devriez l'utiliser chaque fois que pour les lecteurs de la documentation de votre méthode, il peut être utile d'examiner également une autre méthode. Si la documentation de votre methodA dit "Fonctionne comme methodB mais ...", alors vous devriez sûrement mettre un lien. Une alternative à @seeserait la {@link ...}balise en ligne :

/**
 * ...
 * Works like {@link #methodB}, but ...
 */

Lorsque le fait que methodA appelle methodB est un détail d'implémentation et qu'il n'y a pas de vraie relation de l'extérieur, vous n'avez pas besoin d'un lien ici.

— Paŭlo Ebermann
source

13

@seeest également utile pour établir des liens vers des alternatives aux @Deprecatedméthodes.

— Mauve Ranger

1

@MauveRanger Puisque @seec'est assez vague, pour les choses obsolètes, je trouve plus utile de faire quelque chose de plus explicite, comme:@deprecated since X.Y.Z; use {@link #alternateMethod()} instead

— Christopher

10

@see est utile pour obtenir des informations sur les méthodes / classes associées dans une API. Il produira un lien vers la méthode / code référencé sur la documentation. Utilisez-le lorsqu'il existe un code associé qui pourrait aider l'utilisateur à comprendre comment utiliser l'API.

— Rob Dawson
source

9

Un bon exemple d'une situation où cela @seepeut être utile serait l'implémentation ou le remplacement d'une méthode d'interface / classe abstraite. La déclaration aurait une javadocsection détaillant la méthode et la méthode remplacée / implémentée pourrait utiliser un@see balise faisant référence à la base.

Question connexe: Écrire correctement javadoc avec @see?

Documentation Java SE: @see

— AtomHeartFather
source

2

ce n'était pas moi, mais c'était probablement parce que nous avons @inheritDoc docs.oracle.com/javase/6/docs/technotes/tools/solaris/…

1

la documentation java pour @see est vraiment bonne. devrait être le premier.

— dok

2

@vaxquis @inheritDoccopie la documentation d'un autre emplacement. J'imagine que décrire des détails plutôt que d'ajouter des peluches a son utilité?

— Nielsvh

@Nielsvg cette réponse mentionne cela the overridden/implemented method could use a @see tag, referring to the base one.- et c'est exactement ce à quoi cela @inheritDocsert; OMI, il est préférable d'inclure la description de la classe de base textuellement @inheritDoc et de la compléter si nécessaire, plutôt que de s'y référer par @see- voir (sic!) Stackoverflow.com/questions/11121600/… ; de nombreux développeurs (moi inclus) préfèrent avoir tous les détails d'implémentation en un seul endroit, au lieu de ne jamais terminer la chaîne de liens ascendants menant vers le haut à travers une hiérarchie d'héritage.

2

J'utilise @see pour annoter les méthodes d'une classe d'implémentation d'interface où la description de la méthode est déjà fournie dans le javadoc de l'interface. Lorsque nous faisons cela, je remarque qu'Eclipse extrait la documentation de l'interface même lorsque je recherche une méthode sur la référence d'implémentation pendant la fin du code

— Maruthi
source