Transcript Doxygen A Code Documentation System

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 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 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);
}
July 2004
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();
}
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
July 2004
• 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
1
Undocumented Code Output
• After configuration, running doxygen will generate
the documentation
• Docs1/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 HelloWorldUI {
public:
July 2004
/*!
* 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
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);
}
July 2004
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();
1
}
Example Output
• After configuration, running doxygen will generate
the documentation
• Docs2/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:
– 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 2004
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
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