PHP dokumentace,
automaticky a přehledně

IT vývoj

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í 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.

Příkazová řádka
Obrázek 1. Postup generování dokumentace ve Windows

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.

PHP documentator
Obrázek 2. Výsledná vygenerovaná dokumentace

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!

Čtěte dál Tyto články vám nesmí uniknout

Typografie

Redakce

Typografie Tituly

4 minuty čtení

1

Ze života W///S

Naše identita, Vizuál a web

5 minut čtení

Typografie

Redakce

Typografie pomlčka versus spojovník

5 minut čtení

ZAUJALI JSME VÁS? Napište nám

Tým webstudia

Tento web používá k poskytování služeb a analýze návštěvnosti soubory cookie. Používáním tohoto webu s tím souhlasíte. Další informace