Úvod ku komentárom a nástroju Doxygen

Úvod

Obsahom tejto príručky je popis rôznych spôsobov zápisu komentárov v programovacom jazyku C, so zameraním na špecifický spôsob zápisu komentárov, ktorý môže byť užitočný pri automatickom generovaní dokumentácie, napr. k vášmu zadaniu. Príručka je zameraná na Doxygen, univerzálny nástroj pre tvorbu dokumentácie zo zdrojového kódu nielen pre jazyk C, ale aj C++, Java, Objective-C, Python, IDL, PHP, C# či D. Dokumentáciu je možné generovať v rôznych formátoch, napr. HTML, LaTeX, RTF atď. Doxygen je multiplatformový, a teda je možné ho použiť na operačných systémoch Unix, Windows aj Mac OS. Doxygen je dostupný aj na serveri omega.tuke.sk.

Komentáre v jazyku C

Všeobecne v programovacom jazyku C poznáme dva typy komentárov:

        /* Komentar */
        // Komentar
        

Do komentárov je možné zapísať ľubovoľný text, vrátane rôznych kľúčových slov jazyka C, názvov premenných aj funkcií, bez toho, aby zasiahli do chodu programu.

Platí, že komentár, ktorý začína znakmi /*, je ukončený znakmi */. Prvý z uvedených komentárov je teda možné rozšíriť aj na niekoľko riadkov. Jazyk C však nepodporuje vnorené komentáre. Pre nasledujúci príklad vnoreného komentáru prekladač ohlási chybu:

        /**
         * Komentar
         * na viac
         * riadkov /* Vnoreny komentar, ktory vsak nie je podporovany (Chyba). */
         */
        

Pre druhý zo spomenutých spôsobov zápisu komentára platí, že je ukončený koncom riadku, a teda je možné ho pridať na koniec niektorého z riadkov zdrojového kódu alebo na samostatný riadok. Avšak ak sa komentár rozšíri podľa nasledujúceho vzoru, druhý riadok naďalej zostáva súčasťou komentára:

        // Komentar \
            printf("Good Bye!\n"); 
        

Zápis komentárov v štýle Doxygen

Pri zápise komentárov v štýle Doxygen platí niekoľko základných pravidiel. Podstatou je, aby príslušný komentár bol stále platným komentárom jazyka C a zároveň aby bol uvedený v takom formáte, ktorý vie nástroj Doxygen rozpoznať.

• Na začiatok súboru sa pridáva dokumentácia k danému súboru vrátane názvu súboru, pričom:
  • @file sa používa na deklaráciu názvu súboru. Tento príkaz je dôležitý, pretože ak sa v špecifických prípadoch vynechá, celý súbor bude z dokumentácie vynechaný.
  • @brief sa používa na stručný popis daného súboru.
  • @author špecifikuje meno autora daného súboru. Ak má program viac autorov, každého autora je potrebné zdokumentovať zvlášť prostredníctvom príkazu @author.
  • @date špecifikuje dátum vytvorenia súboru.
  • @ref vytvára referenciu (odkaz) na sekciu/podsekciu alebo stránku.
  • @see začína odstavec, v rámci ktorého môže byť špecifikovaná jedna alebo viac krížových referencií na súbory, funkcie, premenné, URL adresy, prípadne triedy a metódy (v objektovom programovaní).
  Samozrejme, nie je povinné používať všetky príkazy naraz.
• Každá funkcia by mala mať pred jej definíciou uvedenú vlastnú dokumentáciu, pričom:
  • @brief je stručný popis, ktorý končí odstavcom, a teda popis uvedený za týmto odstavcom je považovaný za detailný popis. Avšak, ak je nastavenie JAVADOC_AUTOBRIEF konfiguračného súboru nastavené na YES, potom sa krátky popis končí po prvej vete (po prvej bodke).
  • @param popisuje konkrétny parameter. Ak má funkcia viac parametrov, každý parameter je potrebné zdokumentovať zvlášť prostredníctvom príkazu @param.
  • @return popisuje návratovú hodnotu danej funkcie.
  • @author a @date je možné použiť aj v rámci dokumentácie funkcie.
• Príkazy @ref a @see je možné uvádzať v rámci komentárov na ľubovoľnom mieste v programu.
• Príkaz @var slúži na dokumentáciu premennej. Tento príkaz sa odporúča používať pre dokumentáciu globálnych premenných.
• Súčasťou dokumentácie zdrojového súboru a funkcií by mali byť aj dôvody ich vytvorenia resp. podstata ich použitia.
• Ak komentáre obsahujú referencie na sekcie, podsekcie alebo stránky, je potrebné ich vytvoriť prostredníctvom príkazov @section, @subsection resp. @page.
• Ďalšie príkazy:
  • @struct sa používa na dokumentáciu štruktúry záznam.
  • @union sa používa na dokumentáciu štruktúry union.
  • @typedef sa používa sa na dokumentáciu nového typu.
  • @def sa používa na dokumentáciu direktívy #define.
• Podrobnejší popis všetkých príkazov nástroja Doxygen sa nachádza na tejto stránke.

Aby nástroj Doxygen rozpoznal aj iné komentáre ako komentáre k zdrojovým súborom a funkciám (napr. v rámci tela funkcie), dané komentáre je potrebné uvádzať v špecifickom formáte:

• Štýl JavaDoc:

        /**
         * ... text ...
         */
        

• Štýl C++:

        ///
        /// ... text ...
        ///
        

