Doxygen Conventions

Comment layouts

• boxed comments have the following layout:

  /**
   * Boxed comment example.
   */
  

Note: /** and */ are always in separate lines.

• class and function header file comments have the following layout

  /**
   * 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:

// 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:

/**
 * 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:

/**
 * 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