Détails de la différence entre @see et @inheritDoc
J'ai examiné référence JavaDoc , et même si je comprends la différence fondamentale entre @see (divers liens) et {@inheritDoc} _ (exportation du commentaire JavaDoc de la super-classe), j’ai besoin de précisions sur la manière dont les choses ont été implémentées.
Dans Eclipse IDE lorsque je sélectionne "Generate Element Comments" pour générer des commentaires d'élément "pour la méthode héritée (à partir de l'interface ou de la substitution toString (), etc.), le commentaire suivant est créé.
/* (non-Javadoc)
* @see SomeClass#someMethod()
*/
Si je dois produire JavaDoc si je dois en rester là, remplacez @see avec {@inheritDoc}, ou le transformer en de bonne foi JavaDoc en tant que tel:
/**
* {@inheritDoc}
*/
Et quand je le ferai, devrais-je toujours conserver l'indicateur de méthode class #?
Tout d'abord, vous devez supprimer le modèle Eclipse d'origine car il ne s'agit que de fichiers indésirables bruyants. Soit mettre des documents significatifs dans ou ne rien mettre du tout. Mais il est inutile de reformuler l'évidence en utilisant IDE Les modèles encombrent simplement le code).
Deuxièmement, si vous devez produire javadoc, alors vous avez pour que le commentaire commence par /**. Sinon, ce n'est pas javadoc.
Enfin, si vous écrasez, vous devriez 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 d'origine, vous n'avez besoin de rien). @see devrait uniquement être utilisé pour faire référence à other méthodes apparentées.