Javadoc @see ou {@link}?


184

Quelqu'un pourrait-il me dire la différence entre javadoc @seeet{@link} ?

Ou plutôt, quand utiliser lequel d'entre eux?

Réponses:


213

Les directives officielles à ce sujet sont assez claires.

Les différences fonctionnelles sont:

  • {@link} est un lien en ligne et peut être placé où vous le souhaitez
  • @see crée sa propre section

À mon avis, {@link} est préférable de l'utiliser lorsque vous utilisez littéralement un nom de classe, de champ, de constructeur ou de méthode dans votre description. L'utilisateur pourra cliquer sur le javadoc de ce que vous avez lié.

J'utilise l' @seeannotation dans 2 cas:

  • Quelque chose est très pertinent mais non mentionné dans la description.
  • Je fais référence à la même chose plusieurs fois dans la description, et il est utilisé en remplacement de plusieurs liens vers le même.

J'ai basé cette opinion sur la vérification aléatoire de la documentation pour une grande variété de choses dans la bibliothèque standard.


3
Le javadoc avertit que @link est plutôt intensif et ne doit être utilisé que lorsque cela est nécessaire.
Thomas

4
Pour tous ceux qui recherchent, vous pouvez obtenir des détails à ce sujet (y compris l'avertissement à propos @linkdu commentaire ci-dessus) dans le guide Javadoc d'Oracle .
Ash Ryan Arnwine le

48

@seecrée une ligne isolée dans les Javadocs. {@link}est pour l'incorporation dans le texte.

J'utilise @seequand c'est une entité liée mais je n'y fais pas référence dans le texte explicatif. J'utilise des liens dans le texte lorsqu'il y a un couplage serré, ou (je pense) qu'il est probable que le lecteur bénéficierait de l'indice de navigation, par exemple, vous devrez le référencer directement.


3

Il y a une autre référence (section deprecation) mêmes documents officiels à préférer {@link}plus @see(depuis Java 1.2):

Pour Javadoc 1.2 et versions ultérieures, le format standard consiste à utiliser la balise @deprecated et la balise en ligne {@link}. Cela crée le lien en ligne, là où vous le souhaitez. Par exemple:

Pour Javadoc 1.1, le format standard consiste à créer une paire de balises @deprecated et @see. Par exemple:

En utilisant notre site, vous reconnaissez avoir lu et compris notre politique liée aux cookies et notre politique de confidentialité.
Licensed under cc by-sa 3.0 with attribution required.