Javadoc @see ou {@link}?
Quelqu'un pourrait-il me dire la différence entre javadoc @see et {@link}?
Ou plutôt, quand utiliser lequel d'entre eux?
Les directives officielles à ce sujet sont assez claires.
Les différences fonctionnelles sont:
{@link}est un lien en ligne et peut être placé où bon vous semble@seecrée sa propre section
À mon avis, {@link} est mieux utilisé 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'annotation @see dans 2 cas:
- Quelque chose est très pertinent mais non mentionné dans la description.
- Je me réfère à la même chose plusieurs fois dans la description, qui remplace plusieurs liens menant à la même chose.
J'ai fondé cette opinion sur une vérification aléatoire de la documentation pour une grande variété d'éléments de la bibliothèque standard.
@see crée une ligne isolée dans les Javadocs. {@link} est destiné à être incorporé au texte.
J'utilise @see lorsqu'il s'agit d'une entité liée, mais je n'y fais pas référence dans le texte de l'exposant. J'utilise des liens dans le texte lorsqu'il y a un couplage étroit ou (je pense que c'est probable) le lecteur bénéficierait de l'indicateur de navigation, par exemple, vous devrez le référencer directement.
Il y a une autre référence (section dépréciation) same documentation officielle préférer {@link} à @see (depuis Java 1.2):
Pour Javadoc 1.2 et versions ultérieures, le format standard consiste à utiliser @deprecated balise et la balise {@link} en ligne. Cela crée le lien en ligne, où tu le veux. Par exemple:
Pour Javadoc 1.1, le format standard consiste à créer une paire de balises @deprecated et @see. Par exemple: