Documentația proiectului cu ajutorul phpdocumentor - dezvoltare site-uri si rafinament - php

Documentarea proiectului cu ajutorul phpDocumentor

Necesită PHP 5.3.3+.

Setați extensia php-Intl (internaționalizare) și software-ul grafic de desen pentru Graphviz (comanda la Ubuntu / Mint).

pachetul de instalare PhpDocumentor cu ajutorul compozitorului.

Poate set de PEAR (setare provizoriu în sine pere). În cazul în care nu este instalat, executați de instalare cu opțiunea -Z. A alerga afară de rădăcină, de asemenea.

Sau pur și simplu descărcați Phar aici.

Și acum dezlănțuit phpDocumentor, de exemplu, pe un standard de instalare ocStore 1.5.5.1. Rețineți că puteți utiliza proiectul terminat. OcStore am instalat în directorul / home / utilizator / public_html / ocstore, unde utilizatorul - numele de utilizator, și documentația vom păstra la fel și în directorul docs (în cazul în care nici unul, phpDocumentor-l crea eu). Un proces lung, am luat mai mult de o jumătate de oră.

Nu este nici un secret faptul că OpenCart / ocStore nu documentată în nici un fel. Cu toate acestea, vom vedea o listă a tuturor claselor, iar dacă faceți clic pe diagrama ierarhie Sharts / Clasa în colțul din dreapta sus, putem chiar și o ierarhie de clasă într-o formă grafică pentru a contempla (și spectacol de coșmar este absolut inutil în acest caz).

Cu toate acestea, este mai bine decât nimic. Făcând clic pe orice clasă, de exemplu, ControllerCatalogCategory, puteți obține informații despre toate metodele și proprietățile acestei clase, precum și (în dreapta), în cazul în care fișierul este acea clasă și ierarhia.

Aici vom folosi tag-ul @var. determinarea tipului clasei de proprietate.

Acum documentează metoda, de exemplu, getCategories () (acest lucru este în cazul în care există parametri fără forme legale).

Aici am folosit @param tag-uri și @return. Primul parametru descrie o metodă (de tip), al doilea - valoarea returnată

Reporniți procesul de creare a documentației (încă o dată, am act de faptul că procesul este foarte lung).

Am actualizat pagina de clasă ControllerCatalogCategory și a vedea că au existat multe lucruri interesante.

În primul rând, a existat o descriere a clasei. și prima linie a unității de andocare a fost subtitrarea cu italice.

În al doilea rând, o descriere a tipurilor și proprietățile unei clase.

getCategories În cele din urmă, suntem acum bine documentate () metoda.

În procesul de creare a documentației, vom obține o mulțime de avertismente. Ea phpDocumentor ne avertizează cu privire la toate clasele fără acte, metode și proprietăți. Costă ne documentului lor - și odihnă phpDocumentor. Obiectivele documentului de ocStore noi nu facem, ci fac un obicei documentare, astfel, fiecare proiect nu poate face rău.

se concentreze separat pe prevenire „Nu rezumat a fost găsit pentru acest fișier“. Adevărul este că, deși această practică nu este încurajată, în principiu, un singur fișier poate avea mai mult de o clasă. Prin urmare, phpDocumentor necesară la începutul fișierului unei unități de andocare separată pentru întregul fișier. În general, este posibil să se vtulit unele informații, de licență, de exemplu. Cu @license tag-ul.