Details zum Unterschied zwischen @see und @inheritDoc

87

Ich habe mir die JavaDoc-Referenz angesehen , und obwohl ich den grundlegenden Unterschied zwischen @see(verschiedenen Links) und {@inheritDoc}(Export von JavaDoc-Kommentaren der Oberklasse) verstehe, muss klargestellt werden, wie die Dinge tatsächlich implementiert wurden.

Wenn ich in der Eclipse-IDE "Generate Element Comments" für die geerbte Methode auswähle (von der Schnittstelle oder zum Überschreiben von toString () usw.), wird der folgende Kommentar erstellt

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

Wenn ich zu produzieren JavaDoc verpflichtet bin , sollte ich es dabei belassen, ersetzen @seemit {@inheritDoc}, oder es wiederum bona fide JavaDoc als solche:

/**
 * {@inheritDoc}
 */

Und wenn ich das mache, sollte ich trotzdem das Methodenflag class # behalten?

java javadoc comments theUg
quelle

Antworten:

142

Zunächst sollten Sie die ursprüngliche Eclipse-Vorlage entfernen, da es sich nur um lauten Junk handelt. Legen Sie entweder aussagekräftige Dokumente ein oder fügen Sie überhaupt nichts ein. Aber nutzloses Wiederholen des Offensichtlichen unter Verwendung von IDE-Vorlagen überfrachtet nur den Code.

Zweitens, wenn Sie zu produzieren javadoc erforderlich sind, dann Sie haben zu mit dem Kommentar Start zu machen /**. Ansonsten ist es kein Javadoc.

Wenn Sie überschreiben, sollten @inheritDocSie Folgendes verwenden (vorausgesetzt, Sie möchten zu den Originaldokumenten hinzufügen , wie @seh in einem Kommentar vermerkt hat, wenn Sie nur die Originaldokumente duplizieren möchten, benötigen Sie nichts). @seesollte nur wirklich verwendet werden, um auf andere verwandte Methoden zu verweisen .

jtahlborn
quelle
75
Sie sollten nur verwenden, @inheritDocwenn Sie beabsichtigen , die ursprüngliche Dokumentation der Oberklasse zu ergänzen . Wenn Sie lediglich möchten, dass es dupliziert wird, wird Javadoc dies bereits tun. Dabei wird darauf hingewiesen, dass die Dokumentation der Oberklasse für die überschriebene Methode der Unterklasse gilt, da die Unterklasse keine zusätzliche Dokumentation bereitstellte.
seh
4
Ich habe die Dokumente mit und ohne erstellt @inheritDocund sehe keinen Unterschied. Auch ohne das @inheritDocsehe ich, dass das Javadoc der abgeleiteten Klasse an die Basisklasse angehängt wurde.
RandominstanceOfLivingThing
Ich bin hierher gekommen, weil checkstyle sich beschwert "Methode scheint nicht für die Erweiterung ausgelegt zu sein". Eine gute Idee könnte sein, @inheritDoceine implementierungsspezifische Dokumentation zu verwenden und dann hinzuzufügen, z. B. wie die übergeordnete Methode implementiert / überschrieben wird, und insbesondere, warum sie so ausgeführt wird, wie sie ausgeführt wird.
Ben