Share
An diesem Punkt der Serie haben wir eine Menge Material behandelt - nicht nur haben wir die Grundlagen der objektorientierten Programmierung behandelt, sondern auch ein voll funktionsfähiges Plugin entwickelt.
Aber die Herausforderung, die wir mit der Arbeit haben, die wir bis jetzt gemacht haben, besteht darin, dass sie keine Dokumentation darüber enthält, wie das Plugin tatsächlich funktioniert. Wenn Sie sich an den vorherigen Artikel erinnern, haben wir eine bewusste Entwicklungsentscheidung getroffen, um diese Funktion zu verschieben.
In diesem Artikel werden wir in zwei Teilen sehen, wie WordPress-Plugins dokumentiert werden und wie wir dies mit unserem aktuellen Plugin tun können.
Bevor wir mit dem Rest dieses Artikels fortfahren, möchte ich Sie dringend bitten, den Inhalt, den wir bisher behandelt haben, nachzuholen. Wie in jedem früheren Artikel erwähnt, baut jeder Artikel auf dem vorherigen Artikel der Serie auf.
Nachdem dies gesagt wurde, ist es an der Zeit, unsere Aufmerksamkeit auf die Dokumentation unseres Plugins zu lenken. Bevor wir dies tun, müssen wir jedoch sicherstellen, dass wir die Standards, die für die Dokumentation unserer Arbeit gelten, vollständig verstehen.
Bevor wir also die Kommentare veröffentlichen, die für unser Plugin relevant sind, schauen wir uns an, was wir alles hinzufügen müssen. Danach werden wir im nächsten Artikel genau das für unser Plugin tun.
Für den Anfang enthält der WordPress-Codex ein Handbuch speziell für die PHP-Dokumentationsstandards. Sie können die Standards vollständig lesen. Im Folgenden werden wir jedoch die wichtigsten Funktionen unserer Implementierung hervorheben.
Die wichtigsten Dinge, die uns mit dem Dokumentieren beschäftigen, sind folgende:
Accentsconagua
benötigen AussagenDies wird natürlich ein viel langsamerer Satz von Artikeln sein als die beiden vorherigen, aber angesichts der Menge an Arbeit, die wir bisher geleistet haben, sollte dies für einige Leser eine willkommene Abwechslung sein.
Also mit dem gesagt, lass uns anfangen.
Dateiheader sind einzigartig in der Tatsache, dass sie etwas sind sollte In jeder Datei der Dateien, aus denen ein Plugin besteht (oder ein Design, aber nicht das ist der Fokus dieser Serie), sind sie nicht immer vorhanden.
Gemäß dem Kodex:
Der PHPDoc-Dateikopfblock wird verwendet, um einen Überblick darüber zu erhalten, was in der Datei enthalten ist.
Die allgemeine Vorlage, die wir ab dem nächsten Artikel verwenden werden, sieht folgendermaßen aus:
/ ** * Kurze Beschreibung (keine Periode für Dateiheader) * * Lange Beschreibung. * * @link URL * @since x.x.x (falls verfügbar) * * @package WordPress * @subpackage Component * /
Beachten Sie, dass wir dies in den Dateiköpfen tun nicht Geben Sie eine Periode an und es gibt zwei Bestandteile der Beschreibung:
Immer wenn ich diese für meine spezifischen Projekte schreibe, versuche ich mir vorzustellen, dass meine kurze Beschreibung etwas ist, das in die Spitze von passen könnte README Datei, das kann ein einzelner kurzer Höhenabstand für die Datei sein oder das kann sogar in etwas so kurz wie ein Tweet enthalten sein.
Die längere Beschreibung kann natürlich so detailliert sein, wie wir möchten. In diesem Fall gibt es ein bestimmtes Format, das wir für eine ausführliche Beschreibung verwenden sollten. Dies würde jedoch den Rahmen dieses Artikels sprengen, da wir im nächsten Artikel der Serie ein bestimmtes, praktisches Beispiel dafür finden werden.
benötigen AussagenGelegentlich müssen wir Code dokumentieren, der in einer Funktion oder Klasse enthalten ist. Diese unterscheiden sich von Funktionsdefinitionen oder Klassenvariablendefinitionen.
Stellen Sie sich diese stattdessen als Inline-Kommentare vor, wenn Sie eine bestimmte Abhängigkeit hinzufügen oder benötigen. Dies wird im Allgemeinen ein separates PHP-Skript sein.
Zum Beispiel:
/** * Kurze Beschreibung. (Zeitraum verwenden) * / requir_once (ABSPATH. '/filename.php');
Beachten Sie jedoch, dass dies laut Kodex der Fall ist nicht nur beschränkt auf Funktionsaufrufe wie einmalig benötigt.
Erforderliche oder mitgelieferte Dateien sollten mit einer kurzen Beschreibung des PHPDoc-Blocks dokumentiert werden. Optional kann dies für Inline-Aufrufe get_template_part () gelten, wenn dies zur Verdeutlichung erforderlich ist.
Da unser Plugin direkt externe Skripts anruft, haben wir werden Verwenden Sie dazu im nächsten Artikel ein praktisches Beispiel. Der Grund, warum ich es hier teile, ist nicht nur, uns auf das, was kommt, vorzubereiten, sondern auch das richtige Format zu zeigen, wie wir dies in jeder Strömung nutzen können, die wir möglicherweise tun.
Ich denke jedoch, dass die gesamte Dokumentation wichtig ist, und ich behaupte nicht, dass diese beiden Aspekte der wichtigste Teil der Dokumentation eines Plugins sind. Angesichts der Tatsache, dass unser Plugin objektorientiert ist, ist es jedoch wichtig, dass wir verstehen, wie wir sowohl unsere Klassen als auch unsere Funktionen ordnungsgemäß dokumentieren können.
Klassendefinitionen sind Codekommentare, die zwischen den Dateiheatern (die oben beschrieben wurden) und dem Namen der Klasse angezeigt werden.
Das Format, das zum Dokumentieren einer Klasse verwendet wird, lautet wie folgt:
/** * Kurze Beschreibung. (Zeitraum verwenden) * * Lange Beschreibung. * * @since x.x.x * * @see Funktion / Methode / Klasse stützte sich auf * @link URL * /
Wenn Sie sich den WordPress-Codex für diesen Artikel ansehen, werden Sie feststellen, dass er ein enthält wenig Weitere Informationen, die ich in die Dokumentation oben aufgenommen habe. Dies liegt daran, dass sie beide Klassen enthalten und Funktionsdefinitionen.
Stattdessen teilen wir jeden von ihnen in zukünftige Bereiche auf, damit wir später sehen können, weshalb wir im nächsten Artikel der Serie bestimmte Dinge auf bestimmte Weise dokumentieren werden.
Ähnlich wie bei Klassendefinitionen können Sie Folgendes erwarten:
/** * Kurze Beschreibung. (Zeitraum verwenden) * * Lange Beschreibung. * * @since x.x.x * @access (für Funktionen: nur für private Zwecke verwenden) * * @see Funktion / Methode / Klasse basiert auf * @link URL * @global type $ varname Kurzbeschreibung. * * @param type $ var Beschreibung. * @param type $ var Optional. Beschreibung. * @return type Beschreibung. * /
Beachten Sie im obigen Codekommentar, dass es sehr wenig Unterschiede zu dem gibt, was wir in der Klassendokumentation gesehen haben.
Zusätzlich zu den oben genannten Informationen sehen wir Informationen für:
Offensichtlich wird dieses Material normalerweise nicht im Kontext einer Klasse verwendet. Wie auch immer, es ist im Kontext einer Funktion verwendet.
Zu diesem Zweck können Sie sich die folgenden Punkte vorstellen:
global Variablen beziehen sich auf die Variablen, die im Kontext der Funktion verwendet werden und für die WordPress-Umgebung global sind. Dazu gehören Dinge wie $ post, $ authordata, und andere hier aufgelistet.@param Tag bezieht sich auf die Variablen, die eine Funktion akzeptiert. Offensichtlich umfasst dies den von ihr akzeptierten Variablentyp und eine Beschreibung, was die Variable darstellt.@Rückkehr Tag beschreibt den Typ einer von einer Funktion zurückgegebenen Variablen und eine kurze Beschreibung des zurückgegebenen Typs von Daten.Anstatt hier ein konkretes Beispiel zu nennen, werden wir dies im Folgeposting mit dem Code tun, den wir im vorherigen Post geschrieben haben.
Schließlich repräsentieren variable Eigenschaften - oder allgemein als Klasseneigenschaften (die manchmal als Attribute bezeichnet werden) die Daten, die in der Klasse enthalten sind.
Denken Sie daran, dass in früheren Abschnitten unserer Serie erwähnt wurde, dass Attribute den Adjektiven ähneln, die das Nomen beschreiben, das die Klasse darstellt.
Wie Sie dem vorherigen Artikel entnehmen können, werden Klasseneigenschaften direkt nach dem Namen der Klasse und vor dem Konstruktor definiert (unabhängig davon, ob es sich dabei um ein Attribut handelt) Öffentlichkeit oder Privatgelände).
Um diese Attribute zu dokumentieren, folgen wir der folgenden Vorlage:
/** * Kurze Beschreibung. (Zeitraum verwenden) * * @since x.x.x * @access (privat, geschützt oder öffentlich) * @var type $ var Beschreibung. * /
Leicht genug zu verstehen.
Einige mögen argumentieren, dass die Verwendung von @Zugriff ist frivol, da der Zugriffsmodifizierer der direkt auf den Kommentar folgenden Funktion den Typ der Funktion erläutert.
Hier unterscheiden sich die Unterschiede in den WordPress-Dokumentationsstandards jedoch von einigen der PHP-Standards (sowohl vorhanden als auch diejenigen, die gerade standardisiert werden)..
Kurz gesagt bezieht sich PSR auf die von der PHP Framework Interop Group vorgeschlagenen PHP-Standardempfehlungen.
Über jeden dieser Standards können Sie hier nachlesen:
Welches PSR-5 wird gerade diskutiert. Dies ist wichtig für alle PHP-Entwickler, unabhängig von der verwendeten Plattform oder Grundlage, aber ich denke auch, dass es die Unterschiede (und Ähnlichkeiten) zwischen PSR und den WordPress-Standards gibt sind Unterschiede.
Dies ist ein Punkt der Unstimmigkeit. Was ich jetzt sagen möchte, ist rein subjektiv. Ich bin jedoch der Meinung, dass Sie, wenn Sie mit WordPress arbeiten, die von WordPress vorgeschlagenen Konventionen beachten sollten.
Dies bedeutet nicht, dass wir uns nicht darum bemühen sollten, uns enger an das zu orientieren, was die größere PHP-Community tut. Wenn wir jedoch WordPress-Code für andere WordPress-Entwickler schreiben, sollten wir uns in erster Linie darauf konzentrieren.
Im nächsten Artikel werden wir einen Blick auf die Anwendung der oben genannten Prinzipien im Kontext unseres Plugins werfen.
Dies sollte uns dabei helfen, nicht nur ein Plugin zu erstellen, das den WordPress-Codierungsstandards in hohem Maße entspricht, sondern auch den Dokumentationsstandards, so dass wir, unsere Benutzer und unsere zukünftigen Mitwirkenden den Kontrollfluss während des Projekts problemlos verfolgen können.
In der Zwischenzeit können Sie Fragen und / oder Kommentare im untenstehenden Feed hinterlassen!
