Javadoc eine Klasse, die eine externe Schnittstelle implementiert, für die Sie nicht die Quelle geschrieben haben?

Question

Wenn meine Klasse eine gut dokumentierte externe Schnittstelle von einer externen Bibliothek implementiert (eine, die ich nicht geschrieben habe), zum Beispiel AttributeConverter von , frage ich mich die richtige Methode, meine übergeordneten Methoden zu dokumentieren. Benutze ich @inheritDoc oder einen Nicht-Javadoc-Kommentarblock oder dokumentiere einfach gar nichts, da die Dokumentation leicht gefunden werden kann, was ist der richtige Weg?

Answer 1

Es hängt davon ab, was Sie versuchen zu tun. Die erste Frage, die Sie sich stellen müssen, ist: Habe ich etwas zu den Eltern Javadoc hinzuzufügen?

Wenn die Antwort "Nein" ist, ist dies eine Art Meinung basiert. Wenn Sie es einfach weglassen, wird das Eltern-Javadoc verwendet, solange Sie @Override verwenden. Der Kommentar non-javadoc wird in Bezug auf das Ergebnis unwichtig. Es dient immer noch seinem Zweck im Quellcode. Siehe Should I use a "non-Javadoc" comment?

@inheritDoc ist in diesem Fall nicht so nützlich, da es nur das Element kopiert, auf dem es verwendet wird. Von documentation:

Legen Sie die Inline-Tag {@inheritDoc} in einem Verfahren Haupt-Beschreibung oder @return, @param oder @ throws-Tag Kommentar - die entsprechenden geerbten Haupt Beschreibung oder Tag-Kommentar ist in diesem Punkt kopiert.

Es kommt ins Spiel, wenn Sie etwas zur Elterndokumentation hinzufügen möchten. Verwenden Sie es, um die Eltern-Dokumentation irgendwann in Ihrem eigenen Kommentar einzufügen.