| Version 1 (modified by landauf, 16 years ago) (diff) |
|---|
Doxygen
TracNav(TracNav/TOC_Development)?
Table of Contents
Doxygen is a programm that generates a developers manual out of special comments in .cc and .h files.
The main Tags we use are described below:
Introductory Comment
Every file that contains source code must be documented with an introductory comment that provides information on the file name and its contents:
/**
@file
@brief
A brief description.
More description... (new paragraph after @brief)
*/
Note: try not to fill in the filename. It is obvious and the comment compiler (Doxygen) will do it automatically and you don't have to adjust it when renaming the file.
Classes and Structs
In the header file, just above the class declaration, explain what the class does and where it is used. You could even add an example if it helps understanding the class.
/**
@brief
A brief description.
More brief description.
Details follow here.
Maybe an example or something.
*/
class ClassName
{
...
Class Members
Add a brief description to every member of a class:
private:
int value_; //!< A brief description
int longerValueName_; //!< A brief description
The < after ! indicates that the member is located in front of the comment instead of after the comment.
If you need a more detailed description, use:
private:
int value_; //!< A detailed description
//!< More detailed description
//!< ...
or
private:
int value_; /**<
A detailed description
More detailed description
...
*/
Functions
Doxygen documentation (javadoc like for C++) is placed in the source file, just above the function header. If the function is inline, place the comment there but keep it short.
When writing documentation in the source file don't make it all jam-packed to enhance readability. Here is an example to demonstrate formatting:
/**
@brief
A brief description.
More brief description.
Details follow here.
Maybe an example or something.
@param param1
Parameter description for parameter named 'param1'
@param param2
Parameter description for parameter named 'param2'
@return
Describe what the function returns
@note
Something important to remember.
@author
The mighty whoever
*/
returntype functionname(type1 param1, type2 param2)
{
...
Inline Functions
Inline functions need documentation as well, but we don't want a messy headerfile. Keep the comments short and put all doxygen code on one line:
/** @brief A brief description. @param param1 description [...] @return description */
inline returntype functionname(type1 param1 [, ...]) { ... }
Full Example
MyClass.h file:
/**
@file
@brief
A brief description of the file, the classes and macros; links to other files.
More description... (new paragraph after @brief)
Maybe an example or something.
*/
/**
@brief
A brief description of the class
Details follow here.
More details...
*/
class MyClass
{
public:
/** @brief A brief description of the inline function. @return description */
inline int getValue() const { return this->value_; }
void setValue(int value);
private:
int value_; //!< A brief description of the value
};
MyClass.cc:
/**
@brief
A brief description of the function.
More brief description.
Details follow here.
Maybe an example or something.
@param value
Parameter description for parameter named 'value'
*/
void MyClass::setValue(int value)
{
if (value > 0 && value < 10)
this->value_ = value;
}
