Utilisation de @see dans JavaDoc?
Quand dois-je utiliser @see quand vous travaillez avec JavaDocs? Quel est son usage?
Par exemple, si MethodA appelle MethodB, dois-je alors mettre @see dans _ le javadoc et la référence de MethodBMethodA parce que c'est ainsi que l'a appelé, ou dois-je mettre une référence à MethodB à partir de MethodA parce qu'il appelle il. J'ai lu des articles sur @see sur le site Web Oracle et cela me semble incroyablement vague, cela signifie que cela signifie "voir aussi" mais pas vraiment ce que cela signifie!
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 méthode A dit "Fonctionne comme méthode B mais ...", alors vous devriez sûrement mettre un lien. Une alternative à @see Serait le tag inline {@link ...}:
/**
* ...
* Works like {@link #methodB}, but ...
*/
Lorsque le fait que methodA appelle methodB soit un détail d'implémentation et qu'il n'y ait pas de relation réelle de l'extérieur, vous n'avez pas besoin d'un 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/code référencé dans la documentation. Utilisez-le lorsqu'il existe un code associé pouvant aider l'utilisateur à comprendre comment utiliser l'API.
Un bon exemple de situation où @see peut être utile d'implémenter ou de remplacer une méthode de classe abstraite/interface. La déclaration aurait la section javadoc détaillant la méthode et la méthode substituée/implémentée pourrait utiliser un @see tag, faisant référence à la base.
Question connexe: Écriture de javadoc 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 cherche une méthode sur la référence d'implémentation pendant que le code est complet.