Dokumentace je jednou z klíčových částí softwarových projektů. Může se jednat o různé typy dokumentace – uživatelská, zadávací, testovací, akceptační, auditní, ale také ta technická. A právě o ní bude řeč. A to konkrétně v kontextu PHP. Samozřejmě se ale dají základní koncepty, které zde budu popisovat, vztáhnout i na jiné programovací jazyky. Důležité je ale začít. A to hned!
Psaní dokumentace nemusí být opruz, protože nám v tom může pomoci mnoho nástrojů. V tomto článku si jeden takový ukážeme. Jednoduše, na jeden příkaz vyextrahuje a vygeneruje dokumentaci projektu. Řeč je o nástroji phpDocumentor.
Instalace
Podle dokumentace je instalace docela přímočará. Stačí si stáhnout .phar soubor, nainstalovat pomocí Phive nebo stáhnout a spustit Docker image. Sám tvůrce nedoporučuje stahovat do projektu prostřednictvím Composer. Kvůli rozmanitým tým závislostem by mohlo dojít k častým kolizím s knihovnami a balíky, jež používá váš projekt.
Ukážeme si tedy první zmíněnou metodu – soubor .phar. Tento formát je PHP archiv a dovolí nám zabalit celou PHP aplikaci s více komponentami do jednoho souboru pro jednoduchou následnou distribuci. phpDocumentor stáhneme tedy z oficiálních stránek a uložíme k nám na disk. Osobně bych jej neukládal do žádného konkrétního projektu, ale třeba do nadřazeného adresáře, kde máte všechny vaše PHP projekty. Soubor vám totiž stačí pro celý systém jeden a můžete pomocí něj generovat dokumentaci pro libovolný projekt.
Vygenerování dokumentace
Poté, co máme k dispozici phpDocumentor v našem systému, stačí vybrat projekt, ze kterého chceme dokumentaci vyextrahovat a pustit jednoduchá příkaz:
php phpDocumentor.phar -d CESTA/K/PROJEKTU -t CESTA/KAM/VYGENERUJE/DOKUMENTACI
Konkrétně si to můžeme ukázat na Symfony projektu, který má zdrojové PHP soubory ve složce ROOT/src. Příkazu předáme minimálně dva parametry – zdrojový adresář (-d) a cílový adresář (-f). Poté může příkaz vypadat třeba takto:
php phpDocumentor.phar -d simu-portfolio/src -t php-doc/simu-portfolio
Po zavolání tohoto příkazu je vidět postup generování dokumentace. Příklad je uveden ve Windows, ale úplně stejné použití je i na Linux a Mac. Po doběhnutí (pár sekund) je v adresáři ./ php-doc/simu-portfolio vygenerována naše dokumentace.
Jak dokumentaci použít
Když přistoupíme do zmíněného adresáře, tak zde nalezneme složitější adresářovou strukturu (styly, indicie, atd.) a zejména soubor index.html. Nemusíme se v tuto chvíli starat o to, co se kde nachází a stačí otevřít index.html v prohlížeči. Tadá! A můžeme prohlížet, co v projektu máme.
Dokumentace je automaticky vygenerovaná z dostupných tříd, metod a PHP anotací. Pokud tedy dodržujeme dobré zásady psaní kódu a již při programování myslíme na přehlednou strukturu jednotlivých součástí zdrojáku, tak i dokumentace bude dávat smysl. Do PHP anotací není třeba psát eseje o tom, co daná metoda dělá. Stačí stručný popis a následně napoví název metody, datové typy parametrů a návratových hodnot a další.
Dostupný je i přehled případných deprecations a chyb. Hodně pomůže i boční navigace obsahující existující jmenné prostory a fulltextové vyhledávání, které nalezneš v pravém horním rohu.
Samozřejmě lze nástroj dále konfigurovat a vymačkat tak z něj maximum, tady tě ale už odkážu na oficiální dokumentaci projektu, kde se dozvíš, co potřebuješ. Teď už budeš mít dokumentaci vždycky po ruce!
