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.
Comments