More details

Doxygen needs some config-files (Doxyfile, doc/doxygen/*.html ...).
For wesnoth, these have already been set up.

About every item, doxygen keeps a brief and a detailed description.

The brief description should be short, i.e. a single line.

With the option "JAVADOC_AUTOBRIEF", the first sentence of the comment
up to the first dot or linebreak is taken as the brief description.
Otherwise, a blank line is used to separate brief and detailed description.

The detailed description can be as long as you want.

It should be at least 2 lines, so doxygen does not get confused,
e.g. thinking it found a second brief description for the same item :-)

Doxygen recognizes a lot of special keywords, the most important:

@file - description for a file

@todo - mark items for a special todo-list

@param - description for parameters for functions etc.

@return - general description of a return-value (e.g. "length of string")

@retval - description for special return-values (e.g. "-1 : error")

An an example, see fade_logo in titlescreen.cpp

How to document

Doxygen offers quite some options to document items the preferred way in
Wesnoth is:
/// to indicate the comment is a Doxygen comment
/** alternatively to start a Doxygen block comment which must end in */
@ to indicate Doxygen keywords

The following sections describe the preferred way to document certain items

functions

In the .hpp there will be a brief 1 line description

In the .cpp there will be a brief description (same as in the header)
and a longer description.
The following parameters can be used

@param - description for a parameter

@param[in] - description for a parameter if used as input parameter (only makes sense if @param[out] is also used)

@param[out] - description for a parameter if used as output parameter

@return - general description of a return-value (e.g. "length of string")

@retval - description for special return-values (e.g. "-1 : error")

example .hpp

/// lets you visit a bar
int foo(void* bar, int foobar);

example .cpp

/** lets you visit a bar
*
* foo is an action which lets you visit various bars in the
* galaxy, which can be rather nice.
*
* @param[in] foo points to the current bar object
* @param[out] foo points to the new bar object
* @param foobaar does nothing but was nice to allow a second parameter
*
* @return the number of bars visited
* @retval -1 no bars visited, something bad happened
* @retval 42 you feel rather enlightened and know the ultimate answer, if you only could remember the question
*/
int foo(void* bar, int foobar)
{
...
}