Short Documentation Guide

Style for header comments:

/**
* @brief
* @param
* @return (not necessary if void)
*/ (Doxygen requires (!) no linefeed between docstrings and documented class/function)

Style for code comments:

//code comment

Style for class members:

Place documentation of class members in same line after declaration like this      /**< comment (musn't be longer than one line) */

What should be documented:

Classes:

@file
@brief Description about the functionality which is provided by the class

Constructors:

@brief Provide information about how the instanciated object will be initialized
@param describe Input-Parameters, because it might not be ovious to everybody what they might belong to, where they might come from

Functions:

@brief description about what function is used for or what it does
@param describe parameter and provide information about parameter-modification in function if parameter is modified

class members:

short description about what the class member represents

Code:

Please provide code documentation right away when writing new code.
Either you will need it yourself a few days after you wrote the code (and totally forgot what you were thinking...) or somebody else will have a much easier job to check your code or maintain the software even months later.

Some words in general:

It saves anybody a lot of time to find documentation exactly where needed, so don't be shy to write similar phrases more than once or duplicate them if needed in different docstrings.

Descriptions should always be easy to find and to understand. Which means:
Right in front of/next to the code.
Keep it simple, avoid using technical terms unless necessary.

Use easy language, especially on public documentation pages for users. (All docstrings except the code comments will be extracted by doxygen for the Documentation Webpage)

Also consider: Neatly documented software is much more user-friendly.