Utilisation de @see dans JavaDoc?
Quand dois-je utiliser @see lorsque je traite avec JavaDocs? Quelle est son utilisation?
Par exemple, si MethodA appels MethodB puis-je mettre @see dans MethodB's javadoc et de référence MethodA, car c'est ce qui est appelé, ou dois-je mettre une référence à MethodB à partir de MethodA, car c'est en l'appelant. J'ai lu les choses sur @see sur le site Web d'Oracle et il me semble être incroyablement vague, il dit que cela signifie "voir aussi" mais pas vraiment ce que cela signifie!
4 answers
Oui, 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 de regarder é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 à {[1] } 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 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é sur la documentation. Utilisez - le lorsqu'il existe un code associé qui pourrait aider l'utilisateur à comprendre comment utiliser l'API.
Un bon exemple de situation où @see peut être utile serait d'implémenter ou de remplacer une méthode de classe interface/abstraite. La déclaration aurait une section javadoc détaillant la méthode et la méthode remplacée/implémentée pourrait utiliser une balise @see, faisant référence à la méthode de base.
Question connexe: Écrire un javadoc approprié 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 qu'Eclipse extrait la documentation de l'interface même lorsque je recherche la méthode sur la référence d'implémentation pendant le code complete