If you are a beginner to the programming world and you have just heard about the software named Doxygen and was wondering what it is, then this article is for you!
In this article let us learn about the Documentation Software Doxygen and learn how it works.
For those of you in a hurry, here is the short version of the answer.
Short Version of the Answer
What is Doxygen? Doxygen is a software used to produce documentation of source code written in C, C++, Python, Java, etc. and delivers in various formats like HTML, PDF, etc.
How Doxygen works? Doxygen works by taking the comments which are specifically formatted according to Doxygen’s syntax, when you run this tool, it will parse out the documentation details from comments which follow the special Doxygen syntax. so that they can be displayed in formats like HTML, Hyperlinked PDF, etc.
That is just the short version of the answer, read on for a longer and more informative answer where I try to answer the following questions
- Why you might need to use Doxygen?
- Is Doxygen the right choice for you?
- If no, then what are the alternatives available?
- If yes, then how to get started using Doxygen?
If you are interested in a particular topic, you can skip to that using the table of contents below, but I recommend reading the entire article, as the 5 to 10mins you spend reading this article will give you a good understanding of the software, so that you will feel right at home when you start using it.
So, let’s begin!
Need for Doxygen
Before there was Doxygen, there was chaos when it comes to maintaining documentation. For professional software developers, the time to document their source codes used to be their least favorite time of the project!
This is due to the following 3 reasons
- Software developers like us hate doing tedious tasks like writing documentation
- It is very difficult for us to go back and try to make documentation of something they did a few months ago.
- When we make any changes to the source code, nobody has enough patience to go over to the documentation and update them, hence we go into the procrastinate/forget about that mindset!
Hence to avoid this task, we tend to tell ourselves that we don’t really need documentation, as we will remember everything.
This sort of thinking has the following 2 issues.
- We will never remember what we wrote a couple of years ago
- Even if we did, if we leave the project and someone else has to take over our job, then they will have a very hard time with our code without any documentation!
Software has a life time of years, sometimes decades. Hence us developers came to the understanding that
Documentation is unavoidable!
So now that we have established 2 things
- Documentation is something unavoidable
- Documentation is a tedious process
Hence the only way out for us is to automate this process somehow so that we spend less time doing this tedious task at the same time we get the results that we need!
Doxygen is a software specifically made to fulfill the need for producing and maintaining documentation with as little effort as possible.
The next logical question that comes into mind is how can we use Doxygen to make our jobs of producing documentation easier?
How to use Doxygen?
As we saw in the short version of the answer, Doxygen works by taking the comments which are specifically formatted according to Doxygen’s syntax.
Doxygen calls these special syntaxes as “Tags”. Let us see some of those.
Doxygen supports several methods for incorporating documentation inside the comments. The 2 simplest methods to include in C source code are
/**
… comments…
*/
And
/// Comments.
Note the extra asterisk (*) in line 1 of the first option and extra slash symbol(/), i.e. 3 instead of 2 slashes. These syntaxes are used to tell the Doxygen parser that it is documentation and it needs to be extracted.
The above 2 syntaxes must be placed just above an entity so that the Doxygen parser can associate the comments to that particular entity.
What is an entity in Doxygen? An entity can be a global variable, a structure declaration, enum declaration or a function.
Consider the code snippet below written in C programming Language.
#include <stdio.h>
/// This is a test string
char * hello = "Hello Embedded Inventors!";
/**
* This is the main function
*
*/
int main()
{
printf("%s \n", hello);
return 0;
}
Here I have used the 3 slashes syntax to document the global variable and the “/**….*/“ syntax to document the function.
When you run Doxygen, this tool will parse out the documentation details from comments which follow the special Doxygen syntax. so that they can be displayed in formats like HTML, Hyperlinked PDF, etc.
Putting this code through Doxygen and choosing HTML as output gives me documentation that looks like this!
Is Doxygen the right choice for you?
The answer to this question of whether you should use Doxygen or not depends upon the language you are writing your code in.
Languages Supported by Doxygen
Doxygen is the de facto standard tool for generating documentation from annotated C++ sources, but it also supports other popular programming languages such as C, Objective-C, C#, PHP, Java, Python, IDL (Corba, Microsoft, and UNO/OpenOffice flavors), Fortran, VHDL and to some extent D.
https://www.doxygen.nl/index.html
The above snippet is taken from the Doxygen website, as Doxygen supports the following popular programming languages
- C
- C++
- Objective C
- C#
- Java
- Python
- PHP
Doxygen also supports some other not so popular programming languages like
- IDL
- Fortran
- VHDL and
- ID (partial support)
So as long as you are writing your code on any of the above languages, Doxygen should be able to cover your needs. But what if you are writing your code in some other language?
The above screenshot is taken from Doxygen’s official website. As you can see, you can use an input filter to make Doxygen understand your code better. Diving into each and every programming language is beyond the scope of this article, I recommend you to go to this link for more information. Or you can research on google by typing “Doxygen <your programming language name>”
Doxygen and C
Doxygen is a very powerful tool to do documentation, but it’s more geared toward object-oriented languages like C++ and Java.
The Doxy wizard, a.k.a. the GUI frontend of Doxygen, has so many options to play with and in this article, I have shown you how to optimize the settings to wield the full power of Doxygen to document source code written in C.
Checkout my other article, if like, me you write code primarily in C!
Complete Guide On Using Doxygen To Document C Source Code..!!
Alternatives to Doxygen
Doxygen is the best option for some languages like C, C++ etc,
If you are using python I recommend going for Sphinx or pdoc (reference)
If you are using Java, Javadocs and Doxygen are both good options (reference)
If you are using some other programming language I recommend googling “Best documentation tool for <programming language name>”
And with that, I will conclude this article!
I hope you guys enjoyed this article and learned something useful.
If you liked the post, feel free to share this post with your friends and colleagues!
Comments are closed.