My Tech notes: Steps For Generating Document On Doxygen
Subscribe

Unix Documentation

Free Online Unix Training Materials

Lists many links to free Unix training materials.

Pointers and Arrays Materials

Pointers and Arrays materials Explained for C beginners

C FAQ and General Questions C Interview Questions

Powered By

Free XML Skins for Blogger

Powered by Blogger

Thursday, August 7, 2008

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.

No comments:

Post a Comment