Doxygen A Code Documentation System

1. DoxygenA Code Documentation System • Doxygen generates documentation directly from the structure and comments in the code • Browsable HTML documentation • Printable LaTeX documentation • man pages • Can be used with multiple programming languages • C++, C, Java, Objective-C, IDL • Can extract structures from undocumented source code • Configurable to generate various types of documentation

2. Doxygen • Doxygen uses a configuration file to determine • Wich code to extract documentation from • What type of documentation to create • Doxygen uses the structure of the code to build • Class relations and diagrams • Index of functions and methods • Links between classes and methods and the locations they are used • Doxygen uses special comments to • Provide descriptions of classes, methods, parameters, etc.

3. Configuring Doxygen • To use Doxygen a configuration file has to be created and configured • doxygen -g generates the generic configuration file Doxyfile • Configuration files contain a number of tag assignments TAGNAME = VALUE that can be changed to obtain the desired documentation • INPUT tag defines the code files or directories • RECURSIVE indicates it subdirectories should be included • FILE_PATTERNS defines which files to build documentation for

4. Configuring Doxygen • Tags define what parts within the code should be documented • EXTRACT_ALL indicates if documentation should also be created for parts without documentation comments • EXTRACT_PRIVATE indicates if private members of classes should be included • EXTRACT_STATIC indicates if static members should be extracted • SOURCE_BROWSER defines if links to the source code should be created • INLINE_SOURCES can be used to include the relevant parts of the code into the documentation

5. Configuring Doxygen • Tags define what type of documentation should be created • OUTPUT_DIRECTORY defines where the documentation should be placed • HTML_OUTPUT, RTF_OUTPUT, LATEX_OUTPUT, MAN_OUTPUT, indicate if documentation in the particular format should be created

6. Undocumented Code Example • Example.cpp HelloWorldUI::HelloWorldUI() { Fl_Window* w; { Fl_Window* o = win = new Fl_Window(340, 409, "HelloWorld"); w = o; o->labeltype(FL_NORMAL_LABEL); o->user_data((void*)(this)); { Fl_Tile* o = dis = new Fl_Tile(25, 130, 265, 255, "Hello World"); o->box(FL_SHADOW_BOX); o->end(); } { Fl_Button* o = new Fl_Button(120, 15, 215, 50, "Change it"); o->type(1); o->down_box(FL_UP_BOX); o->callback((Fl_Callback*)cb_Change); } o->end(); } } int main(int argc, char **argv) { HelloWorldUI* main_window = new HelloWorldUI(); main_window->win->show(argc, argv); return Fl::run(); } // generated by Fast Light User Interface Designer (fluid) version 1.0100 #include "Example.h" inline void HelloWorldUI::cb_Change_i(Fl_Button* o, void*) { if (o->value()) { o->label("Hello World"); dis->label("Change it"); } else { o->label("Change it"); dis->label("Hello World"); } o->redraw(); dis->redraw(); } void HelloWorldUI::cb_Change(Fl_Button* o, void* v) { ((HelloWorldUI*)(o->parent()->user_data()))->cb_Change_i(o,v); }

7. Undocumented Code Example • Example.h • Doxyfile Changes PROJECT_NAME = Example PROJECT_NUMBER = 1 OUTPUT_DIRECTORY = Docs1 EXTRACT_ALL = YES EXTRACT_PRIVATE = YES EXTRACT_STATIC = YES INPUT = . FILE_PATTERNS = *.cpp *.h RECURSIVE = YES INLINE_SOURCES = YES // generated by Fast Light User Interface Designer (fluid) version 1.0100 #ifndef helloworld_h #define helloworld_h #include <FL/Fl.H> #include <FL/Fl_Window.H> #include <FL/Fl_Tile.H> #include <FL/Fl_Button.H> class HelloWorldUI { public: HelloWorldUI(); Fl_Window *win; Fl_Tile *dis; private: inline void cb_Change_i(Fl_Button*, void*); static void cb_Change(Fl_Button*, void*); }; #endif

8. Undocumented Code Output • After configuration, running doxygen will generate the documentation • Docs1/index.html

9. Documenting Code • Documentation for Doxygen is created by including special comment blocks in the code • Doxygen supports multiple types of comment blocks • C style with extra * : /** This is a C style comment block */ • C++ style with extra / or ! : /// This is a C++ style comment • The basic elements of documentation are brief and detailed descriptions • Brief descriptions are single line comments • Detailed descriptions are more elaborate • If both are used they have to be separated either in a different comment block, by adding an empty comment line, or by preceding the brief description with \brief

