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, ...). Hlavním pomocným
souborem, který je nutné nainstalovat je Graphviz.
Program doxygen
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.
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.h.
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). 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".
Zkuste vytvořit nový konfigurační soubor. Porovnejte svůj „čistý“ nově vytvořený soubor s následujícím souborem připraveným pro vaši práci
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ří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.
Zadání k procvičení:
Vytvořte pomocí doxygen dokumentaci k
projektu 2D pole. Vytvořte úvodní list se zadáním a popište řešení.
Okomentujte funkce, strukturu a důležité proměnné.
- denní studenti mohou hledat inspiraci v projektu CXItem
- vytvořte konfigurační soubor doxyfile
- spusťte doxygen na 2D pole - podívejte se na základní hlášení,
sledujte chybová hlášení.
Je možné hlášení uložit – a to
zvlášť hlášení o průběhu a o chybách. Následující řádek v cmd způsobí
vytvoření dvou souborů: doxygen Doxyfile 1> x1.txt 2> x2.txt. V
x1.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> x1.txt. Hlášení
warningů a errorů bude na obrazovce.
- V projektu 2D pole vytvořte soubor pro dokumentaci - documentation.txt – V něm vytvořte tabulku, kde bude jméno autora, název projektu. Dále do tohoto souboru vložte zadání.
- V projektu 2D pole pomocí nástroje doxygen "okomentujte" soubory
- V projektu 2D pole pomocí nástroje doxygen "okomentujte" funkce (viz main v projektu)
- V projektu 2D pole pomocí nástroje doxygen "okomentujte" strukturu a její proměnné
Poslední úpravy 2014-11-05