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!

Generating Doc files from Php in Linux

When we are writing a php application and need to generate a Microsoft word document (.doc) dynamically from the php script we can you this very simple to technique for it. We don't have to learn to use any specialized library for this purpose. Only the knowledge of html and php will be enough for this since all the formattings of the generating .doc file will be done by the basic formattings we do on web pages. However this works only in the linux environment.

Lets say you want to generate a file called "report.doc" with some content in it. Open your favourite text editor and enter the following example code in it. The first two lines in the code make the output of this php script to be appear as Microsoft word .doc file to the web browser which you used to view the output of the script. Inside the body section of this file you can write any kind of php statements you want to echo the required output in a specific format. You can even change the font and background colours also just thinking it as going to be appear in the web browser as usual. These texts in your specified colours and fonts will appear in the final .doc file. 

    After writing down the example code in the file, save it to your web servers web folder (www or htdocs in apache server) with a file name say "gernerator.php". Then access that file from your web browser. You will notice that the web browser is prompting to download and save a file call "report.doc". That's the output generated from the "generator.php" file. Save it somewhere in your PC and open from an application which can be used to open .doc files like OpenOffice or LibreOffice. You will notice that the output of the php script has been written into the .doc file.

When you use this method to generate php scripts, keep in mind that all the things related to the content of the .doc file should appear inside a single php file. You cannot use external CSS files together with the php file. All the styles should be embedded inside the same php file. Because of this reason, you cannot add images to the php file for appearing in the final .doc file.  

1:  header("Content-type: application/vnd.ms-word");  
2:  header("Content-Disposition: attachment;Filename=report.doc");  
3:  echo "<html>";  
4:  echo "<meta http-equiv=\"Content-Type\" content=\"text/html; charset=Windows-1252\">";  
5:  echo "<body>";  
6:  //------------------------------------------  
7:  echo "<u><b>Title of the report</b></u>";  
8:  echo "1) Name : Name Of someone";  
9:  echo "2) Age : 23";  
10:  echo "3) Gender : male";  
11:  //------------------------------------------  
12:  echo "</body>";  
13:  echo "</html>";