Writing a Well Documented Code With Doxygen

Goal : To give a push start on how to start with good well self 
       documenting code and generate a easy document using doxygen.
Pre-requiset : Doxygen installed on your ubuntu machine..
sudo apt-get install doxygen

Doxygen is a wonderful document generation application available for any programmer.
What I feel is, when you start coding with the intention of creating a document using Doxygen, you will end up with a awesome, well self explaining code ever.
Here is a simple example to start with using Doxygen for C program.

While creating a file, start always with the License header, which implies you code is reusable to a good scale.

/**
* DO WHAT THE FUCK YOU WANT TO PUBLIC LICENSE
* Version 2, December 2004
*
* Copyright (C) 2004 Sam Hocevar <sam@hocevar.net>
*
* Everyone is permitted to copy and distribute verbatim or modified
* copies of this license document, and changing it is allowed as long
* as the name is changed.
*
* DO WHAT THE FUCK YOU WANT TO PUBLIC LICENSE
* TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
*
* 0. You just DO WHAT THE FUCK YOU WANT TO.
*/

* The above License is actually a valid License, if anyone this that I am playing..
** This is the License created by the Ex-Debian Project Leader and a big contributor to VLC code Sam_Hocevar
Always give a description of what a file is going to contain and used for, with revision history. It will give you a better clarity on what has to be done and what is the purpose of having that file.

/**
* @file \file_name.c
* @author \you
* @date \today
* @brief This file is for blah blah drup doom code to invoke a thermo-nuclear
* war for fun.
* @param[in] argument1 - Used to simply say i have argument 1
* @param[in] argument2 - Used to simply say i have argument 2
* @param[in] argumentn - Used to simply say i have upto argument n
* @param[out] out argument1 - Used to simply say I am doing something upto
* provide a output
* @return - I do return a status of what happened inside this black hoel!!
*/

start with sections of what its going to do inside.. like..

/* Declaration of required variables */
..
.
.
..

/* I am going to sleep for n seconds */
sleep(n);

Name every variable as that is going to explain the need, like,

/* This variable is used to keep a count of
number of iterations happened and I feel
Its better to have a meaningful variable
name than to have like int i.. */

uint8_t iteration_count = 0;

So, Now you have your example code done..
Hope you will have a well self documented code by now..
Next, go and generate the Doxygen config file to produce the documentation.

cd /location/of/my/code/
doxygen -g
ls

This would have generated a file as Doxyfile

Now open and edit few things on this..

gvim Doxyfile

# PROJECT_NAME = "My Project"
# PROJECT_NUMBER =
# PROJECT_BRIEF =
# INPUT =
# RECURSIVE = NO

to

PROJECT_NAME = "Your Project Tilte"
PROJECT_NUMBER = "0.0.1"
PROJECT_BRIEF = "This is to learn Doxygen"
INPUT = /your/source/location/
RECURSIVE = YES

This is just a piece of cake… all the configuration variables are self explanatory.. explore more..

now, run,

doxygen Doxyfile
ls

Yes… Its done.. Go and open html/index.html.

you have your documentation for your code here in html..

You want in PDF? That too in latex??
Just install latex on your machine and follow this..

sudo apt-get install latex;

cd /your/source/code/location/latex;
make;

voila.. you are done…

Advertisements

Author: Shingu

Search in pursuit. Help me if you can.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s