REU 2005 Doxygen

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

// generated by Fast Light User Interface
Designer (fluid) version 1.0100 include
"Example.h" inline void HelloWorldUIcb_Change_i
(Fl_Button o, void) if (o-gtvalue())
o-gtlabel("Hello World") dis-gtlabel("Change
it") else o-gtlabel("Change it")
dis-gtlabel("Hello World") o-gtredraw() dis-gtred
raw() void HelloWorldUIcb_Change(Fl_Button
o, void v) ((HelloWorldUI)(o-gtparent()-gtuser
_data()))-gtcb_Change_i(o,v)
HelloWorldUIHelloWorldUI() Fl_Window w
Fl_Window o win new Fl_Window(340, 409,
"HelloWorld") w o o-gtlabeltype(FL_NORM
AL_LABEL) o-gtuser_data((void)(this))
Fl_Tile o dis new Fl_Tile(25, 130, 265, 255,
"Hello World") o-gtbox(FL_SHADOW_BOX)
o-gtend() Fl_Button o new
Fl_Button(120, 15, 215, 50, "Change it")
o-gttype(1) o-gtdown_box(FL_UP_BOX)
o-gtcallback((Fl_Callback)cb_Change)
o-gtend() int main(int argc, char argv)
HelloWorldUI main_window new
HelloWorldUI() main_window-gtwin-gtshow(argc,
argv) return Flrun()
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
ltFL/Fl.Hgt include ltFL/Fl_Window.Hgt include
ltFL/Fl_Tile.Hgt include ltFL/Fl_Button.Hgt 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 ltFL/Fl.Hgt include
ltFL/Fl_Window.Hgt include ltFL/Fl_Tile.Hgt include
ltFL/Fl_Button.Hgt ////////////////////////////////
/////////// /// /// 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
HelloWorldUIHelloWorldUI() Fl_Window w
Fl_Window o win new Fl_Window(340, 409,
"HelloWorld") w o o-gtuser_data((void)
(this)) Fl_Tile o dis new Fl_Tile(25,
130, 265, 255, "Hello World")
o-gtbox(FL_SHADOW_BOX) o-gtend()
Fl_Button o new Fl_Button(120, 15, 215, 50,
"Change it") o-gttype(1)
o-gtdown_box(FL_UP_BOX) o-gtcallback((Fl_Call
back)cb_Change) o-gtend() /!
\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-gtwin-gtshow(argc, argv) return
Flrun()

• 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
HelloWorldUIcb_Change_i(Fl_Button o, void)
if (o-gtvalue()) o-gtlabel("Hello World")
dis-gtlabel("Change it") else
o-gtlabel("Change it") dis-gtlabel("Hello
World") o-gtredraw() dis-gtredraw() void
HelloWorldUIcb_Change(Fl_Button o, void v)
((HelloWorldUI)(o-gtparent()-gtuser_data()))-gtcb_C
hange_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