= Doxygen =
[[TOC]]

[http://www.doxygen.org 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. [[br]]
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 ==
  * [http://www.stack.nl/~dimitri/doxygen/docblocks.html this] for more info on doxygen-tags
  * [http://www.stack.nl/~dimitri/doxygen/commands.html this] for all possible doxygen-tags