Doxygen A Code Documentation System Doxygen generates documentation

Doxygen A Code Documentation System • Doxygen generates documentation directly from the structure and comments in the code – Browsable HTML documentation – Printable La. Te. X 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 2004 1

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 2004 1

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 2004 1

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 2004 1

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 2004 1

Undocumented Code Example • Example. cpp // generated by Fast Light User Interface Designer (fluid) version 1. 0100 #include "Example. h" inline void Hello. World. UI: : 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 Hello. World. UI: : cb_Change(Fl_Button* o, void* v) { ((Hello. World. UI*)(o->parent()->user_data()))->cb_Change_i(o, v); } July 2004 Hello. World. UI: : Hello. World. UI() { Fl_Window* w; { Fl_Window* o = win = new Fl_Window(340, 409, "Hello. World"); 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) { Hello. World. UI* main_window = new Hello. World. UI(); main_window->win->show(argc, argv); return Fl: : run(); } 1

Undocumented Code Example • Example. h // 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 Hello. World. UI { public: Hello. World. UI(); Fl_Window *win; Fl_Tile *dis; private: inline void cb_Change_i(Fl_Button*, void*); static void cb_Change(Fl_Button*, void*); }; #endif July 2004 • Doxyfile Changes PROJECT_NAME = Example PROJECT_NUMBER = 1 OUTPUT_DIRECTORY = Docs 1 EXTRACT_ALL = YES EXTRACT_PRIVATE = YES EXTRACT_STATIC = YES INPUT =. FILE_PATTERNS = *. cpp *. h RECURSIVE = YES INLINE_SOURCES = YES 1

Undocumented Code Output • After configuration, running doxygen will generate the documentation • Docs 1/index. html July 2004 1

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 2004 1

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 2004 1

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 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 Hello. World. UI { public: July 2004 /*! * The class constructor */ Hello. World. UI(); /*! * The main window pointer */ Fl_Window *win; /*! * The class constructor */ Hello. World. UI(); /*! * 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 1

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 1. 0100 #include "Example. h" inline void Hello. World. UI: : 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 Hello. World. UI: : cb_Change(Fl_Button* o, void* v) { ((Hello. World. UI*)(o->parent()->user_data()))>cb_Change_i(o, v); } July 2004 Hello. World. UI: : Hello. World. UI() { Fl_Window* w; { Fl_Window* o = win = new Fl_Window(340, 409, "Hello. World"); 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 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) { Hello. World. UI* main_window = new Hello. World. UI(); main_window->win->show(argc, argv); 1 return Fl: : run(); }

Example Output • After configuration, running doxygen will generate the documentation • Docs 2/index. html July 2004 1

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: – – – July 2004 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 1

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

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