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 <firstname.lastname@example.org> * * 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..
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…