Pomocí speciálních komentářů vygenerujeme programátorskou příručku.
V prvním díle tohoto seriálu jsme se podívali na výhody používaní PHPDoc. Pokud jste se dostali k tomuto dílu, nejspíše jste – stejně jako já – přišli na to, že práce s dokumentováním se později mnohokrát vrátí.V tomto díle se podíváme na tagy při psaní komentářů. PHPDocumentor obsahuje celou řadu tagů a dalších nástrojů pro tvorbu automatické dokumentace. V tomto seriálů si popíšeme pouze [b]základní[/b] a nejdůležitější tagy, abychom byli schopni vytvořit [b]kvalitní automatickou dokumentaci[/b]. Nastudovat všechny možnosti by stálo hodně času a osobně si myslím, že základy jsou ideálním kompromisem. Kdo by se PHPDoc věnovat, může nastudovat jejich velmi přehlednou dokumentaci.
Použitím pokročilých komentářů se náš kód stane velmi přehledným. Připomínám, že i při použití PHPDoc, se nesmí zapomínat na používání klasických komentářů a to hlavně na popis složitějších částí kódů. PHPDoc slouží pouze jako obecný popis.
Vzor
Jak jsem uvedl v minulém článků, dokumentace se tvoří pomocí [b]/** ….popis… */ [/b]. Nejlepší vysvětlování je ukázka na příkladu. K tomuto účelu využiji jednoduchou třídu pro práci s MySQL, na které si ukážeme základní popis souboru, třídy, funkce i proměnné. Po dokončení tohoto mini-seriálu tuto třídu rozeberu a popíšu v budoucím seriálu Rozumná práce s MySQL . Celá třída s komentáři by vypadala takto:
/**
* OBSLUHA MYSQL
*
* muj projekt
* @author Honzy
* @version 1.0 - 2007
* @package Classes
*/
/**
* trida pro pripojeni k databazi
*/
class MySQL {
/**
* link na pripojeni k db
* @access private
* @var int
*/
private $link;
/**
* provede MySQL dotaz
* @param $query dotaz_pro_MySQL
* @return integer Mysql_result
*/
public function query($query) {
...
...
}
}
Popis souboru
Každý náš jednotlivý soubor by měl obsahovat hlavičku. První řádek obsahuje popis souboru (v našem případě OBSLUHA MYSQL). Dále název projektu, jméno autora, verzi, rok. Poslední z důležitých tagů je @package. Obsahuje jméno balíčku, do kterého daný soubor patří. Seznam těchto balíčků pak bude vygenerován v menu. Ukázku uvidíte na některém z obrázku dále. Po kliknutí na položku, se zobrazí seznam souboru v tomto balíčku. Význam tohoto tagu je tím pádem jasný. Například pro seskupení souborů pracujících s administrací apod.Popis tříd
K popisu třídy není moc co dodávat. Prostě napíšeme popis toho, k čemu třída je. Stejným způsobem popisujeme i include() a define().
/**
* chyba pripojeni k db
*/
define ("DB_ERROR", "Chyba v databazi. Zkuste to prosim pozdeji.");
Popis proměnných
Za to u funkcí a proměnných, se toho najde víc. U každé proměnné popisujeme popis, typ přístupu a jeho typ. Můžete psát int stejně jako integer. PHPDocumentor typ nekontroluje a prostě jej vypíše.
/**
* link na pripojeni k db
* @access private
* @var int
*/
private $link;
Popis funkcí
Jako poslední se podíváme na okomentování funkce. Opět začínáme popisem. Tagem [b]@param[/b] popíšeme vstupní parametry. Tagem [b]@return[/b] tak zcela logicky návratovou proměnnou.
/**
* provede MySQL dotaz
* @param $query dotaz_pro_MySQL
* @return integer Mysql_result
*/
public function query($query) {
Pár slov závěrem
Toto bylo pro dnešní díl vše. Jak sami vidíte, nastudování těchto základních komentářů zabere sotva minut a výsledky jsou ohromné. V dalším a zároveň posledním díle ukážu, jak příručku z už okomentovaného zdrojového kódu vygenerovat.
Ukázky obrazem
Úplným závěrem přidávám pár obrázků z již vygenerované dokumentace.
Ukázka souhrnu našeho souboru. Nalevo můžete vidět jednotlivé balíčky a obsah práve vybraného balíčku. Dále si můžete nechat vypsat zdrojový kód – viz. Další obrázek
Vidíme, že zobrazení zdrojového kódu je perfektní. Zvýraznění kódu je samozřejmostí. Navíc, názvy tříd a některé proměnné, jsou klikatěné. Po kliknutí je podle očekávání zobrazen popis.
Autor: Honzy
2024 ©