PHP a Doxygen

Už přes rok kontinuálně vyvíjím jistou webovou aplikaci a již od začátku jsem si dával záležet na tom, abych ke každé třídě a metodě psal tzv. doxygen-style komentáře, popisující co která třída a metoda dělá, u metod navíc třeba dokumentaci parametrů a návratových hodnot.

Jak komentovat v kódu

/**
 * Ukázka doxygen-style komentáře.
 *
 * @class UkazkovaTrida
 * @author Hans
 *
 * @date 2008-05-29
 */
class UkazkovaTrida
{
	/**
	 * Ukázka doxygen-style komentáře.
	 * Funkce vracející nulu.
	 *
	 * @author Hans
	 *
	 * @date 2008-05-29
	 *
	 * @param zbytecny zbytečný parametr
	 * @return vždy 0
	 */
	function Nula($zbytecny)
	{
		return 0;
	}
}

Co pak s tím

Teď jsem to konečně nějak zužitkoval – stáhnul si Doxygen, v rychlosti nakonfiguroval projekt (pomocí přiloženého doxywizardu; stačilo v podstatě definovat adresář projektu a výstupní adresář pro dokumentaci) a vygeneroval konfigurační soubor projektu (Doxyfile). Ten lze pak doupravit ručně v textovém editoru (jedná se vlastně o jakýsi „makefile“ pro Doxygen).

Na ten jsem následně spustil doxygen.exe z příkazové řádky a rázem mám čtyřmegový balík provázané dokumentace v HTML včetně grafického znázornění závislosti tříd a podobných vymožeností.

To se mi líbí, v podstatě se jedná o jediný smysluplný (a zároveň snadný a nepříliš otravující) způsob dokumentování kódu. Kdysi jsem svůj kód zkoušel prohnat tuším PhpDocumentorem, ale ten se mi nepodařilo nakonfigurovat a rozchodit během jednoho odpoledne, toto šlo oproti tomu zcela samo.

Jak rozchodit Doxygen

Takže, jestli si chcete snadno dokumentovat své projekty (ať už v Javě, C, C++, PHP nebo dalších podporovaných jazycích), proveďte následující:
  • stáhněte si Doxygen
  • stáhněte si Graphviz (abyste si mohli nechat generovat i grafické části dokumentace)
  • obojí nainstalujte a pomocí prográmku doxywizard.exe si můžete rychle zkusit vytvořit první pokusný dokumentační projekt :)

Jak vypadá výsledek

Ukázka hotové dokumentace

3 komentáře

Hans

PS: Článek budu ještě dolaďovat, mimojiné přidám ukázku dokumentace vytvořené z onoho pokusného kusu kódu. To mi teď nejde, nemaje FTP přístup na server || správně nakonfigurovaný upload v CMS :)

kumpa

Ale my chceme ukazky ted hned! :-)

Hans

Už je to tam :)

Reagovat