Planet
navi homeaboutscreenshotsdownloaddevelopmentforum

Doxygen

TracNav(TracNav/TOC_Development)?

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

Also see

  • this for more info on doxygen-tags
  • this for all possible doxygen-tags
Last modified 9 years ago Last modified on Sep 21, 2008, 8:39:40 PM