Obsah
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ů:
- Vložení komentářů ve vhodném formátu (JavaDoc…) přímo do zdrojového kódu.
- 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.
Komentáře v kódu
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.
Dokumentace souborů
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.
Ukázka hlavičkového souboru
#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
Ukázka jiného (nehlavičkového) souboru
/**
* @author John Doe <john.doe@example.com>
* @file list.c
*/
...
Dokumentace struktur a výčtových typů
/** * @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;
Dokumentace funkcí
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);
Generování dokumentace
Vygenerování dokumentace provedeme pomocí následujících kroků:
- Přepneme se do adresáře se zdrojovými kódy
- Vygenerujeme konfigurační soubor Doxygenu pomocí příkazu
doxygen -g
Vznikne skript Doxyfile.
- Pokud jsou zdrojové kódy i v podadresářích, tak upravíme ve skriptu Doxyfile hodnotu
- RECURSIVE = YES
- Spustíme Doxygen pomocí příkazu
doxygen
- 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é:
- Nainstalovat balík GraphViz http://www.graphviz.org/Download.php
- Změnit před generováním dokumentace ve skriptu Doxyfile hodnoty
- CALL_GRAPH = YES
- HAVE_DOT = YES
- 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
- Spustíme znovu
doxygen
Troubleshooting
- 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).