ActiveSPLIT.com

Doxygen is a source code documentation generator tool.
Comment blocks are constructed like this: (JavaDoc style)

/**
*  multiline bloc… some text
*/

/// single ling comment… some text

“some text” can be replaced with various special commands in order to make the generated documentation more user friendly. Doxygen special commans overview.

———————–

Main project file should contain this:
@mainpage  used to customize the index page (in HTML) or the first chapter
@version  version number
@author  author name
@date  date-time
@note  optional note

Beginning of each file:
@file filename.ext
@brief brief description
@details detailed description

Before a variable:
@brief brief description
@details detailed description

Before function/method:
@brief
@param x info about x
@param y info about y
@return  info about return value
@details  detailed description

Before classes:
@class className
@brief
@details

Often used commands:

@see  reference
Starts a paragraph where one or more cross-references to classes, functions, methods, variables, files or URL may be specified. Two names joined by either :: or # are understood as referring to a class and one of its members. One of several overloaded methods or constructors may be selected by including a parenthesized list of argument types after the method name.

@bug Description of bug goes here
@warning Warning message goes here
@note notice here
@todo  todo message here
@par  paragraphTitle  paragraphConten

@code
code here
@endcode
——————–

Groups
You can let files appear as multi-level groupings under the Modules tab by assigning a file to a group.
@addtogroup  groupName  // put in a existing group or create new
@ingroup groupName    // put inside a group
@defgroup groupName  // defines a new group, I use addtogroup instead

Examples
@example <file-name>
Indicates that a comment block contains documentation for a source code example. The name of the source file is <file-name>.  Source files or directories can be specified using the EXAMPLE_PATH tag of doxygen’s configuration file.

Common project folder structure:
myProject/
|- Doxyfile
|- Makefile
|- README
|- bin/
|- data/
|- doc/
|- include/
|- src\

USAGE EXAMPLE, File beginning (QT Style notation)
you can put all of your doxygen relevant documentation in the header files.

/*! \file uart.h  \brief UART driver with buffer support. */

/// \ingroup driver_avr
/// \defgroup uart UART Driver/Function Library (uart.c)
/// \code #include “uart.h” \endcode
/// \par Overview
/// This library provides both buffered and unbuffered transmit and receive
/// functions for the AVR processor UART.  Buffered access means that the
/// UART can transmit and receive data in the “background”, while your code
/// continues executing.  Also included are functions to initialize the
/// UART, set the baud rate, flush the buffers, and check buffer status.
///
/// \note For full text output functionality, you may wish to use the rprintf
/// functions along with this driver.
///
/// \par About UART operations
/// Most Atmel AVR-series processors contain one or more hardware UARTs
/// (aka, serial ports). UART serial ports can communicate with other
/// serial ports of the same type, like those used on PCs. In general,
/// UARTs are used to communicate with devices that are RS-232 compatible
/// (RS-232 is a certain kind of serial port).
/// \par
/// By far, the most common use for serial communications on AVR processors
/// is for sending information and data to a PC running a terminal program.
/// Here is an exmaple:
/// \code
/// uartInit(); // initialize UART (serial port)
/// uartSetBaudRate(9600); // set UART speed to 9600 baud
/// rprintfInit(uartSendByte); // configure rprintf to use UART for output
/// rprintf(“Hello World\r\n”); // send “hello world” message via serial port
/// \endcode
///
/// \warning The CPU frequency (F_CPU) must be set correctly in \c global.h
/// for the UART library to calculate correct baud rates. Furthermore,
/// certain CPU frequencies will not produce exact baud rates due to
/// integer frequency division round-off. See your AVR processor’s
/// datasheet for full details.