Základy použití dokumentačního nástroje Doxygen

Dokument vytvořil Petr Švenda, jakékoli připomínky piště prosím na svenda@fi.muni.cz

Doxygen je dokumentační nástroj, umožňující generovat dokumentaci v různých formátech (html, latex, xml) ze zdrojového kódu. Práce programátoru se sestává ze dvou kroků:

1. Vložení komentářů ve vhodném formátu (JavaDoc…) přímo do zdrojového kódu.
2. Zpracování a vygenerování dokumentace pomocí nástroje Doxygen.

Tento dokument navazuje na konvence programování v jazyku C.

Následující části obsahují ukázky dokumentace a některé důležité body. Pro podrobný seznam možností nástroje Doxygen viz. manuál. Značky označené [OPTIONAL] nejsou povinné, ale mohou se hodit.

V průběhu psaní kódu je nutné vkládat do zdrojového kódu komentáře ve speciálním formátu. Doxygen podporuje několik možných syntaxí (JavaDoc, QT, Visual Studio…), více viz. http://www.stack.nl/~dimitri/doxygen/docblocks.html. V dalším textu budeme předpokládat použití syntaxe JavaDoc.

V hlavičkových souborech a main.c pište plnou dokumentaci funkcí, struktur atd., ve všech souborech navíc pište tagy @author a @file. V textu dokumentace používejte angličtinu.

#ifndef MY_AWESOME_LIBRARY_H
#define MY_AWESOME_LIBRARY_H
 
/**
 * @brief   [OPTIONAL] Brief file description.
 * @file    my_awesome_library.h
 * @author  John Doe <john.doe@example.com>
 *
 * [OPTIONAL] Detailed file description.
 */
 
#include <stdlib.h>
// ...
 
#endif // MY_AWESOME_LIBRARY_H

/**
 * @author John Doe <john.doe@example.com>
 * @file   list.c
 */
 
...

/**
 * @brief Doubly linked list node.
 *
 * [OPTIONAL] Detailed description.
 */
typedef struct node
{
    struct node *prev; /**< previous node        */
    struct node *next; /**< next node            */
    void        *data; /**< pointer to node data */
} node_t;
 
/**
 * @brief UNIX file system permissions.
 *
 * [OPTIONAL] Detailed description.
 */
typedef enum mode
{
    Read    = 1, /**< read a file or list contents of a directory */
    Write   = 2, /**< modify a file or directory entries          */
    Execute = 4  /**< execute a file or enter a directory         */
} mode_t;

Pokud chcete v textu odkazovat parametr funkce, použijte značku @a parametr, hodnoty můžete značit např. značkou @c true. Funkce, které nic nevrací (mají návratový typ void) pochopitelně nemusí mít značku @return.

/**
 * @brief   Halting problem solver.
 * @param   tm      Turing machine to simulate
 * @param   input   input to simulate the @a tm with
 * @return  @c true if the machine @a tm will halt with the tape @a input, @c false otherwise
 * @note    [OPTIONAL] The content of the @a input tape will remain unchanged.
 * @warning [OPTIONAL] Still under development.
 * @bug     [OPTIONAL] This function can run indefinitely for some inputs.
 *
 * [OPTIONAL] Detailed information on how awesome this function is.
 */
bool halts(machine_t *tm, tape_t *input);

Navíc, pokud je argument funkce ukazatel, přidejte za param položku [in], [out] nebo [in,out] pokud je to vstupní, výstupní resp. vstupno-výstupní argument:

/**
 * @param[in]     ro   memory to be read
 * @param[out]    wo   memory to be filled
 * @param[in,out] rw   memory to be read and written
 */
void foo(const void *ro, size_t *wo, char *rw);

Vygenerování dokumentace provedeme pomocí následujících kroků:

1. Přepneme se do adresáře se zdrojovými kódy
2. Vygenerujeme konfigurační soubor Doxygenu pomocí příkazu

   doxygen -g

   Vznikne skript Doxyfile.

3. Pokud jsou zdrojové kódy i v podadresářích, tak upravíme ve skriptu Doxyfile hodnotu

• RECURSIVE = YES

1. Spustíme Doxygen pomocí příkazu

   doxygen

2. V adresáři html/index.html by měla být vygenerována dokumentace ve formátu HTML

Velmi dobrého rozšíření dosáhneme generováním grafu volání jednotlivých funkcí. Lze použít i v případě, že se potřebujeme rychle zorientovat v neznámém kódu. K tomu je nutné:

1. Nainstalovat balík GraphViz http://www.graphviz.org/Download.php
2. Změnit před generováním dokumentace ve skriptu Doxyfile hodnoty
   • CALL_GRAPH = YES
   • HAVE_DOT = YES
3. Pokud chceme vygenerovat graf volání (a základní dokumentaci) i ze zdrojových kódů, které neobsahují Doxygen komentáře, tak změníme ještě hodnotu
   • EXTRACT_ALL = YES
4. Spustíme znovu

   doxygen

• Po spuštění Doxygenu není ve vygenerované dokumentaci žádný soubor nebo některé chybí. Důvodem je pravděpodobně to, že sdrojové soubory nezačínají direktivou /** @file jmeno_souboru*/. Řešením je vložit tuto direktivu na začátek každého souboru nebo změnit v konfiguračním skriptu Doxyfile (nebo jiný soubor, pokud nemáte v defaultním) hodnotu EXTRACT_ALL na YES (defaultně je NO).