opțiuni de cazare pentru documentare
Să ne uităm la documentația în afara codului. Deși nu este scopul acestui articol. În proiecte open source nu este o practică mai puțin frecvente pentru articolele de documentare sunt stocate în același depozit ca și codul de bază. De exemplu, în bibliotecă pentru a genera un fals luminări web pentru documentația PHP plasate în fișierul README; pentru a citi până la sfârșit, ai nevoie de un pic poskrolit. Populare HTTP client pentru PHP guzzle magazine instrucțiuni de utilizare în diferite fișiere într-un dosar documente separate. A se păstra documentația lângă codul - este cu siguranță frumos și confortabil. Odată ce furnizorul pachetului descărcat, aveți atât de cod și documentație. În cazul în care biblioteca este mică, în cazul în care este stabilă și nu implică în viitor schimbări constante API care implică o constantă a documentelor re-scriere, atunci puteți plasa în siguranță documentele în depozitul proiectului.
Omite punerea în aplicare a acestei interfețe, doar a crea un nou obiect dintr-o clasă de iepure:
Rabbit - un substantiv, alerga - verbul, în metri - contextul pe care îl adăugați metoda de a transmite esența acesteia. Folosind acest sistem, puteți scrie metode
Dar acest lucru este deja prea mult:
Există, totuși, excepții de la lungimea numelor metodelor. De exemplu, atunci când scrieți un spec pe phpSpec. nu te poate limita la metoda de lungime, principalul lucru pe care el a trecut întregul punct. Aici este un exemplu de cod, luate din phpSpec documentare:
SPECA pentru nume de metode care utilizează înregistrarea subliniere. astfel încât este mai ușor pentru a prinde ochiul dincolo de cuvinte și de a citi o propoziție lungă. Acest lucru nu este PSR standard, în cazul în care CamelCase utilizat. dar pentru teste de lizibilitate astfel de opțiune este ideală.
Un simț al proporției în numele metodei vine cu timpul, cu experienta. Puteți bau, așa cum se face în populare cadrele și biblioteci.
inconsecvență
redundanță
Nefiabilitate
inventivă
Nu se știe când sau termeni evidente sunt folosite pentru a codifica o anumită locație.
Scrie, dar trebuie să își asume responsabilitatea pentru ei. Aici sunt momente când acestea sunt necesare.
conținut informațional
Aceeași problemă în limbajul de programare poate fi rezolvată în mai multe moduri. Programatorul are propriul stil de programare și de a face cunoștință cu codul unui alt programator cu un stil diferit, poate fi greu pentru a citi codul „în diagonală“. Dacă aveți orice stil de programare speciale, sau știu din experiență că algoritmii pe care le utilizați, este dificil de citit de altă parte, apoi lăsați indicii în codul imediat înainte de începerea unei piese complexe de cod.
avertismente
Nu documentează cod rău - l rescrie.
Folosind dokblokov Documentarea
Dokblokom poate fi o singură linie, atâta timp cât aceasta începe cu / **.
Dokbloki atât de obișnuiți cu kommyuniti PHP-programatori, care pregătește PSR-5 pe baza lor (Recomandarea PHP Standard). La momentul scrierii acestui articol, el era încă în stadiul de proiect.
PHP prin dokblokov se poate documenta următoarele elemente:
De asemenea, este important ca o dokblok poate fi aplicată numai un element structural. Ie pentru fiecare funcție - dokblok dvs., o variabilă în funcție - lui, pentru clasa - o.
În phpdoc există multe tag-uri, dar nu orice etichetă se aplică tuturor elementelor structurale. Mai jos este o listă de tag-uri existente, domeniul de utilizare și explicații.
Tag-uri perimate, cel mai probabil, nu va fi susținută în viitor:
- @category (fișier, clasa) - utilizat pentru pachete de grup împreună.
- @subpackage (fișier, clasă) - este utilizat pentru izolarea anumitor grupuri în pachete.
Nu toate etichetele sunt la fel de populare, sunt cel mai des folosite: @var, @param, @return, @todo, @throws. altele - mai puțin. Și, cum ar fi @property și @method eu, în general, nu au îndeplinit în cerere, pentru că „magie de lucru“ în PHP - este periculos :)
Ușor de utilizat dokblokov în IDE
Dacă sunteți în curs de dezvoltare un proiect open source, apoi documentat desigur API publice folosind dokblokov necesare. Acest lucru nu numai că va permite să generați o documentație gata, dar, de asemenea, vă permite să utilizați codul este convenabil pentru alți dezvoltatori în IDE lor. În ceea ce privește codul privat externalizeze proiectului, utilizarea dokblokov nu pare foarte potrivit, cu toate acestea, le sfătui să folosească, aceasta va accelera dezvoltarea ta.
De exemplu, să ia cele mai populare IDE pentru PHP - PhpStorm. Luați în considerare exemplul anterior de iepuri de căutare:
Că magazin o variabilă $ iepuri și $ iepure. PhpStorm despre ea nu știe nimic. PHP - limbaj slab tastat, tipul de rezultat al funcției nu este definită strict din descrierea acestuia (Bună ziua PHP7, în cazul în care acesta va fi pus în aplicare). Prin urmare, IDE-ul trebuie să determine utilizarea dokblokov cum să se comporte cu un anumit cod. Există mai multe opțiuni. Puteți face acest lucru:
@return sau adăugați o etichetă la o metodă findRabbitsInLocations:
Vă rugăm să rețineți că am indicat Rabbit []. în loc de iepure. Consolele în mod clar că returnează o matrice de obiecte de clasa de iepure. dacă vom elimina paranteze pătrate, va însemna că metoda returnează o singură instanță a Rabbit. Totuși este posibil să se scrie astfel încât @return nul | Rabbit []. băț vertical este „OR“, în acest caz, precizăm că metoda returneaza un array fie iepuri sau nul.
Indiferent ce metodă de a specifica tipul pe care o alegeți, PhpStorm va acorda acum vă indicii atunci când tastați $ rabbit-> și așteptați un moment:
Acest lucru se întâmplă pentru că PhpStorm știe că, în $ iepurii variabilă returnează o matrice de obiecte de clasa de iepure. Mai mult, în bucla foreach variabila $ iepure devine un element de matrice, care este un exemplu de iepure și PhpStorm vă arată disponibile la metodele publice ale acestei clase.
Astfel, nu se uita în sus de la tastatură, puteți utiliza clase cu metode publice care au scris colegii. PhpStorm vă va da un indiciu, iar în cazul în care metoda se numește este clar, îl puteți folosi chiar și fără a citi codul sursă și documentația.
O altă caracteristică utilă dokblokov asociat cu PhpStorm - este de avertizare cu privire la parametrii de intrare greșite. Umple dokblok una dintre metodele de iepure:
Aici subliniem că de intrare trebuie să vină întreg (din nou, în PHP7 va fi posibil să se stabilească nivelul de sintaxa limbii). Ce se întâmplă dacă vom trece această metodă o matrice?
PhpStorm oferă culoare și vă va da un indiciu că de intrare este de așteptat să int. și vă transmite matrice. Convenabil, nu-i așa? Aceleași sfaturi vor fi emise și inconsistența clase, interfețe. Dacă metoda dvs. acceptă mai multe tipuri de argumente de intrare, le separa și prin |. În acest exemplu, în cazul în care runInMetres (), metoda este, de asemenea, posibilitatea de a procesa matrice, atunci putem adăuga dokblok «@param int | matrice $ Contoare» PhpStorm și mai înjura.
Pentru a minimiza disconfortul, aveți nevoie pentru a face fiecare membru al echipei pentru a include setări de inspecție PhpStorm dokblokov> Editor> Inspecțiile> phpdoc și a remarcat că toate căpușele:
Deci, ar trebui să utilizați PHP CodeSniffer (phpcs) cu un cod adecvat de stilul tau. Nu sunt sigur ce despre toate codul pentru Style, dar pentru Symfony dokbloki sunt obligatorii. Prin urmare, phpcs în furtună vă va emite un avertisment pe zbor. Setările sunt făcute în același loc, dar există încă o instrucțiune suplimentară.
Desigur, nu face toata lumea 100% sa respecte regulile. Dar, mai ales Lenesii poate fi încărcat cu mai mult de un citat din cartea „Codul curat“, cu toate acestea, nu se mai tratează codul de formatare, dar sensul este același:
„Regulile trebuie să fie respectate de către toți membrii grupului. Acest lucru înseamnă că fiecare membru al grupului ar trebui să fie suficient de rezonabil pentru a realiza că, indiferent de modul în care este pus aparat dentar, cu excepția cazului în toată lumea a fost de acord să le plaseze în același mod. "
Generarea documentatiei folosind phpDocumentor
Acum, că toate să adere la regulile și codul dvs. este acoperit dokblokami poate genera documentație. Adu toată documentația pentru phpDocumentor nu va, numai comenzile minime de odihnă pe site-ul oficial.
Deci, trebuie să instalați phpDocumentor. Se poate livra la nivel global, astfel:
Sau adăugați ca dependență în composer.json proiectul dumneavoastră.
Și acum, fiind în directorul proiectului pe care le-ați acoperit dokblokami, trebuie doar să rulați de la consola:
Așa cum am menționat, acest lucru este setul minim de activități pentru a genera documentare, src opțiunea -d / indică calea către fișierele pe care doriți să le procesați. Documentația generată va fi creat în directorul de ieșire. Desigur, acest utilitar are diferiți parametri și diferite lucruri ea știe. O documentație generată aspect va fi așa. puteți selecta un șablon existent sau pentru a crea propriul.
Generarea de documentare folosind Sami
Un alt instrument pentru a genera PHP pe bază de documentare dokblokov - utilitate Sami. Poate că nu este la fel de bine cunoscut, dar am decis să-l menționez, pentru că, cu ajutorul documentației Sami generate de iubitul Symfony nostru. Și el a scris acest utilitar Fabien Potencier, și a scris despre ea o dată pe blogul său.
Sami generator de documentare diferă de phpDocumentor prin aceea că configurația sa este stocată în PHP-fișiere. În general, Sami perfecționa pentru tine poate fi mult mai abruptă decât phpDocumentor, dar va trebui să facă mânere, și anume scrie un cod. Există chiar posibilitatea de a redefini diferitele piese de cod care sunt responsabile pentru generarea de documentare. Și pe TWIG'e Șabloanele suprascriere convenabil. Mai pot face cunoștință cu Sami de pe pagina de magaziei pe GitHub.