A teda, v generovanej dokumentácii nebudú zahrnuté komentáre v tvare:

        /* Komentar */
        // Komentar
        

Ďalšie spôsoby zápisu komentárov sú uvedené na tejto stránke.

Na ukážku si môžete stiahnuť súbory fibonacci.c a fibonacci.h. V rámci predmetu Programovanie nie je potrebné uvádzať komentáre tak podrobné ako vo vzorových súboroch (t.j. komentáre pre každý riadok zdrojového kódu). Na konci vzorového súboru fibonacci.c máte uvedený príklad použitia príkazu @page.

Generovanie dokumentácie nástrojom Doxygen

Pre zistenie všetkých nastavení Doxygen používa konfiguračný súbor, pričom každý projekt by mal mať vlastný konfiguračný súbor. Pre zjednodušenie vytvorenia konfiguračného súboru vie program Doxygen vytvoriť šablónu konfiguračného súboru. To je možné docieliť volaním príkazu s príslušným atribútom:

        $ doxygen -g <nazov_suboru>
        

Šablóna konfiguračného súboru bude mať teda názov <nazov_suboru>. Názov súboru je možné vynechať, pričom bude automaticky vytvorený súbor s názvom Doxyfile. Ak konfiguračný súbor s príslušným názvom už existuje, Doxygen ho automaticky premenuje na <nazov_suboru>.bak.

Formát konfiguračného súboru je podobný formátu súboru Makefile, a teda pozostáva z niekoľkých priradení vo formáte:

        NAZOVTAGU = HODNOTA
        NAZOVTAGU = HODNOTA1 HODNOTA2
        

V generovanej šablóne je možné ponechať väčšine priradení prednastavené hodnoty. Konfiguračný súbor je možné modifikovať aj prostredníctvom tzv. doxywizard pozostávajúceho z rôznych záložiek v dialógovom okne. Avšak ak sa rozhodnete používať Doxygen na serveri omega.tuke.sk, konfiguračný súbor bude modifikovaný prostredníctvom textového editora.

Pre malý projekt pozostávajúci z niekoľkých zdrojových a hlavičkových súborov je možné ponechať nastavenie INPUT prázdne a pridať jeden alebo viac vzorov pre nastavenie FILE_PATTERNS, napr. *.c *.h. Spracované tak budú iba tie súbory, ktoré sa zhodujú so zadanými vzormi. Ak toto nastavenie bude vynechané, automaticky budú použité prednastavené vzory. Pre rekurzívne spracovanie stromu zdrojových súborov je potrebné nastaviť RECUSIVE na YES. Pre ďalšie ladenie zoznamu súborov je možné použiť nastavenia EXCLUDE a EXCLUDE_PATTERNS, napr. pre vynechanie všetkých testovacích adresárov (adresáre, ktoré majú v názve test) je možné použiť vzor:

        EXCLUDE_PATTERNS = */test/*
        

Doxygen pozná konkrétne prípony súborov, ktoré vie spracovať, pričom ak špecifickú príponu nepozná, daný súbor sa spracuje podľa pravidiel pre programovacie jazyky C/C++.

Pre automatické generovanie dokumentácie je potrebné v príslušnom adresári zadať príkaz:

        $ doxygen <nazov_suboru>
        

Podľa nastavení v rámci konfiguračného súboru <nazov_suboru> je potom možné generovať dokumentáciu v rôznych formátoch, napr. html, rtf, latex, xml, man, pre ktoré program vytvorí samostatné adresáre.

Východzím adresárom, v rámci ktorého bude vytvorená dokumentácia, je ten adresár, z ktorého bol príkaz rep. program doxygen spustený. Toto nastavenie je možné zmeniť prostredníctvom nastavenia OUTPUT_DIRECTORY, pričom ak špecifikovaný adresár neexistuje, program sa ho pokúsi vytvoriť. Adresáre pre generovanú dokumentáciu je tiež možné zmeniť, a to v rámci nastavení HTML_OUTPUT, RTF_OUTPUT, LATEX_OUTPUT atď. Ak je možnosť EXTRACT_ALL nastavená na NO (prednastavená hodnota), potom sa dokumentácia vygeneruje iba pre zdokumentované entity. Podrobný popis rôznych nastavení a priradení konfiguračného súboru uvádza táto stránka.

Hlavným súborom dokumentácie vo formáte HTML je index.html, dokumentácia vo formáte RTF je generovaná do jediného súboru refman.rtf. Dokumentáciu vo formáte LaTeX (refman.tex) je najprv potrebné preložiť príslušným prekladačom.

Vytvoriť si možete aj vlastný konfiguračný súbor, napr. s nasledovným obsahom: Custom. Ak v rámci adresára s vašim projektom zadáte nasledujúci príkaz, v adresári by mali pribudnúť nové podadresáre s prednastavenými názvami html, latex a rtf vrátane dokumentácie v príslušnom formáte:

        $ doxygen Custom
        

Vzorový konfiguračný súbor Custom obsahuje vybrané nastavenia so slovenským komentárom a je možné ho použiť na generovanie dokumentácie v slovenskom jazyku ku vzorovým súborom fibonacci.c a fibonacci.h. Takto generovaná dokumentácie by mala obsahovať aj komentáre z tiel funkcií v príslušných formátoch. V dokumentácii však nabudú zahrnuté komentáre vo formáte:

        // Tento komentar nie je vo formate stylu Doxygen
        

Dokumentáciu je možné ďalej upraviť prostredníctvom modifikácie niektorých ďalších nastavení v rámci konfiguračného súboru Custom.