Doxygen Jakub Břečka
Úvod Proč a typy dokumentace na přednášce Programátorská dokumentace (popis implementace, tříd, funkcí, API) Doxygen, JavaDoc, Sandcastle, AppleDoc, Doxygen = klasika mezi dokumentačními nástroji C, C++, Java, Objective-C, Python, PHP, C#, Windows, Linux, Mac OS, Vstup: Anotované zdrojové kódy, konfigurace Výstup: HTML, LaTeX, PDF, man stránky,
Vstupy a výstupy
Anotace /** * This class implements a simple "Hello world" application. */ class HelloDoxy { /** * Main method of the HelloDoxy class. * @param args Arguments passed from the command line. */ public static void main(string[] args) { System.out.println("Hello World!"); } }
Konfigurační soubor Vygenerovat pomocí -g : $ doxygen g Configuration file `Doxyfile' created. Formát: TAGNAME = value TAGNAME = value1 value2 TAGNAME = "Value with spaces"
Doxyfile DOXYFILE_ENCODING = UTF- 8 PROJECT_NAME = "My Project" OUTPUT_DIRECTORY = OUTPUT_LANGUAGE = English SHOW_FILES = YES SHOW_NAMESPACES = YES EXTRACT_ALL = NO EXTRACT_PRIVATE = NO GENERATE_HTML = YES GENERATE_HTMLHELP = NO GENERATE_LATEX = YES LATEX_OUTPUT = latex GENERATE_MAN = NO
Vygenerování dokumentace $ ls Doxyfile HelloDoxy.java $ doxygen Doxyfile... $ ls Doxyfile HelloDoxy.java html latex $ ls html annotated.html classhellodoxy- members.html classes.html doxygen.css functions.html index.html jquery.js nav_h.png search tab_b.png tab_s.png bc_s.png classhellodoxy.html closed.png doxygen.png functions_func.html installdox nav_f.png open.png tab_a.png tab_h.png tabs.css
Výsledek
Syntaxe Dokumentace v komentářích, brief, detailed : Konfigurace JAVADOC_AUTOBRIEF JavaDoc/C style: /** * Brief description. Detailed description. */ Qt style: /*! * \brief Brief description. *... */ C++ style: /// ///... text... /// Single-line brief: /// Brief description. /** Detailed description. */
Umístění anotací Soubor Namespace Třída, metoda, proměnná, struktura, union, enum, Je-li anotace umístěna jinam, je třeba označit, k čemu patří: \class, \enum, \file, \fn, \interface, \namespace, \var, \struct,
Dokumentování souborů, tříd /*! * \brief Pretty nice class. * \details... * \author John Doe * \author Jane Doe * \version 4.1a * \date 1990-2011 * \pre First initialize the system. * \bug... * \warning... * \copyright GNU Public License. */ class SomeNiceClass {};
Dokumentování funkcí \param [(dir)] <param-name> { description } \throw, \throws, \exception <exception-object> { description } \return { description } \deprecated { description }
Nečíslovaný seznam +, -, * Hello world - item - item - subitem Seznamy Číslovaný seznam +#, -#, *#, +., -., *. Hello world - # item 1 - # item 2 - # subitem 1
Skupiny Sloučení souborů, tříd, metod, stránek, skupin, do modulů \defgroup <name> (title) \addtogroup <name> (title) \ingroup <groupname> Seskupení více položek ///@{... ///@} /**@{*/... /**@}*/
Strukturální (kam co patří) \class, \fn Příkazy Označování sekcí \brief, \details, \exception, \param, \return Vytváření odkazů \link, \ref Ukázky kódu \include Vizuální příkazy \b, \em, \code, \n
Grafy a diagramy Diagramy dědičnosti, graf závislosti souborů, grafy volání Využívá GraphViz a utilitu dot Konfigurace HAVE_DOT Pokud máme dot v $PATH, funguje vše automaticky
Preprocessing Doxygen má vestavěný C-čkový preprocesor Podmíněné příkazy (#if) defaultně ano, expanze maker defaultně ne Konfigurace ENABLE_PREPROCESSING, MACRO_EXPANSION, EXPAND_ONLY_PREDEF, PREDEFINED Hodí se pro makra typu declspec, attribute,
Samostatné stránky Vytvoření hlavní stránky a dalších stránek: \mainpage [(title)] \page <name> (title) \section, \subsection \tableofcontents
Odkazování Odkazy odkudkoliv kamkoliv stránky, komentáře, funkce, typy \link <link-object> text odkazu \endlink \ref <link-object> \sa, \see Automatické odkazy ::ClassName ClassName::MethodName(ParamTypes) ClassName::VariableName
Další možnosti Markdown, HTML support Vzorce Doxywizard Formátování výstupu HTML výstup pomocí CSS, vlastních šablon To-do list, bug list, deprecated list
http://www.doxygen.org/ Otázky? Ukázky vygenerované dokumentace http://api.kde.org/ http://gnuradio.org/doc/doxygen/ http://www.stack.nl/~dimitri/doxygen/projects.html http://ci.apache.org/projects/httpd/trunk/doxygen/ Děkuji za pozornost.