June 2009 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

June 2009 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.

June 2009 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

June 2009 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

June 2009 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

June 2009 1

Undocumented Code Example

// 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);}

• Example.cppHelloWorldUI::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();}

June 2009 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 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 = ExamplePROJECT_NUMBER = 1OUTPUT_DIRECTORY = Docs1EXTRACT_ALL = YESEXTRACT_PRIVATE = YESEXTRACT_STATIC = YESINPUT = .FILE_PATTERNS = *.cpp *.hRECURSIVE = YESINLINE_SOURCES = YES

June 2009 1

Undocumented Code Output

• After configuration, running doxygen will generate the documentation

• Docs1/index.html

June 2009 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

June 2009 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

June 2009 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 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

June 2009 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 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();}

June 2009 1

Example Output

• After configuration, running doxygen will generate the documentation

• Docs2/index.html

June 2009 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:– 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

June 2009 1

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

June 2009 1

More Information

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

www.doxygen.org