Utilisation de @see dans une JavaDoc ?

Question

Quand dois-je utiliser @see lorsqu'il s'agit de JavaDocs ? Quelle est son utilisation ?

Par exemple, si MethodA appels MethodB dois-je alors mettre @see en MethodB et la référence MethodA parce que c'est ce qui l'a appelé, ou dois-je mettre une référence à MethodB de MethodA parce qu'il l'appelle. J'ai lu ce qui concerne les @see sur le site web d'Oracle et cela me semble incroyablement vague, il est dit que cela signifie "voir aussi" mais pas vraiment ce que cela signifie !

Answer 1

Oui, c'est assez vague.

Vous devez l'utiliser chaque fois que les lecteurs de la documentation de votre méthode peuvent trouver utile d'examiner également une autre méthode. Si la documentation de votre méthodeA dit "Fonctionne comme la méthodeB mais ...", vous devez certainement mettre un lien. Une alternative à @see serait la ligne {@link ...} étiquette :

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

Lorsque le fait que la méthode A appelle la méthode B est un détail d'implémentation et qu'il n'y a pas de relation réelle avec l'extérieur, il n'est pas nécessaire d'établir un lien.

Answer 2

En @see est un peu différente de la balise @link étiquette,
limitée à certains égards et plus souple à d'autres.
Les exemples suivants proviennent d'Eclipse :

Différents types de liens JavaDoc

1. Affiche le nom du membre pour un meilleur apprentissage, et est refactorable ; le nom sera mis à jour lors d'un renommage par refactor
2. Réactualisable et personnalisable ; votre texte est affiché à la place du nom du membre
3. Affiche le nom, refactorable
4. Réactualisable, personnalisable
5. Un plutôt médiocre c'est-à-dire une combinaison :

• Réactualisable, personnalisable, et qui reste dans l'environnement de l'entreprise. Voir aussi section
• S'affiche joliment dans le survol d'Eclipse
• Affiche la balise de lien et son formatage lorsqu'elle est générée

Answer 3

Un bon exemple de situation où @see peut être utile serait d'implémenter ou de surcharger une méthode d'interface/de classe abstraite. La déclaration aurait javadoc détaillant la méthode et la méthode surchargée/implémentée pourrait utiliser une section @see en se référant à la balise de base.

Question connexe : Ecrire une javadoc correcte avec @see ?

Documentation sur Java SE : @see

Answer 4

@see est utile pour obtenir des informations sur les méthodes/classes apparentées dans une API. Il produit un lien vers la méthode/le code référencé(e) dans la documentation. Utilisez-le lorsqu'il existe un code connexe susceptible d'aider l'utilisateur à comprendre comment utiliser l'API.

Answer 5

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