Die Frage ist ziemlich einfach - wie sollte ich phpdoc für die Schnittstelle und für die Klassenimplementierung der Schnittstelle unterscheiden? Sollten / können sie gleich sein oder sollte die Dokumentation der Benutzeroberfläche so allgemein wie möglich sein und die Klasse diese Schnittstelle spezifischer implementieren?
Ich schließe eine Methode phpDoc aus meinem echten Code ein:
Meine Schnittstelle:
%Vor%Meine Klasse, die Schnittstelle implementiert:
%Vor%Soll die Dokumentation so aussehen? Allgemeiner für die Schnittstelle und spezifischer für die Klasse, die diese Schnittstelle implementiert?
Die direkte Antwort auf Ihre direkte Frage ist "Ja". Die allgemeineren Beschreibungen der Schnittstelle sind gut und Sie sollten diese Informationen nur in den Klassenbeschreibungen ergänzen. Ich würde wählen, nicht die Tags auf den Klassenmethoden zu duplizieren, weil Sie dadurch verhindern, dass die Informationen Ihrer Schnittstelle gesehen werden ... Sie übersteuern es effektiv. Ich realisiere, dass das Arbeitsproblem darin besteht, dass nicht alle IDE-Autovervollständigungen und Info-Popups diese Vererbungsanalyse richtig (oder überhaupt) handhaben.
Als langjähriger phpDocumentor und IDE-Benutzer ist es meine beste Praxis, die Schnittstelle nur zu dokumentieren . Wenn es um Docblocks für die Klassen geht, die die Schnittstelle implementieren, ist die einzige Information, die ich dort einfügen würde, das @ internal -Tag zum Schreiben entwicklerspezifischer Informationen, die nicht in den Schnittstellen-API-Dokumenten erscheinen sollten. Ich erwarte, dass meine IDE weiß, dass die Implementierungsmethode der Klasse ihre Dokumente aus dem Docblock der Schnittstelle abrufen sollte.
Die Verwendung von {@inheritdoc} in freier Wildbahn ist inkonsistent darüber, was es wirklich zu erreichen beabsichtigt, und ich denke, dass Bugs in phpDocumentor 1.x die Handhabung dieses Tags im Laufe der Zeit dazu brachten, verschiedene Arten der Verwendung auszuprobieren in IDEs auch anders behandeln. Als Ergebnis ist es nicht mehr eine Praxis, die ich überhaupt verwende.
Tags und Links class php interface phpdoc documentation