Doxygen for generating great documentations

When you are writing a software which involves so many source files, so many functions and other stuff you will probably face to a software maintenance problem soon. When your code base grow larger you can't keep remembering what each and every component of your software doing out there. In addition to that any third party who is going to reuse your code or your provided API run into trouble without understanding your code properly. This is where you need a good documentation of your codes that help you and other parties in the long run.

Doxygen is an open source documentation tool which supports various programming languages. Currently it supports languages like C, Objective-C, Java, PHP, Python  and Fortran etc. When you are using Doxygen, you have to do is simply maintain a proper commenting standard all over your source codes. At the end the Doxygen tool will prepare a very nice documentation in both html and latex formats based on the comments you have put in your source code. As the Doxygen manual points out there are so many other formats that you can generate documentations using the Doxygen tool.

Here I'm going to show how to use Doxygen tool on the Linux platform. The vary first thing you have to do is to install Doxygen in your system. You can download Doxygen from here. I'm working on Ubuntu-10.10 and I downloaded the binary distribution of Doxygen-1.7.4 version. Installation is very simple.

1) Uncompress the downloaded commpressed file.

2) Move into that uncompressed directory from the terminal.
    cd Doxygen-1.7.4

3) Issue the command,
    sudo make install

4) Type "Doxygen"(without quotes) to make sure that it has installed. If everythings OK it will print,
    "Doxyfile not found and no input file specified!" and some other stuff.

I hope your installation went fine. Now you can dive into documentation generation part. For testing purposes you can use some simple programs that you have written some time back. Let's say you hava a directory named "my_software" which cantains so many source files of a software. Now you have to learn the format of the comments that you are going to put in that source files. There are different formats of comments that Doxygen supports. In this article I presents only the way I used to do it. You can explore it more.

Your comment follows the JavaDoc style. You can write your comment in the area marked as text. However even in that area there's a proper way to write your comment. You can use some tags that help the Doxygen tool to identify different important parts of your comment seperately.

1:  /**  
2:   * text text text  
3:   * text text text       
4:   * text text text  
5:   * text text text  
6:   */  

As an example say you have a function called count(). This is how you will put the comment.

1:  /*! \brief Brief description.  
2:   *     Brief description continued.  
3:   *  
4:   * Detailed description starts here.  
5:   */  
6:  int count(){  
7:       code lines...  
8:       code lines...  
9:  }  

You can notice that \brief tag is used to spacify a brief description. You put this comment right above the function that your are going to describe. If you want to put the comment below the function or in the same line of the function signature, refer the Doxygen manual how to do it. There are different tags available to specify different things just like the \brief tag. This comment style can be used to describe functions, variables and other segments of your source code.

To give a description of each source file you can use the following command at the top of each source file. Change the content of the comments as your requirements.

1:  /*  
2:   * Write anything here. May the licence details of your software and copyright details.  
3:   *   
4:   *  
5:   *  
6:   * \file  
7:   *   Small description about this file  
8:   * \author  
9:   *   write name and e-mail address of the author of this source file.  
10:   */  

Your documentation which is going to be generated from Doxygen has to have a main page which describe something about your software, how to compile the source etc. For this purpose you have to put a special comment. So, first select one of the source files that is linked to other files of the software directly or indirectly. Suppose you have header file which is included by most of the source files. Select that file. Put a comment like this inside that file some where. You can understand the places where you can change and fill with your own content. This will appear in the very first page of you documentation nicely.

1:  /*! \mainpage Name or Title or the Software or the Project.  
2:   *  
3:   * \section intro_sec Introduction(or any thing)  
4:   *  
5:   * bla bla bla  
6:   * more and more bla  
7:   *  
8:   * \section install_sec How to Install(or any thing)   
9:   *  
10:   * \subsection creating_sub_sec Compiling(or any thing)   
11:   *   
12:   * bla bla and bla  
13:   * bla and bla bla  
14:   *   
15:   *   
16:   */  

Now it's time to generate your documentation. Follow the steps below for it.

1) Move into the directory which contains your source files say "my_software" from linux terminal.
    cd my_software

2) Type this command which generate the configuration file. It will create the file called "Doxyfile".
    doxygen -g

3) Now issue this command to have your documentation at hand,
    doxygen Doxyfile

Now if you look at the source files directory you will notice that there are some new directories create inside it like "html", "latex". Open the file named "index.html" inside the "html" directory using your favourite web browser. You will be Surprised!
Enjoy happy documenting with Doxygen!