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!
@seeenMethodBl » javadoc et référenceMethodAparce 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 ...Réponses:
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 :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.
la source
@seeest également utile pour établir des liens vers des alternatives aux@Deprecatedméthodes.@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@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.
la source
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 unejavadocsection détaillant la méthode et la méthode remplacée / implémentée pourrait utiliser un@seebalise faisant référence à la base.Question connexe: Écrire correctement javadoc avec @see?
Documentation Java SE:
@seela source
@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é?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@inheritDocet 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.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
la source