Systémy softvérovej dokumentácie: Úvod do rôznych systémov generujúcich používateľskú a vývojársku dokumentáciu softvéru. | ||
---|---|---|
Predchádzajúci | Nasledujúci |
Pre generovanie vývojárskej dokumentácie existuje viacero nástrojov v závislosti na tom, v akom programovacom jazyku je aplikácia napísaná. Pre C/C++ je to Doxygen, ktorý sa vyvinul z Doc++. Pre programovací jazyk PHP poznáme hneď niekoľko nástrojov: phpDoc, phpDocumentor, PearDoc a PearDoc2. Posledný z menovaných má pred sebou zrejme najlepšiu budúcnosť, nakoľko je aktívne vyvíjaný a zrejme sa stane hlavným dokumentačným nástrojom pre PHP. Nakoniec pre programovací jazyk Java je to známy JavaDoc.
Vývojárska dokumentácia sa píše priamo do zdrojových kódov programu v podobe špeciálnych komentárov. Dokumentujú sa všetky entity programovacieho jazyka: triedy a ich metódy i atribúty, globálne a lokálne funkcie i premenné, konštanty, dátové typy ako sú napr. štruktúry, výčtové typy a iné. Dokumentačný systém pomocou špeciálnych značiek rozpozná typ informácie a na základe toho ju zakomponuje do výslednej dokumentácie.
Nespornými výhodami uvedeného prístupu sú najmä ušetrný čas a komplexnosť. Vďaka tomu, že sa dokumentácia píše priamo do zdrojovýh súborov, nie je nutné pracovať so zdrojovým kódom a dokumentačným súborom súčasne. Ako už bolo spomenuté, vývojársku dokumentáciu je vhodné písať priamo počas vývoja aplikácie. A tak napríklad po pridaní novej metódy sa k nej zároveň napíše aj jednoduchý komentár, ktorý je jednak použiteľný pre informovanie o funkčnosti metódy priamo v zdrojovom kóde a samozrejme bude tiež použitý na vygenerovanie vývojárskej dokumentácie. Klasické komentáre je možné v zdrojovom kóde používať aj naďalej, do dokumentácie zahrnuté nebudú.
Treba zdôrazniť, že dokumentačné systémy sú schopné veľké množstvo poznatkov odvodiť priamo zo zdrojového kódu, keďže v sebe spravidla obsahujú analyzátory daného programovacieho jazyka. Napríklad do dokumentačného komentáru ku funkcii, metóde alebo triede nie je nutné písať jej meno, keďže to sa dá odvodiť z príslušnej deklarácie. Toto je aj hlavný dôvod, prečo pre každý programovací jazyk existujú odlišné dokumentačné nástroje vývojárskej dokumentácie, napriek tomu, že ich použitie je v zásade totožné.
Uvádzame ukážky zdokumentovania jednoduchej triedy v troch odlišných programovacích jazykoch (C++, PHP, Java) pomocou ich dokumentačných systémov (Doxygen, PearDoc, JavaDoc). Zameriame sa najmä na spoločné črty, ktoré su pre všetky systémy zhodné. Začíname príkladom pre Doxygen.
Príklad 3-1. Zdokumentovaný C++ zdrojový kód pre Doxygen
/** * Example class * * More elaborate class description. */ class Example { public: /** * Example object constructor * * More elaborate description of the constructor. * * @param bar a bar constructor parameter * @param foo a foo constructor parameter * @return void */ Example(int bar = 0, const char *foo = "foo"); /** * Example object destructor * * More elaborate description of the destructor. */ ~Example(); };
Príklad 3-2. Zdokumentovaný PHP zdrojový kód pre PearDoc
/** * Example class * * More elaborate class description. */ class Example { /** * Example object constructor * * More elaborate description of the constructor. * * @param int bar a bar constructor parameter * @param string foo a foo constructor parameter * @return boolean true if this example is right, * false otherwise */ function Example($bar = 0, $foo = 'foo') { // Constructor code goes here. Note that PHP does not // have anything like header files with declarations. return true; } }
Príklad 3-3. Zdokumentovaný Java zdrojový kód pre JavaDoc
/** * Example class * * More elaborate class description. */ class Example { /** * Example object constructor * * More elaborate description of the constructor. * * @param bar a bar constructor parameter * @param foo a foo constructor parameter * @return void */ Example(int bar = 0, const char *foo = "foo") { // Constructor code goes here } }
Z príkladov vidieť, že špeciálne komentáre začínajú sekvenciou /**. Klasické /* komentáre sa ignorujú. Boli použité značky @param pre definovanie vstupného funkčného parametru a @return pre definovanie navratovej hodnoty z funkcie. Všimnite si, že zdrojový kód C++ už obsahuje informáciu o dátovom type vstupného parametra, preto sa v komentári nevyskytuje. Dokumentačný systém Doxygen si ju zistí sám. Naproti tomu zdrojový kód PHP túto informáciu v sebe nemá, takže musí byť v dokumentačnom komentári uvedená.
Medzi ďalšie značky používané na dokumentovanie funkcií alebo metód patria okrem @param a @return tiež @access vyjadrujúci prístupnosť metódy (public, private, ...) a @retval používajúci sa na opis návratovej hodnoty parametru funkcie definovaného referenciou (adresou). Ďalšie všestranne použiteľné značky sú:
@author | -- autor entity (triedy, metódy, funkcie) |
@version | -- verzia entity |
@date | -- dátum vzniku |
@since | -- minimálna verzia majúca nejakú funkcionalitu |
@deprecated | -- stará a už nepodporovaná funkcionalita |
@see | -- odkaz na súvisiacu entitu |
@todo | -- popis nedokončných vymožeností |
Príklad 3-4. Použitie ďalších dokumentačných značiek
/** * Extensive Example class * * This extensive class does some extensive job. * * @author Ondrej Jombik <nepto@pobox.sk> * @author Ondrej Holotnak <beast@host.sk> * @version 1.0 * @date 2002-12-19 */ class Extensive_Example { /** * Normal method doing something * * @param some some integer argument * @retval thing allocated string filled with thing * @return test result * @author Someone External <someone@example.com> * @see Test() * @see ~Test() * @todo make this method something doing */ int doSomething(int some, char **thing); };
Podobne ako pri používateľskej dokumentácii je aj tu možnosť vygenerovať finálnu dokumentáciu vo viacerých formátoch. Aplikácia Doxygen podporuje nasledovné výstupné formáty: HTML, LaTeX, RTF, XML a manuálové stránky. Všetko sa konfiguruje pomocou prehľadného konfiguračného súboru Doxyfile. Pokial spustíte program doxygen s prepínačom -g, základný konfiguračný súbor bude zapísaný na disk. Obsahuje veľa komentárov, takže jeho modifikácia je jednoduchá a priamočiara. Samotná generácia dokumentácie prebieha nasledovným príkazom:
$ doxygen
Ostatné vymenované nástroje sa používajú obdobne. Nemusia však obsahovať podporu všetkých vymenovaných formátov. Všetky však určite obsahujú možnosť generovania HTML výstupu, ktorý sa považuje za najdôležitejší a najpoužiteľnejší.Predchádzajúci | Domov | Nasledujúci |
Systémy používateľskej dokumentácie softvéru | Iné systémy pre dokumentáciu softvéru |