Doxygen and your project

28 Dec

Doxygen and your project

This blog will give you practical knowledge of why and how you can use Doxygen . You have heard this word Doxygen many times but don't know what exactly it is ? Or may be majority didn't hear about this technology. So it’s time to do friendship with Doxygen and make your life easier. So let's start.

What Doxygen actually is ?

Doxygen is a new and emerging technology. It's a system which allows you to make documentation of your different projects running on C , C++ , Java , Python , PHP , Objective-C , IDL (Corba and Microsoft flavors) , Fortran, VHDL , C#, D.
Doxygen is open source technology which runs on almost all Unix flavors. Executables for Windows are also available.
Why should I use Doxygen in my project ?
Doxygen has many advantages. Some noted below.

    It can generate on-line documentation browser in HTML or an off-line reference manual in LATEX from documented source files.
    It also generate your documentation in RTF (MS-Word) , Postscript, hyperlinked PDF ,compressed HTML , and Unix man pages.
    You can make documentation of any code structure (including framework , CMS , complex projects ) from its undocumented source files. So instead of googling every time you can directly dive into code structure documentation and understand relationships between classes , methods etc.
    You can also visualize relationship between your code elements including dependency graphs, inheritance diagrams , collaboration diagrams . And hey good news is all these things get generated automatically with no pain.
    It actually speeds up the development process of your project when you are working on big code architecture like Drupal or Django etc.
    Doxygen add plus point in your project when you delivering project to your client by providing technical documentation with project.
    I believe Doxygen not only help to clients but in many software development processes (Development, Testing , Maintenance , Implementation , Deployment )

How can i install Doxygen in my linux machine ?

Step 1: Download Doxygen source from here doxygen or you can just write this command in your terminal .
sudo apt-get install doxygen
Note:- Makes sure apt-get is only for Ubuntu and Debian please use as per your Linux distribution.(fedora- yum , opensuse – zipper )

Step 2:After downloading source tar package of Doxygen . Extract it by terminal
tar xf doxygen-$VERSION.src.tar.gz
If you have installed it by “apt-get” then skip this step and directly switch to running and configuring Doxygen with your project.

Step 3: Run the configure script :
cd doxygen-$VERSION
sh ./configure
Step 4:Compile the program by running make:
Step 5:Optional : Generate the user manual
make docs
Step 6: After the compilation of the source code do following to install Doxygen
make install

Note:- Make sure you are in root or maybe it will give you error in making directory or executable in /usr/bin , /usr/bin/x11/

Well done you have installed Doxygen!
Note:- For more advance installation instruction you can check out here : Advance installation
How i can give some oxygen to my project ? :- Configuration
Step 1: Go into your project directory and run this command
doxygen -g [configfile name]
Note: If you do not give any file name then Doxygen will generate “Doxyfile” by default.
Step 2: Now just open your configuration file and edit as per your project andprogramming language you are using .
Step 3: Tell doxygen about your project configuration
doxygen [configuration file name]
Step 4: check your documentation in /html or /man depends what type of documentationyou are generating .

Here you can download Doxygen config file for PHP project from my Github repository : config file
How can i use Doxygen in understanding Drupal CMS(PHP based) ?
Scenario 1:
I was working on Drupal project and i wanted to know all functions, classes , hooks etc used in Drupal and how exactly i can modify them as per my project requirement. I came to know about API module in Drupal and it's good but i was not satisfied because of three things :

    It was slow . I have to again and again do lots of clicks.
    I have to check security updates as it was released again and again .
    I didn't have choices of generating my documentation in different formats whichshould be understandable by my user.

I need some system which actually generate documentation of Drupal source code and able to explain me all relationship between classes etc.So API module and Doxygen both have their own objective and viewpoints. API module let you know what all methods , hooks you can use in Drupal .But Doxygen generated documentation of your undocumented source code of Drupal off-line and give you user friendly docs of source code with various relationship diagrams. This is basically one feature of Doxygen but if you are working on large CMS or frameworks it will make your life easier. you can modify comments as you want and document them.
So some things i like to include here about what i observed after creating my documentation of drupal source code .

1. My documentation was fancy , structured and understandable .
2. Documentation have Indexes and it was browsable.3. Doxygen documented all files, namespaces, packages, classes, structs, unions, templates, variables, functions, typedefs, enums and defines.4. It generated all my class and collaboration diagram in HTML and LATEX.5.It grouped all my entities in modules and created hierarchy of modules.6.Generated all list of members of a class along with their protection level.
7.Automatically generated references to documented classes , files , members and namespaces , global variables , functions typedefs , defines and enumerations .
8. References to my base/super classes and inherited/overridden members are generated automatically.
After getting all this information my development process became easy.This is howDoxygen gave me oxygen in this scenario and it was really cool.
You can check out my documentation of source code of Drupal 7 created using Doxygen Drupal documentation
Scenario 2:
How i used Doxygen after documenting my project?

    I have used dot tool of the Graphviz tool kit to generate include dependency graphs, collaboration diagrams, call graphs, directory structure graphs, and graphical class hierarchy graphs and it was beautiful .
    I configured references to documentation generated for other projects in a location independent way. So let say if i'm working on big and complex project and i created many documents for different components of project. At last i need to merge those documents in one documentation. Here Doxygen gave me flexibility by allowing integration of all documents together .
    I wanted to transfered my documentation from my office laptop to my personal laptop. In this thing Doxygen allow me to transfer all my documentation and search engine to my personal laptop without regenerating the documentation.

I hope this blog will help to folks who want some information for start using Doxygen .
I hope it will also help to project managers in making decision to use Doxygen in their projects .

Note: I will add Doxygen configuration files of different projects running on different programming languages in my github repository as i will do some more R&D on Doxygen working with other technologies.

References :-

copyright 2012 10jumps Llc.

copyright 2012 10jumps LLC.