Nástroj pro dokumentování projektů

Doxygen

Doxygen slouží ke komentování zdrojových textů projektu a ke tvorbě strukturované dokumentace. V dokumentaci zachytí nejen okomentované skutečnosti, ale i vazby (mezi typy, proměnnými, prostory, soubory...), které je schopen odvodit.

Jak začít?

Instalace

Je nutné nainstalovat program doxygen a případně i pomocné soubory (grafické znázornění UML, podpora pro (La)Tex, ...).
Program je možné stáhnout z adresy http://www.doxygen.org/download.html. Je zde binární instalace i zdrojové kódy, které je možné si přeložit.

Pro zobrazení grafů závislostí je nutné nainstalovat pomocný program (pro doxygen) Graphviz (http://www.graphviz.org/) a v konfiguračním souboru doxygen zapnout spolupráci s graphviz pomocí změny přepínače HAVE_DOT na YES. Původně jednoduché grafy závislostí (je, má) jsou teď podstatně detailnější.

Vytvoření konfiguračního souboru

- ručně,
- vygenerováním implicitního a jeho úpravou,
- pomocí wizardu.

K ručnímu napsání jsou třeba dobré znalosti (a asi se bude vycházet ze staršího souboru).
Vygenerování konfiguračního souboru (v adresáři, kde jsou zdrojové texty projektu) je možné příkazem doxygen -g JmenoSouboru (spouštějící program doxygen.exe s parametry -g (pro generování) a jménem souboru pro uložení konfiguračního textu). Konfigurační soubor v sobě obsahuje kromě nastavení i komentáře k položkám. Je možné použít i vygenerování stručné formy bez komentářů, pouze s nastaveními, příkazem doxygen -s - g JmenoSouboru. Tento soubor je možné upravovat (měnit nastavení položek). Tato volba je asi nejjednodušší (pokud máte komentovanou verzi je i velice dobrá orientace při modifikování nastavení).
Poslední možností je spuštění GUI wizardu a nastavování položek zde "klikáním".

Vytvoření dokumentace

V adresáři, ve kterém je vytvořen konfigurační soubor spusťte program Doxygen se jménem konfiguračního souboru jako parametr - doxygen.exe doxyfile. Spuštění „přeložené“ verze je nutné provést v adresáři html (který se vytvoří při zpracování) souborem index.h.

Propojení s VC++

Tento nástroj je možné volat i přímo z VC++. V položce menu tools/external tools, kam se dá doinstalovat externí program se přidá doxygen (Title - doxygen, command - doxygen.exe, arguments - , initialDir - $(ProjectDir). Pokud zaškrtnete use output window, bude protokol o zpracování zobrazován ve výstupním okně VC++. Spuštění „přeložené“ verze je i zde nutné provést „externě/ručně“ v adresáři html (který se vytvoří při zpracování) souborem index.h.

Nastavení Doxygenu lze do VC++ doplnit pomocí tohoto souboru, který doinstalujete tools/import&export settings/import selected environment settings/(podle uvážení-spíše No)/...

Překlad si můžete vyzkoušet na příkladu, ve kterém je i podrobnější návod obsahující základní vlastnosti. Podrobnější použití najdete ve školním projektu a podrobnější dokumentaci na domovských stránkách tohoto nástroje.

Jako vzor pro komentovaný projekt může sloužit projekt pro testování prvků lineárního seznamu, který naleznete jako součást projektu v svn.

Poslední úpravy 2013-10-07