Nástroj pro dokumentování projektů

Doxygen



Naučte se zacházet s nástrojem Doxygen. Na základě dodaného příkladu vytvořte dokumentaci pro vypracovávanou třídu CVector.



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, ...). Hlavním pomocným souborem, který je nutné nainstalovat je Graphviz.
Program doxygen je možné stáhnout z adresy http://www.stack.nl/~dimitri/doxygen/download.html. Je zde binární instalace i zdrojové kódy, které je možné si přeložit. Níže na stránkce je možné stáhnout pdf manuál. Na stránkách je tentýž manuál ve webovém rozhraní.

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ší. Pro správnou funkci je nutné upravit proměnnou prostředí path tak, aby obsahovala cestu do bin podadresáře v adresáři, ve kterém je graphviz nainstalován

Cestu ke graphviz je nutné zjistit na vašem počítači, v daném adresáři by měl být soubor dot.exe.
Cesta může vypadat například: C:\Program Files (x86)\Graphviz2.38\bin (včetně bin).

Co je cesta lze zjistit na:
http://en.wikipedia.org/wiki/PATH_%28variable%29
http://cs.wikipedia.org/wiki/PATH_%28prom%C4%9Bnn%C3%A1%29


Jak nastavit, nebo rozšířit cestu ve Windows lze zjistit například na:
http://www.computerhope.com/issues/ch000549.htm
http://msdn.microsoft.com/en-us/library/office/ee537574%28v=office.14%29.aspx
http://merlin.fit.vutbr.cz/FITkit/docs/navody/install_path.html
http://lmgtfy.com/?q=Jak+nastavit+PATH+ve+windows


Propojení s VisualStudiem

Tento nástroj je možné volat i přímo z VS. V položce menu tools/external tools, kam se dá doinstalovat externí program se přidá doxygen (Title: doxygen, command: doxygen.exe, arguments: prázdné/nevyplňujte , 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.html.

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

Ve VS je možné provádět editaci. Dále je zde možné provést spracování a prohlédnout si výsledek (v okně output). Není zde možné utvořit počáteční konfigurační soubor Doxyfile. Není zde možné si prohlédnout výsledek. To je nutné provést v prohlížeči (IE, Chrome, Firefox ...)



Vytvoření konfiguračního souboru

Pro spuštění programu doxygen (a tedy pro vytvoření dokumentace) je nutný konfigurační soubor. Jeho možné pořízení je:

- ručně,
- vygenerováním implicitního a jeho úpravou,
- pomocí wizardu.
- použít soubor z jiného projektu jako základ pro úpravy

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). Volba bez komentářů je jednoduchá pro orientaci, pokud víte co položky znamenají. Pokud máte komentovanou verzi je dobrá orientace při modifikování nastavení i pro méně zkušeného uživatele.
Poslední možností je spuštění GUI wizardu a nastavování položek zde "klikáním".

Zkuste vytvořit nový konfigurační soubor. Porovnejte svůj „čistý“ nově vytvořený soubor s následujícím souborem vytvořeným ve starší verzi s modifikacemi položek a upraveným pro projekt (porovnání příkazem „fc Doxyfile Doxyfileold >rozdily.txt“ kdy starší soubor přejmenujeme na Doxyfileold. Zjištěné rozdíly se uloží do souboru rozdily.txt).



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.



Překlad si můžete vyzkoušet na předpřipraveném příkladu, ve kterém je i podrobnější návod obsahující základní vlastnosti. Soubory z tohoto příkladu nakopírujte do adresáře vašeho projektu CVector.
Další podrobnější použití najdete ve školním projektu a podrobnější dokumentaci na domovských stránkách tohoto nástroje.





Postupujte podle následujících bodů:

  1. vygenerujte nový soubor doxyfile a srovnejte ho se starším dodaným souborem. Zjistěte jakou funkci mají rozdílné položky. Proveďte v novém souboru (rozumné) úpravy podle starého souboru. Správně nastavte český jazyk. Nastavte „velký“ název projektu a zobrazte logo.

  2. Prostudujte si dodané soubory s dokumentací. Proveďte překlad dokumentace. Podívejte se na výsledek překladu a srovnejte ho se zdroji. Všimněte si zobrazení (zatím) nekomentovaných zdrojových souborů třídy CVector.

  3. Spusťte doxygen a tentokrát si všímejte jeho zpráv - podívejte se na základní hlášení, sledujte chybová hlášení.
    Základní/informativní a chybová hlášení je možné uložit do souboru a to i odděleně hlášení o průběhu a o chybách.
    Následující řádkový příkaz v cmd způsobí vytvoření dvou souborů:
    doxygen Doxyfile 1> sh.txt 2> we.txt
    V sh.txt budou standardní hlášení o průběhu, v x2.txt potom warningy a errory. Následující povel provede zpracování ale zobrazí na konzole pouze chybová hlášení:
    doxygen Doxyfile 1> sh.txt. Hlášení warningů a errorů bude na obrazovce.
    Cílem by měl být překlad bez warningů a errorů.

  4. Vytvořte v dokumentaci popis hlavičkového souboru vector.h. Uveďte zkrácený a detailní popis co soubor obsahuje. Uveďte jméno autora.

  5. Vytvořte dokumentaci ke třídě.
    U třídy jako celku uveďte zkrácený a detailní popis.
    U datových členů třídy uveďte jejich význam, k čemu se používají.
    U metod uveďte zkrácený a detailní popis činnosti, popište význam vstupních a výstupních parametrů.

  6. Popište pro dokumentaci i ostatní (nutné) součásti projektu (například enum ….)







Poslední úpravy 2018-10-22