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