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

Question

J'ai regardé Référence JavaDoc et bien que je comprenne la différence fondamentale entre @see (divers liens) et {@inheritDoc} (commentaire JavaDoc sur l'exportation de la superclasse), j'ai besoin de précisions sur la manière dont les choses sont réellement mises en œuvre.

Dans l'IDE Eclipse, lorsque je sélectionne "Generate Element Comments" pour la méthode héritée (de l'interface, ou de la surcharge de toString(), etc.), le commentaire suivant est créé

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

Si je suis tenu de produire un JavaDoc, dois-je m'en tenir à cela, remplacer @see con {@inheritDoc} ou le rendre de bonne foi JavaDoc en tant que tel :

/**
 * {@inheritDoc}
 */

Et lorsque je fais cela, dois-je conserver l'indicateur class#method ?

Answer 1

Tout d'abord, vous devez supprimer le modèle original d'éclipse, car il ne s'agit que de déchets bruyants. Soit vous mettez des documents significatifs, soit vous ne mettez rien du tout. Mais les répétitions inutiles de ce qui est évident en utilisant les modèles IDE ne font qu'encombrer le code.

Deuxièmement, si vous êtes tenu de produire une javadoc, alors vous ont pour que le commentaire commence par /** . Sinon, ce n'est pas de la javadoc.

Enfin, si vous avez recours à des surcharges, vous devez utiliser l'option @inheritDoc (en supposant que vous voulez ajouter aux docs originaux, comme @seh l'a noté dans un commentaire, si vous voulez juste dupliquer les docs originaux, alors vous n'avez besoin de rien). @see ne doit être utilisé que pour faire référence à autre des méthodes connexes.