Utilisation de @see dans JavaDoc?

Quand est-ce que j’utilise @see pour traiter JavaDocs? Quelle est son utilisation?

Par exemple, si MethodA appelle MethodB dois-je mettre @see dans le javadoc de MethodA et faire référence à MethodA parce que c’est ce qui s’appelle, ou dois-je faire référence à MethodB de MethodA parce qu’il l’appelle. J’ai lu les @see sur @see sur le site Web d’Oracle et il me semble incroyablement vague, cela veut dire “voir aussi” mais pas vraiment ce que cela signifie!

Oui, c’est assez vague.

Vous devriez l’utiliser lorsque, pour les lecteurs de la documentation de votre méthode, il peut être utile de regarder une autre méthode. Si la documentation de votre méthodeA indique “Fonctionne comme methodB mais …”, alors vous devriez sûrement mettre un lien. Une alternative à @see serait la balise inline {@link ...} :

 /** * ... * 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 relation réelle de l’extérieur, vous n’avez pas besoin de lien ici.

@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 / le code référencé dans la documentation. Utilisez-le lorsque du code associé peut aider l’utilisateur à comprendre comment utiliser l’API.

Un bon exemple d’une situation où @see peut être utile serait d’implémenter ou de remplacer une méthode d’interface / classe abstraite. La déclaration aurait la section javadoc détaillant la méthode et la méthode substituée / mise en œuvre pourrait utiliser une balise @see , en référence à celle de base.

Question connexe: Ecrire un javadoc correct avec @see?

Documentation Java SE: @see

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 que Eclipse extrait la documentation de l’interface même lorsque je recherche une méthode sur la référence d’implémentation pendant l’exécution du code.