Kapitola 3. 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.

/**
 * 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();
};

/**
 * 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;
	}
}

/**
 * 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ú:

/**
 * 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