10. Documenting Code • Brief and detailed description for classes, methods, and members of a class do not require a keyword. • In methods, parameters and return values can be indicated with the \param and \return keywords • Annotations for files, functions, variables, etc. require keywords for doxygen to be able to assign them • \file precedes descriptions for files • \var precedes global variables • \fn precedes funcions • Within function blocks, \param and \return indicate parameters and return values • \warning can be included to point out problems

11. Documentation Example /*! * The class constructor */ HelloWorldUI();/*! * The main window pointer */ Fl_Window *win; /*! * The class constructor */ HelloWorldUI(); /*! * The pointer to the toggle button */ Fl_Tile *dis; private: /*! * This method inlines the callback code to make it permanently visible * \param o A pointer to the widget * \param v A pointer to additional data */ inline void cb_Change_i(Fl_Button* o, void* v); /*! * The main callback function * \param o A pointer to the widget * \param v A pointer to additional data */ static void cb_Change(Fl_Button* o, void* v); }; #endif • Example.h /*! * \file Example.h * \brief User Interface Header * * The header file for the user interface */ // generated by Fast Light User Interface Designer (fluid) version 1.0100 #ifndef helloworld_h #define helloworld_h #include <FL/Fl.H> #include <FL/Fl_Window.H> #include <FL/Fl_Tile.H> #include <FL/Fl_Button.H> /////////////////////////////////////////// /// /// This is the brief description of the user interface class /// /*! This class is used for the windos and contains the callback functions for the button that causes the swapping of the labels */ /////////////////////////////////////////// class HelloWorldUI { public:

12. Documentation Example HelloWorldUI::HelloWorldUI() { Fl_Window* w; { Fl_Window* o = win = new Fl_Window(340, 409, "HelloWorld"); w = o; o->user_data((void*)(this)); { Fl_Tile* o = dis = new Fl_Tile(25, 130, 265, 255, "Hello World"); o->box(FL_SHADOW_BOX); o->end(); } { Fl_Button* o = new Fl_Button(120, 15, 215, 50, "Change it"); o->type(1); o->down_box(FL_UP_BOX); o->callback((Fl_Callback*)cb_Change); } o->end(); } } /*! * \fn int main(int argc, char **argv) * The main program * The main program operns up the window and then waits for mouse * events in the run loop * \param argc Number of arguments passed in on the command line * \param argv A pointer to an array of pointers to the arguments * \return Returns the error code upon termination * \warning Warnings are a good idea if particular pars are not * implemented */ int main(int argc, char **argv) { HelloWorldUI* main_window = new HelloWorldUI(); main_window->win->show(argc, argv); return Fl::run(); } • Example.cpp /*! * \file Example.cpp * \brief User Interface Implementation * * The implementation file for the user interface */ // generated by Fast Light User Interface Designer (fluid) version 1.0100 #include "Example.h" inline void HelloWorldUI::cb_Change_i(Fl_Button* o, void*) { if (o->value()) { o->label("Hello World"); dis->label("Change it"); } else { o->label("Change it"); dis->label("Hello World"); } o->redraw(); dis->redraw(); } void HelloWorldUI::cb_Change(Fl_Button* o, void* v) { ((HelloWorldUI*)(o->parent()->user_data()))->cb_Change_i(o,v); }

13. Example Output • After configuration, running doxygen will generate the documentation • Docs2/index.html

14. Generating Graphical Documents • Doxygen also creates graphical representations (using the dot tools) for the code structure such as: • Class diagrams, Include and Collaboration graphs, etc. • The location of the dot tools has to be indicated using the DOT_PATH variable in the configuration file • For this to work HAVE_DOT has to be set to YES • Graphs are enabled using definitions in the doxygen configuration file: • GRAPHICAL_HIERARCHY – display class hierarchy • CLASS_GRAPH – shows inheritance relations • INCLUDE_GRAPH – shows include dependencies • COLLABORATION_GRAPH – shows inheritance and usage • CALL_GRAPH – shows call relationship

15. Example Output • After configuration, running doxygen will generate the documentation • Docs3/index.html • For this simple program only include graphs will be created under the File Lists tab

16. More Information • More information and a complete list of possible keywords can be found in the Doxygen manual at www.doxygen.org