Doxygen is a documentation system for several languages like C++. It can generate an on-line documentation browser (in HTML), a set of manpages, an off-line reference manual (in LaTeX) and/or others from the set of documented source files of your project. This kind of documentation is a necessary tool for developers to find informations about the code. It is not a way to explain how it is imagined but which possibilities you have. It is available for several distributions like Fedora Core, Debian, Gentoo and others,.. Windows, MacOs and Sun Solaris too.
To create your first Doxygen documentation, you need a config file .cfg or .doxygen. To generate it :
doxygen [-g myfile.doxygen]
The file contains the options you can choose for the documentation generation. Comments indicates how to use this variables. The INPUT variable contains the files or directories to find the source files. When you have set all tags with good values, you can generate the documentation. Doxygen checks the source files to extract the informations in special comments and tags. See this page for the informations about the variables : http://www.stack.nl/~dimitri/doxygen/config.html. To create it :
doxygen [myfile.doxygen]
By default, it creates directories : html, latex, and/or man, ...
For the Tulip project, It exists two documentations. One is destinated for the Developer team and this other one is for the user of the librairies. The Configuration files are generated by the Makefile processing.
The code documentation, generated by Doxygen is completely dependant of the developer comments. It is important that developers follow the grammar rules.
So the blocks of documentation in the sources files are the C++ comment blocks. For each item of code, there are two types of descriptions, which together form the documentation : a brief description and detailed description. A detailed description is used to explain generously the existence of an item.
/** * detailed description */ or /*! * detailed description */ or /*! detailed description */ or others ....
To make a brief description, you can use the command \brief. This command ends at the end of a paragraph, so the detailed description follows after an empty line. An other option is to use a special C++ style comment which does not span more than one line.
/*! \brief Brief description............. * ............... * * Detailed description */ or /// Brief description /** Detailed description. */ or //! Brief descripion. //! Detailed description //! starts here. or others ....
For more details, the web site of Doxygen explains it.
In general, the comments must be before the declaration or definition of a type, a function or a member. If you want to putting the documention after, you have to add a marker <. Note that you can place your comment at other places using some tags like \class, \union, \fn, \var, ... or @class, @union, @fn, @var, ...
It exists several tags to help you for commenting and writing a description : all of it begin with a backslash \ or an at-sign @.
@author, name of the author.
@param, to write a special comment on a parameter of a method or function
@see, to make a reference to an other object or function
@return, to indicate the exit of a function
@date, date of creation
@note, describe a role
@attention, write a caution
@warning, write a warning
@pre, write a prerequisite
@remark
The complete list is on this page in the Doxygen web site.
Example 9.1. Doxygen : A simple source file
// ... comments not include ...
/// A example of class : MyClass.
/**
a more detail class description :
\author Me
\date 29/07/2005
*/
#include <string>
class MyClass
{
/* ... comments not include ... */
public:
/** the constructor of the class */
/** the detail description of the constructor. */
MyClass(){i=0;}
//! A destructor.
~MyClass(){}
/// drawing of a string
/**
\param s the string to display
\return there is no return
@sa MyClass(), ~MyClass()
*/
void draw(const char *s="Hello World");
/* exemple of doc comments not before the declaration */
unsigned int getI(){return i;} /**<@return the number
the value of i */
private:
unsigned int i;
/** @var i
@brief, you can put the comments where you want
with the special tags */
};
To update the Documentation of Tulip, you just have to use the makefile and so write : make docs.
1. | How to insert a block of code ? |
To illustrate your documentation, you can insert a block of code in a description between | |
2. | How to force an end of line ? |
Use the tag | |
3. | How to make doxygen ignore code fragment ? |
It exists two ways to resolve this questions. The first one is to use the tags #ifndef MACROS_NAME /* code that must be skipped by Doxygen */ #endif /* MACROS_NAME */ Two macros are defines for Tulip documentations.
| |
4. | How to insert a equation ? |
See the Doxygen web site Doxygen allows you to put Latex formulas in the ouput (just for HTML and latex format). Three ways are avaible. If you want to include formulas in-text, you have to put formulas between a pair of “\f$”
\f$ AB = \sqrt{BC^2 + CA^2} \f$
The second way is for a centered display on a seperate line. These formulas should be put between The third way is to used formulas or other latex elements that are not in a math environment. It can be specified using |