# Doxygen Documentation Template

###### tags: `Documentation`

[TOC]

Doxygen documentation can be generated in many formats(HTML, LaTeX, RTF, PDF, DOC) . HTML generation has support for more plugins and is easier to refactor as the system changes. Doxygen style should follow a consistent format to aid development across different IDEs. Additionally, it reduces issues when generating documentation.

/**
 * @tagname
 */

This is an example of a Java doc style Doxygen tag, since it uses the “@” symbol. Tags using the “\tagname” style are considered Qt style Doxygen tags.

There should be a header file containing only Doxygen tags or a separate Doxygen file that acts as a guide for the components, classes, methods, and variables (e.g. DoxygenMainpage.h). This can be done using the @mainpage tag at the top of the file.

## System

There should be a header file containing only Doxygen tags or a separate Doxygen file that acts as a guide for the components, classes, methods, and variables (e.g. DoxygenMainpage.h). This can be done using the @mainpage tag at the top of the file.

/**
 * @mainpage                    Title of Document
 *                                          
 */

Example of HAL system Doxygen Guideline (Note: source code was also modified to support correct generation of documentation)

## File
A file should contain the @file tag at the top of the file. This supports generation of a file list tab on the main page. It also helps when files contain multiple classes.

/**
 * @file               FileName.h
 *
 * @brief              Brief file description.
 *            
 *                     Verbose file description.
 */

## Classes
Classes can be tagged in a number of different ways, but in general they are tagged using the @brief and @class tags before the class declaration. Having the @author, @date, and @version supports tractability as the system is versioned throughout the software lifecycle. When updating classes, update comments like this:

#include <iostream>
using namespace std;
 
 
/**
 * @brief              Brief class description
 *
 *                     Verbose description of class.
 *
 * @class              Class Name
 */
 
class ClassName {
               public:
                      ClassName();
                      ~ClassName();
 
                      int var1;         /**< Comment about public member variable*/
 
                      /**
                       *@brief           Brief method description
                       *
                       *                 Verbose description of method
                       *
                       *@param           Parameter in the method’s definition
                       *
                       *@return          Return value of method
                       */
                      int Function1(int x);
 
               protected:
                      int var2;         /**< Comment about protected member variable*/
 
                      /**
                       *@brief            Brief method description
                       *
                       *                  Verbose description of method
                       *
                       *@param            Parameter in the method’s definition
                       *
                       *@return           Return value of method
                       */
                      int Function2(int x);
 
               private:
                     int var3;          /**< Comment about private member variable*/
 
                      /**
                       *@brief            Brief method description
                       *
                       *                  Verbose description of method
                       *
                       *@param            Parameter in the method’s definition
                       *
                       *@return           Return value of method
                       */
                      int Function3(int x);
 
};

## Structs
A struct can be tagged in the same way a class, but it is best to use the @struct tag. When updating structs, update comments like this:

/**
 *@brief             Brief struct description
 *
 *@struct            Struct Name
 */

## Methods
Methods can be tagged in a number of ways, but in general the @brief, @details, @param, and @return tags are used before a method’s declaration or implementation. When updating methods, update comments like this:

/**
 *@brief              Brief method description
 *
 *                    Verbose description of method
 *
 *@param              Parameter in the method’s definition
 *
 *@return             Return value of method
 *@retval             Verbose explanation of return values
 */
int addNumbers(int x)
{
    int sum = 0;
    sum += x; 
    return sum; 
}

## Variables
When updating variables, update comments like this:

int number;     /**< Comment about number*/

## Enumerated Types
Enumerated types are tagged using the @enum. When updating enum types, update comments like this:

/**
 *@brief          Brief enum description
 *
 *@enum           enum Name
 */

## Miscellaneous
There are many tags you can use with HTML markup to create unique Doxygen documentation for a given file, class, method, or variable. The following are common tags that should be used when appropriate.

/**
 *@note           A brief remark about the implementation to help clarify.
 *
 *@attention      An important remark that may cause code to break.
 *
 *@warning        An import remark that may depend on random conditions etc.
 *
 *@see            A reference to a class or a link to documentation (e.g. http://document.1a.com)
 */

/**
 *@bug            A remark about a known bug in the code.
 *
 *@todo           A remark of what needs to be done to fix issues or remaining work.
 *
 */

/**
 *@a              Formats following word in special font (used for hyperlinks)
 *
 *@b              Formats following word in bold
 *
 *@em             Formats following word in italic
 *
 *@c              Formats following word in monospaced typewriter font
 *
 */

/**
 * - bulleted list item1
 *  - sub bulleted item1   
 *
 * - bulleted list item2
 *
 */

/**
 * -# numbered list item1
 * -# numbered list item2
 *
 */

/**
 *@code
    i++;
 *@endcode
 */

## Source
https://wiki.rdkcentral.com/display/RDK/Doxygen+Guideline