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.
/** * 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; } }
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.
Ale my chceme ukazky ted hned! :-)
Už je to tam :)
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 :)
29. 5. 2008 15:40, Reagovat