Systémy vývojárskej dokumentácie softvéru
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>.
Zdokumentovaný C++> zdrojový kód pre Doxygen>Zdokumentovaný PHP> zdrojový kód pre PearDoc>Zdokumentovaný Java> zdrojový kód pre JavaDoc>
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í>
Použitie ďalších dokumentačných značiek
* @author Ondrej Holotnak
* @version ]]>&version;&date;
* @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