Ú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

        /* Komentar */
        // Komentar
        

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

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

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

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

• Štýl JavaDoc:

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

• Štýl C++:

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

        /* Komentar */
        // Komentar
        

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

        $ doxygen -g <nazov_suboru>
        

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
        

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

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

        $ doxygen <nazov_suboru>
        

Východzím adresárom, v rámci ktorého bude vytvorená dokumentácia, je ten adresár, z ktorého bol príkaz resp. 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
        

        // Tento komentar nie je vo formate stylu Doxygen