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.
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í |
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 |