July Doxygen A 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

July 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.

July 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

July 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

July 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

July Undocumented Code Example // generated by Fast Light User Interface Designer (fluid) version #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); } 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(); }

July Undocumented Code Example Example.h // generated by Fast Light User Interface Designer (fluid) version #ifndef helloworld_h #define helloworld_h #include 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 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

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

July 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

July 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

July Documentation Example 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 #ifndef helloworld_h #define helloworld_h #include /////////////////////////////////////////// /// /// 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: /*! * 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

July Documentation Example 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 #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); } 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(); }

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

July 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

July 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

July More Information More information and a complete list of possible keywords can be found in the Doxygen manual at