= Doxygen Conventions =

== Comment layouts ==

 * boxed comments have the following layout:
{{{
#!cpp
/**
 * Boxed comment example.
 */
}}}	
'''Note:''' {{{/**}}} and {{{*/}}} are always in separate lines.
 * class and function header file comments have the following layout 
{{{
#!cpp
/**
 * Short class description goes here ending with dot.
 *
 * Second sentence is here.
 * Third sentence is here.
 */
class my_class : public base_class
{
public:
    /**
     * Brief description.
     *
     * Function header documentation goes here.
     *
     * @param parameter Parameter description.
     * @return Description of the returned value
     */
    int my_function( int parameter );
    ...
}
}}}
 * these comments are recognized by the Doxygen tool, which can generate HTML documentation for classes. For this reason, the comment has to start with {{{/**}}} instead of {{{/*}}}. Keep the {{{/**}}} and {{{*/}}} in a separate line. 

== Header documentation ==

'''Example''':

{{{
#!cpp
// Copyright (C) 2012-2013 ChaosForge / Kornel Kisielewicz
// http://chaosforge.org/
//
// This file is part of NV Libraries.
// For conditions of distribution and use, see copyright notice in nv.hh

/**
 * @file file_name.hh
 * @author Name Surname name.surname(at)mailadress.com
 * @brief Brief description
 *
 */

#ifndef NV_CLASS_NAME_HH
#define NV_CLASS_NAME_HH

#include <nv/common.hh>
#include <system_header>
#include <system_header2>

#include <nv/...>
#include <nv/...>

namespace nv
{

// Code goes here...

} // namespace nv

#endif // NV_CLASS_NAME_HH

}}}

'''Notes:'''
 * author is the person mainly responsible for the class, or the one that wrote the most code of it
 * copyright date should match current year
 * use "@" for doxytags, not "\"
 * file description can be a single brief line if the file constitutes of a single class and the class is well documented

== Class documentation ==

'''Example''':
{{{
#!cpp
/**
 * An interesting class.
 * 
 * A more elaborate multiline class description, 
 * 
 * @see another_class
 */
class class
{
}; // class
}}}
'''Notes''':
 * description should be as elaborate as possible
 * include any see also information
 * include any revelant note, todo, warning and pre/post conditions if applicable to the whole class
 * if class throws exceptions, write about which ones

== Method/function documentation ==

'''Example''':
{{{
#!cpp
/**
 * A brief description.
 *
 * A normal function taking two arguments and returning an integer value.
 *
 * @param param an integer argument.
 * @param another a constant character pointer.
 * @return A funny value.
 *
 * @throws funny_exception on error
 */
uint32 funny_function( int param, const char* another );
}}}
'''Notes''':
 * param, return and throw are all mandatory descriptions
 * any warnings, pre and post conditions, etc. are welcome