Utilisation de @see dans JavaDoc?
Quand dois-je utiliser @see pour traiter avec JavaDocs? Quelle est son utilisation?
par exemple si MethodA appelle MethodB alors je dois mettre @see dans MethodB javadoc et référence MethodA parce que c'est ce qui l'a appelé, ou je dois mettre une référence à MethodB de MethodA parce qu'il l'appelle. J'ai lu le truc sur @see sur le site Oracle et il me semble être incroyablement vague, il le dit signifie "voir aussi", mais pas vraiment ce que cela signifie!
4 réponses
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 d'examiner aussi une autre méthode. Si la documentation de votre methodA dit " fonctionne comme methodB mais ...", alors vous devriez certainement mettre un lien.
Une alternative à @see serait le inline {@link ...} tag:
/**
* ...
* Works like {@link #methodB}, but ...
*/
lorsque le fait que methodA appelle methodB est un détail de mise en œuvre et qu'il n'y a pas relation réelle de l'extérieur, vous n'avez pas besoin d'un lien ici.
@voir est utile pour des informations sur les méthodes/classes connexes dans une API. Il produira un lien vers la méthode/code référencé sur la documentation. L'utiliser quand il est lié code qui peut aider l'utilisateur à comprendre comment utiliser l'API.
un bon exemple d'une situation où @see peut être utile serait la mise en œuvre ou l'annulation d'une méthode d'interface/classe abstraite. La déclaration aurait la section javadoc détaillant la méthode et la méthode dépassée/appliquée pourrait utiliser une étiquette @see , se référant à la base.
question connexe: écrire correctement javadoc avec @see?
Java SE documentation: @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. Quand nous faisons cela, je remarque Qu'Eclipse tire vers le haut de la documentation de l'interface même quand je cherche la méthode sur la référence d'implémentation pendant le code complet