Share
În acest moment al seriei, am acoperit o mulțime de materiale - nu numai că am acoperit elementele de bază ale programării orientate pe obiecte, dar am început să construim un plugin complet funcțional.
Dar provocarea care vine cu munca pe care am făcut-o până acum este că nu include nicio documentație despre cum funcționează plugin-ul. Dacă vă reamintiți din articolul precedent, am luat o decizie de dezvoltare conștientă pentru a amâna această caracteristică.
Începând cu acest articol, vom analiza modul în care se documentează pluginurile WordPress și cum putem face acest lucru având în vedere pluginul nostru actual.
Înainte de a continua cu restul acestui articol, vă îndemn foarte mult să vă recuperați conținutul pe care l-am acoperit până acum. După cum se menționează în fiecare articol din trecut, fiecare articol se bazează pe articolul precedent din serie.
Cu asta am spus că este timpul să ne îndreptăm atenția asupra documentării plugin-ului nostru, dar înainte de a merge și a face acest lucru, trebuie să ne asigurăm că înțelegem pe deplin standardele care sunt în vigoare pentru a ne documenta munca.
Deci, înainte de a furniza comentariile relevante pentru plugin-ul nostru, vom analiza ce trebuie să includem. După aceea, vom analiza exact ceea ce facem pentru pluginul nostru în următorul articol.
Pentru început, Codul WordPress include un manual special pentru standardele de documentare PHP. Puteți citi standardele în întregime; cu toate acestea, vom sublinia cele mai importante caracteristici ale ceea ce vom implementa în următorul articol.
Lucrurile principale cu care ne ocupăm de documentare sunt următoarele:
Accentsconagua
necesita declaraţiiAcest lucru va fi, evident, un set de articole mult mai lent decât cele din ultimele două, dar având în vedere volumul de muncă pe care l-am acoperit până acum, ar trebui să fie o schimbare binevenită a ritmului pentru unii cititori.
Cu ce a spus asta, să începem.
Fișierele antetului sunt unice în faptul că ele sunt ceva care ar trebui să să fie plasate în fiecare fișier al fișierelor care alcătuiesc un plugin (sau o temă, dar nu este în centrul acestei serii), dar acestea nu sunt întotdeauna.
Conform Codului:
Blocul de antet al fișierului PHPDoc este folosit pentru a oferi o imagine de ansamblu a conținutului fișierului.
Șablonul general pe care îl vom folosi începând cu următorul articol arată astfel:
/ ** * Scurtă descriere (fără perioadă pentru anteturile de fișiere) * * Long Description. * * @link @link @ * din x.x.x (dacă este disponibil) * * @pachet WordPress * @subpackage Component * /
Rețineți că în anteturile de fișiere, noi facem nu include o perioadă și există două componente ale descrierii:
Ori de câte ori le scriu pentru proiectele mele specifice, încerc să-mi imaginez scurta descriere a mea dacă ceva care se potrivește în partea de sus a lui CITEȘTE-MĂ fișier, care poate fi un singur pas de ascensiune scurt pentru fișier, sau asta Mai chiar să fie conținută în ceva atât de scurt ca un tweet.
Descrierea mai lungă, desigur, poate fi la fel de ușor de detaliat pe cât ne place. În acest caz, există un format specific pe care ar trebui să-l folosim pentru o descriere lungă, dar acest lucru depășește sfera acestui articol special, deoarece vom vedea un exemplu particular și practic al acestui lucru în următorul articol din seria.
necesita declaraţiiOcazional, avem nevoie să documentăm codul care este inclus într-o funcție sau într-o clasă. Acestea sunt diferite de definițiile funcțiilor sau de definițiile variabilelor de clasă.
În schimb, gândiți-vă la acestea ca la comentarii inline pentru momentul în care trebuie să includeți sau să solicitați o anumită dependență. Acesta va fi, în general, un script PHP diferit față de orice altceva.
De exemplu:
/** * Scurta descriere. (perioada de utilizare) * / require_once (ABSPATH. '/filename.php');
Cu toate acestea, rețineți că în conformitate cu Codul că acesta este nu limitat doar la apelurile de funcții cum ar fi require_once.
Fișierele necesare sau incluse ar trebui să fie documentate cu o scurtă descriere a blocului PHPDoc. Opțional, acest lucru se poate aplica apelurilor in-line get_template_part () necesare pentru claritate.
Deoarece pluginul nostru face apeluri direct la scripturi externe, noi voi utilizați un exemplu practic în acest articol. Motivul pentru care îl împărtășesc aici nu este doar să ne pregătească pentru ceea ce vine, ci și să arătăm formatul adecvat pentru modul în care să folosim acest lucru în orice moment pe care îl putem face.
Deși cred că toată documentația este importantă și nu susțin că aceste două aspecte sunt cea mai importantă parte a documentării unui plugin; cu toate acestea, având în vedere faptul că pluginul nostru este orientat pe obiect în natură, este esențial să înțelegem cum să documentăm corect atât clasele noastre, cât și funcțiile noastre.
Definițiile de clasă sunt comentariile de cod care apar între anteturile de fișiere (pe care le-am discutat mai sus) și numele clasei.
Formatul utilizat pentru a documenta o clasă este după cum urmează:
/** * Scurta descriere. (perioadă de utilizare) * * Descriere lungă. * * @ din x.x.x * * @see Funcție / metodă / clasă bazată pe * @link URL * /
Dacă se întâmplă să te uiți la WordPress Codex pentru acest articol, veți observa că acesta oferă o puțin mai multe informații pe care le-am inclus în documentația de mai sus. Acest lucru se datorează faptului că au inclus conținut atât de clasă și funcții.
În schimb, distrugem fiecare dintre ele în zone separate pentru referințe viitoare și pentru a vedea de ce vom documenta anumite lucruri în anumite moduri în următorul articol din seria.
Similar cu definițiile de clasă, pe care le puteți aștepta să vedeți următoarele:
/** * Scurta descriere. (perioadă de utilizare) * * Descriere lungă. * * @ din x.x.x * @ acces (pentru funcții: folosiți numai dacă privat) * * @see Funcție / metodă / clasă bazată pe * @link @ URL * @global type $ varname Scurtă descriere. * * @param type $ var Descriere. * @param tip $ var Opțional. Descriere. * @return type Descriere. * /
Observați în comentariul de mai sus, este foarte mică diferența față de ceea ce am văzut cu documentația din clasă.
În plus față de cele de mai sus, vedem informații pentru:
Evident, acest lucru este material nu este folosit în mod obișnuit în contextul unei clase; cu toate acestea, aceasta este utilizate în contextul unei funcții.
În acest scop, iată cum vă puteți gândi la fiecare dintre cele de mai sus:
global variabilele se referă la acele variabile care sunt utilizate în contextul funcției globale pentru mediul WordPress. Acestea includ lucruri cum ar fi $ postare, $ authordata, și altele listate aici.@param tag se referă la variabilele pe care le acceptă o funcție. Evident, acesta include tipul de variabilă pe care îl acceptă și o descriere a variabilei.@întoarcere tag-ul discută tipul de variabilă pe care o funcție o returnează și o scurtă descriere cu privire la tipul de date care sunt returnate.Mai degrabă decât să dăm un exemplu concret aici, vom face acest lucru în postul de urmărire cu codul pe care l-am scris în postul anterior.
În cele din urmă, proprietățile variabilei - sau mai des cunoscute ca proprietăți ale clasei (care sunt uneori numite atribute), reprezintă datele păstrate în cadrul clasei.
Amintiți-vă din mai devreme în seria noastră, am menționat că atributele sunt ca adjectivele care descriu substantivul pe care îl reprezintă clasa.
După cum puteți vedea din articolul precedent, proprietățile clasei sunt definite imediat după numele clasei și înainte de constructor (indiferent dacă este public sau privat).
Pentru a documenta aceste atribute, urmăm următorul șablon:
/** * Scurta descriere. (perioadă de utilizare) * * @ din x.x.x * @ acces (privat, protejat sau public) * @var tip $ var Descriere. * /
Destul de ușor de înțeles.
Unii pot argumenta că utilizarea @acces este frivolă, deoarece modificatorul de acces al funcției care urmează imediat după comentariu explică tipul de funcție pe care este.
Dar aici diferențele în standardele de documentație WordPress diferă de unele standarde PHP (atât în vigoare, cât și cele care sunt în proces de a fi standardizate).
Pe scurt, PSR se referă la recomandările standard PHP, propuse de grupul PHP Framework Interop.
Puteți citi despre fiecare dintre aceste standarde aici:
Ce PSR-5 se discută chiar acum. Acestea sunt importante de urmat pentru toți dezvoltatorii de PHP, indiferent de platforma sau fundația pe care o folosesc, dar cred că este de remarcat faptul că diferențele (și asemănările) existente între PSR și standardele WordPress, sunteți diferențele.
Acesta este un punct de dezacord, deci ceea ce voi spune este pur subiectiv; cu toate acestea, eu sunt de gândire că, atunci când lucrați în cadrul WordPress, ar trebui să urmați convențiile, astfel cum a fost propus de WordPress.
Aceasta nu înseamnă că nu ar trebui să facem eforturi pentru a ne alinia mai bine cu ceea ce face comunitatea mai mare PHP; cu toate acestea, dacă scriem codul WordPress pentru alți dezvoltatori WordPress, atunci acesta este un lucru pe care ar trebui să ne concentrăm în primul rând.
În următorul articol, vom analiza aplicarea principiilor de mai sus în contextul pluginului nostru.
Acest lucru ar trebui să ne ajute nu numai să construim un plugin care să fie în conformitate cu standardele de codare WordPress, dar și cu standardele de documentare, astfel încât noi, utilizatorii noștri și viitorii colaboratori să putem urmări cu ușurință fluxul de control prin intermediul proiectului.
Între timp, nu ezitați să lăsați orice întrebări și / sau comentarii în feedul de mai jos!
