Détails de la différence entre @see et @inheritDoc

87

J'ai examiné la référence JavaDoc , et bien que je comprenne la différence fondamentale entre @see(divers liens) et {@inheritDoc}(exportation du commentaire JavaDoc de superclasse), j'ai besoin de clarifications sur la façon dont les choses sont réellement implémentées.

Dans Eclipse IDE, lorsque je sélectionne «Générer des commentaires d'élément» pour la méthode héritée (de l'interface, ou de la substitution toString (), etc.), il crée le commentaire suivant

/* (non-Javadoc)
 * @see SomeClass#someMethod()
 */

Si je suis obligé de produire JavaDoc, devrais-je en rester là, le remplacer @seepar {@inheritDoc}ou le transformer en JavaDoc de bonne foi en tant que tel:

/**
 * {@inheritDoc}
 */

Et quand je fais cela, dois-je toujours conserver l'indicateur de méthode class #?

java javadoc comments theUg
la source

Réponses:

143

Tout d'abord, vous devez supprimer le modèle d'éclipse d'origine car il ne s'agit que d'ordures bruyantes. Soit mettre des documents significatifs, soit ne rien mettre du tout. Mais la reformulation inutile de l'évidence à l'aide de modèles IDE ne fait qu'encombrer le code.

Deuxièmement, si vous devez produire javadoc, vous devez faire commencer le commentaire par /**. Sinon, ce n'est pas javadoc.

Enfin, si vous remplacez, vous devez utiliser @inheritDoc(en supposant que vous souhaitiez ajouter aux documents d'origine, comme @seh l'a noté dans un commentaire, si vous souhaitez simplement dupliquer les documents originaux, vous n'avez besoin de rien). @seene devrait vraiment être utilisé que pour référencer d' autres méthodes connexes.

jtahlborn
la source
75
Vous ne devriez l'utiliser que @inheritDocsi vous avez l'intention d' ajouter à la documentation originale de la superclasse. Si vous voulez simplement qu'elle soit dupliquée, Javadoc le fera déjà, notant que la documentation de la superclasse s'applique à la méthode remplacée de la sous-classe car la sous-classe n'a fourni aucune documentation supplémentaire.
seh
4
J'ai généré les documents avec et sans @inheritDocet je ne vois aucune différence. Même sans le @inheritDoc, je vois que le Javadoc de la classe dérivée a été ajouté à la classe de base.
randominstanceOfLivingThing
Je suis venu ici parce que checkstyle se plaint que "la méthode ne semble pas être conçue pour l'extension". Une bonne idée pourrait être d'utiliser @inheritDocpuis d'ajouter une documentation spécifique à l'implémentation, par exemple comment elle implémente / écrase la méthode parente, et surtout POURQUOI elle le fait comme elle le fait.
Ben