Share
Vid denna tidpunkt i serien har vi täckt mycket material - inte bara har vi täckt grunderna i objektorienterad programmering, men vi har också börjat bygga ett fullt fungerande plugin.
Men utmaningen som följer med det arbete som vi har gjort så här långt är att det inte innehåller någon dokumentation om hur plugin faktiskt fungerar. Om du kommer ihåg från föregående artikel, fattade vi ett medvetet utvecklingsbeslut att skjuta upp den här funktionen.
Början i den här artikeln kommer vi att ta en tvådelad titt på hur man dokumenterar WordPress-plugins och hur vi kan göra det med tanke på vårt nuvarande plugin.
Innan du fortsätter med resten av den här artikeln uppmanar jag dig att hämta det innehåll som vi har täckt hittills. Som nämnts i varje tidigare artikel bygger varje artikel på den föregående artikeln i serien.
Med det sagt är det dags att göra vår uppmärksamhet åt att dokumentera vårt plugin, men innan vi fortsätter och gör det måste vi se till att vi fullt ut förstår de standarder som finns för att vi ska dokumentera vårt arbete.
Så innan vi lämnar kommentarer som är relevanta för vårt plugin ska vi titta på vad vi behöver inkludera. Därefter ser vi på att göra exakt det för vårt plugin i nästa artikel.
Till att börja med innehåller WordPress Codex en handbok specifikt för PHP Documentation Standards. Du kan läsa standarderna i sin helhet; Vi kommer emellertid att lyfta fram de viktigaste funktionerna i vad vi ska genomföra i nästa artikel.
De primära sakerna som vi är berörda med att dokumentera är följande:
Accentsconagua
fordra uttalandenDetta kommer givetvis att vara en mycket långsammare uppsättning artiklar än de föregående två, men med tanke på den mängd arbete som vi har täckt hittills, bör det vara en välkommen förändring av takten för vissa läsare.
Så med det sagt, låt oss börja.
Filhuvuden är unika i det faktum att de är något som skall placeras i varje fil i filerna som utgör ett plugin (eller ett tema, men det är inte fokus för denna serie), men de är inte alltid.
Enligt Codex:
PHPDoc-filhuvudblocket används för att ge en översikt över vad som finns i filen.
Den allmänna mallen som vi börjar använda i nästa artikel ser ut så här:
/ ** * Kort beskrivning (ingen period för filhuvud) * * Lång beskrivning. * * @länkadress * @since x.x.x (om tillgänglig) * * @package WordPress * @subpackage Komponent * /
Observera att vi i filhuvudena gör det inte Inkludera en period och det finns två komponenter i beskrivningen:
När jag skriver ut dessa för mina specifika projekt försöker jag föreställa mig att min korta beskrivning om något som kan passa i toppen av README fil, det kan vara en enda, kort hissnivå för filen eller den Maj ens innehålla något så kort som en tweet.
Den längre beskrivningen kan naturligtvis vara lika lättare som vi vill. I det här fallet finns det ett specifikt format som vi ska använda för lång beskrivning, men det ligger utanför tillämpningsområdet för den här artikeln eftersom vi får se ett särskilt praktiskt exempel på detta i nästa artikel i serien.
fordra uttalandenIbland har vi behov av att dokumentera kod som ingår i en funktion eller en klass. Dessa skiljer sig från funktionsdefinitioner eller klassvariabla definitioner.
Tänk istället på dessa som inline kommentarer för när du behöver inkludera eller kräva ett visst beroende. Detta kommer i allmänhet att vara ett separat PHP-skript över allt annat.
Till exempel:
/** * Kort beskrivning. (användningsperiod) * / require_once (ABSPATH. '/filename.php');
Observera dock enligt Codex att detta är inte bara begränsad till funktionssamtal som require_once.
Filer som krävs eller ingår bör dokumenteras med ett kort beskrivning av PHPDoc-blocket. Eventuellt kan detta gälla för inline get_template_part () samtal som behövs för tydlighet.
Eftersom vårt plugin gör samtal direkt till externa skript, vi kommer använd ett praktiskt exempel på detta i nästa artikel. Anledningen till att jag delar den här här är inte bara att förbereda oss för vad som kommer, men också att visa rätt format för hur man kan utnyttja detta i någon ström som vi kanske gör.
Även om jag tycker att all dokumentation är viktig, och jag hävdar inte att dessa två aspekter är den viktigaste delen av att dokumentera ett plugin. Men med tanke på att vår plugin är objektorienterad i naturen är det viktigt att vi förstår hur man korrekt dokumenterar både våra klasser och våra funktioner.
Klassdefinitioner är kodkommentarer som visas mellan filhuvudena (som vi diskuterade ovan) och namnet på klassen.
Formatet som används för att dokumentera en klass är som följer:
/** * Kort beskrivning. (användningsperiod) * * Lång beskrivning. * * @since x.x.x * * @see Funktion / metod / klass åberopas * @link URL * /
Om du råkar titta på WordPress Codex för den här artikeln kommer du märka att den ger en liten mer information som jag har med i dokumentationen ovan. Detta beror på att de har inkluderat innehåll både i klassen och funktionsdefinitioner.
Istället bryter vi var och en ut i separata områden för framtida referens och så att vi kan se varför vi kommer att dokumentera vissa saker på vissa sätt i nästa artikel i serien.
Liknande klassdefinitioner, som du kan förvänta dig att se följande:
/** * Kort beskrivning. (användningsperiod) * * Lång beskrivning. * * @since x.x.x * @access (för funktioner: använd endast om privat) * * @see Funktion / metod / klass åberopat * @link URL * @global typ $ varname Kort beskrivning. * * @param typ $ var Beskrivning. * @param typ $ var Valfritt. Beskrivning. * @return typ Beskrivning. * /
Observera i kodkommentaren ovan, det är väldigt liten skillnad i vad vi såg med klassdokumentation.
Utöver vad som står ovan ser vi information för:
Självklart är detta material inte vanligtvis används inom ramen för en klass; dock det är används inom ramen för en funktion.
För det ändamålet, så här kan du tänka på var och en av ovanstående:
global variabler hänvisar till de variabler som används inom ramen för den funktion som är global till WordPress-miljön. Detta inkluderar saker som $ post, $ authordata, och andra listade här.@param taggen avser de variabler som en funktion accepterar. Självklart inkluderar detta typen av variabel som den accepterar och en beskrivning av vad variabeln representerar.@lämna tillbaka taggen diskuterar typen av variabel som en funktion returnerar och en kort beskrivning av vilken typ av data som returneras.I stället för att ge ett konkret exempel på detta här gör vi det i uppföljningsinsatsen med koden vi skrev i föregående inlägg.
Slutligen representerar variabla egenskaper - eller mer allmänt kända som klassegenskaper (som ibland kallas attributter) de data som hålls inom klassen.
Kom ihåg från tidigare i vår serie, nämnde vi att attribut är som adjektiv som beskriver substantivet som klassen representerar.
Som du kan se från föregående artikel definieras klassegenskaper strax efter namnet på klassen och före konstruktören (oavsett om dess offentlig eller privat).
För att dokumentera dessa attribut följer vi följande mall:
/** * Kort beskrivning. (användningsperiod) * * @since x.x.x * @access (privat, skyddad eller offentlig) * @var typ $ var Beskrivning. * /
Lätt nog att förstå.
Vissa kan hävda att användningen av @tillgång är frivolous eftersom åtkomstmodifieraren av funktionen direkt efter kommentaren förklarar vilken typ av funktion det är.
Men det är här skillnaderna i WordPress-dokumentationsstandarder skiljer sig från några av PHP-standarderna (både på plats och de som håller på att standardiseras).
Kort sagt, PSR hänvisar till PHP-standard rekommendationer som föreslagits av PHP Framework Interop Group.
Du kan läsa om var och en av dessa standarder här:
Vilken PSR-5 diskuteras just nu. Det här är viktigt att följa för alla PHP-utvecklare, oavsett vilken plattform eller fundament de använder, men jag tycker också att det är värt att notera att skillnaderna (och likheterna) som finns mellan PSR och WordPress-standarderna som där är skillnader.
Det här är en oenighet, så det jag bara säger är rent subjektivt. Jag är emellertid av tankegången att när du arbetar inom WordPress bör du följa de konventioner som föreslås av WordPress.
Detta ska inte säga att vi inte borde göra ansträngningar för att bättre anpassa oss till vad det större PHP-samhället gör. Om vi skriver WordPress-kod för andra WordPress-utvecklare, är det dock något som vi i första hand bör fokusera på.
I nästa artikel kommer vi att ta en titt på att tillämpa ovanstående principer inom ramen för vårt plugin.
Detta bör hjälpa oss att inte bara bygga ett plugin som överensstämmer högt med WordPress-kodningsstandarderna, men också till dokumentationsstandarderna så att vi, våra användare och våra framtida bidragsgivare lätt kommer att kunna följa kontrollflödet genom hela projektet.
Under tiden kan du lämna några frågor och / eller kommentarer i foderet nedan!
