Steps For Generating Document On Doxygen

Generating Document using doxygen

In simple Steps.
1) In every (.c or .h) file put this comment after includes.
---------------------------------------------------------------------
/** \file filename.ext
* \brief some notes about this file.
*
* A more extensive description of this file.
*/

Example:
/** \file function.h
* \brief This file contains prototypes for functions defined in function.c.
*
* This file contains prototypes for functions defined in function.c.
*
*/

NOTE: Period '.' is necessary after \brief sentence.

2) Before every function put this comment:
---------------------------------------------------
/** \brief A brief description of my_function().
*
* A more extensive description of my_function().
*
* \param aParameter A brief description of aParameter.
* \param bParameter B brief description of bParameter.
* \return A brief description of what myProcedure() returns.
*/

Example:
/** \brief get position of field in configfile.
*
* This function returns the position of the
* field in the config file………………….
* ………………………………………....
*
* \param i index of field.
*
* \return returns position of the field in configfile.
*
*/

3)Just before each variable, put these comments.
------------------------------------------------------------
Example:
/** \brief A brief description of myVariable.
*
* A more extensive description of myVariable.
*/

int myVariable;

Note: use it only for important variables:

4)Just before each enumeration put these comments.
----------------------------------------------------------------
/**
* \enum some description about this enum.
*/

Beside each field write some description inside /**< description */
Example:
enum Fields {
Factory_State, /**< Factory State Flag */
Login_Password, /**< Password required to login */
Model_Name, /**< Model Name of the SerialServer */
MAC_Address, /**< MAC Address of the SerialServer */
. . . .
};

5)Just before each structure put these comments ------------------------------------------------------------
/**
* \struct some description about this enum.
*/
beside each field write some description inside /**< description */
Example:
struct nw2serial_s {
struct mcs7840 * mcs7840_dev; /**< serial device structure */
spinlock_t lock; /**< spinlock for list operations */
unsigned char number; /**< unknown */
. . . . .
};
Note: for enum and typedef just change the \struct tag to \enum or \typedef.

Project Description for main page:
--------------------------------------------
In main file. keep this description at the beginning of file.
/*
* \mainpage
* write description here.
*
*
*
*/

For TODO put this comment:
-----------------------------------
/**
* \todo keep todo description here.
*
*/

For more doxygen tags manual Creating documents:

cd to the directory containing source files and type.

$doxygen –g

example:

$doxygen -g ssdoc

This will create a configuration file called ssdoc.

Open ssdoc and modify it.

Set the tags PROJECT_NAME , PROJECT_NUMBER

Example:

PROJECT_NAME = MCS8140-SS-16S

PROJECT_NUMBER = 1.0.0.2

If you want header, footer and CSS files then run

$doxygen –w html header.html footer.html stylesheet.css

This will create header.html , footer.html and doxygen.css files,
now set paths for HTML_HEADER, HTML_FOOTER, and HTML_STYLESHEET tags in configuration file (ssdoc)
example

HTML_HEADER = header.html
HTML_FOOTER = footer.html
HTML_STYLESHEET = doxygen.css

finally run doxygen.

$doxygen ssdoc

This will create two folders ./html and ./latex

For html document open ./html/index.html file.

To get an image above the document modify the header.html file and run doxygen again.
Example:
Modify css to get different colors.

Creating PDF document:
--------------------------------------
To create pdf document just cd to ./latex folder
and type

$make

This will create a pdf refman.pdf in ./latex folder.