Seznámení s Doxygenem

Opět pro účely projektu z IFJ jsem sepsal úplné minimum potřebné pro práci s Doxygenem. Popisuji styl JavaDoc, ale samozřejmě neexistuje jediný, jen mi přišel nejpříjemnější. JavaDoc určuje pouze syntaxi pro příkazy Doxygenu, ostatní „stylistické prvky“, jako třeba jestli funkce komentovat u její deklarace či definice, nebo jak komentovat složky struktur jsou již mé vlastní konvence. Nic vám samozřejmě nebrání zavést vlastní.

Základní příkazy

Doxygen rozeznává dva druhy komentářů (ostatní jsou pro něj „neviditelné“):
[c]
/** doxycomment multi line
*/
///doxycomment single line
[/c]

Na začátek každého zdrojového (nikoliv header) souboru je třeba vložit následující – umožní to jeho indexaci:
[c]
/** @file jmeno_souboru.c

• @brief Jedna veta o tomto modulu.
• Mozny obsahlejsi popis na vice
• radek.
  */
  [/c]
  Je samozřejmě vhodné  vkládat i standardní hlavičku souboru (autoři, datum, atp.), ale již ne v Doxygen formátu – to by pouze výstup znepřehlednilo.

Funkce se komentují často u její definice (nad ní) a to následujícím stylem:
[c]
/**

• Kratky, jednoradkovy popis funkce.
• Obsahlejsi, podrobnejsi popis cinnosti funkce.
• Klidne na vice radku.
• @bug Obcas vraci spatne vysledky.
• @warning Pri zadani cisla 0 se zachveje lampicka.
• @param firstNumber prvni operand (int)
• @param secondNumber druhy operand (int)
• @return prumer zadanych cisel (double)
  */
  double Average(int firstNumber, int secondNumber)
  {
  …
  }
  [/c]
  Samozřejmě všechny tagy je třeba používat s rozmyslem — když funkce nepřijímá parametry, neuvedu @param, pokud zde není bug ani varovné chování neuvedu @bug ani @warning. Tagy pro bugy a warningy však používejte co nejčastěji, aby se na ně nezapomnělo a byly dané chyby hned na očích (v HTML výstupu jsou pak viditelně označené, vizte dále).

Struktury a výčtové typy je vhodné dokumentovat poněkud důkladněji (i každý jejich element), viz příklad:
[c]
/**

• Struktura pro uchovani obsahu PPM souboru.
  */
  typedef struct ppm {
  unsigned long xsize; ///< velikost x rozmeru
  unsigned long ysize; ///< velikost y rozmeru
  char data[]; ///< vektor pro uchovani samotnych dat
  } ppm_t;

/**

• Vyctovy typ pro rozmerove dimenze
  */
  typedef enum {
  dimOne, ///< 1D, jedna dimenze
  dimTwo, ///< 2D, dve dimenze
  dimThree, ///< 3D, tri dimenze
  docKovar ///< Meda
  } dimension_t;
  [/c]

Výstupy

Je sice fajn, když máme projekt okomentovaný Doxygen stylem, ale k čemu nám to je? Doxygen je nástroj pro „automatickou dokumentaci“ – tudíž z komentářů ve zdrojovém kódu (které byste měli psát tak jako tak) vám vygeneruje velice pěknou a přehlednou dokumentaci v několika formátech. Nemusíte tak úmorně procházet kód a dělat jí ručně, ale všechno máte hotové v řádu sekund (pokud nepočítáme investici při psaní komentářů ve zdrojáku).

Jak se tato celá ta legrace spustí? Velice jednoduše, stačí mít nainstalovaný program Doxygen (k dostání snad ve všech repozitářích) a spustit následující příkaz.
[plain]
doxygen Doxyfile
[/plain]
Doxyfile je konfigurační soubor, podle nějž se řídí veškeré generování dokumentace. Je tam toho k nastavení opravdu mnoho (včetně různých optimalizací pro odlišné programovací jazyky). Jako ukázka vám může posloužit náš konfigurační soubor do IFJ. Můžete si zapnout generování dokumentace do nejrůznějších formátů – třeba HTML nebo LaTeX. Pokud chcete zadat nějaký řetězec do Doxyfile, používejte pouze dvojité uvozovky – při použití jednoduchých Doxygen do výsledného řetězce zahrne i ty jednoduché uvozovky. Jak vypadá taková HTML dokumentace vygenerovaná Doxygenem středního projektu můžete vidět na našem IFJ projektu (zdrojové soubory nebyly zahrnuty, pouze hlavičkové).

Podrobnější informace pro fanoušky:
Doxygen Manual
YoLinux