In this tutorial, let us learn about the Documentation software Doxygen and see how to make use of it to make the job of producing documentation more automated and stress-free!
Let us start by looking at what Doxygen is.
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.
In other words, Doxygen is a software specifically made to fulfill the need for producing and maintaining documentation with as little effort as possible.
That is just the short version of the answer, read my other article 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?
Here is the link again.
Doxygen, What is it? How it works?
In this article, our focus will be on how to get started to actually start using Doxygen.
Step 1: Download and install Doxygen
So head over to the Doxygen official website given in the link below and download the latest release of Doxygen.
You can opt in for notifications regarding updates using the form shown in the screenshot below
If you scroll a bit down, till you see something like this.
Click on the link highlighted in the red box above to get the software.
If nothing happens after you click, then probably your browser is preventing you from downloading the executable. But don’t worry, just right-click the link and click on “save link as” to get the software as shown in the screenshot below. (I am using Chrome).
Your browser might now ask you for confirmation whether you wish to download an executable, say yes as shown in the screenshot below and you should be good to go!
On Google’s Chrome Browser you will see something like this on the bottom right corner. Click on the “down arrow icon” then click “Keep” and Doxygen should start downloading.
Then go through the usual installation steps to finish installing Doxygen on your Windows PC. I recommend keeping the default settings while doing so.
Once that is done you should be able to launch the Doxygen software from the windows start menu. The software should be under the name “Doxywizard” as shown in the screenshot below.
Once you open that app, you must see something like shown in the screenshot below.
If you got till here, congratulations, you have finished the first step of installing Doxygen software on your PC!
Step 2: Learn How to Document the code using Doxygen
Doxygen works by taking the comments which are specifically formatted according to Doxygen’s pre-agreed syntax.
Doxygen calls these special syntaxes as “Tags”. Let us see some of those before we actually get into using them!
Doxygen tags and symbols to use in your comments
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. in C we just need 2 slashes for a comment line) 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.
The entities and tags are implemented in code as shown in the screenshot above.
The Doxygen generated documentation from the code above will look like this
Next, let’s look at the documentation of parameters. Here another special Doxygen syntax is used which is the @ syntax.
Doxygen calls these structural commands. There are several of them and the most useful ones are the following.
| @file | The file name must be present in the file header for inclusion into the documentation generation process |
| @param | Parameter documentation for functions |
| @page | Markdown page name |
| @mainpage | Main markdown page for the project |
| @tableofcontents | Generates “table of contents” for the markdown page |
Let us see how you can use Doxygen entities to document your source code at various levels.
Step 2.1: File headers
File headers contain detailed description about a given file. This must be present at the top of every file which needs documentation. If there is no file header then Doxygen will not produce documentation for that file.
File headers look like this
Just use the Doxygen “structural command” @file followed by the file’s name, to tell Doxygen that you want this file to be included in the documentation generation process. You can also add some description about the file to be shown in the Documentation as shown in the screenshot below.
As you can see, the file name and description are placed on the documentation page generated for this example file main.c
Next lets us have a look at how to properly document functions and their arguments.
Step 2.2: Function Documentation
As we have seen above any function in a file can be documented by simply adding a Doxygen styled comment just above the function.
Next lets see how to describe the arguments and return values. Consider the following 2 functions
The syntax used in the parameter description is the following
@param[in/out] <variable name> <variable description>
Since the variable name radius is obvious to the reader of the code, I did not add the description. Please have a look at my other article “How To Use The Power Of Comments In Your Code The Right Way?” for guidelines on commenting.
The syntax used in the parameter description is the following
@param[in/out] <variable name> <variable description>
The output produced by doxygen using the syntaxes above will look like this
Step 2.3: Global Variables Documentation
We have seen how to document modules(files) and functions inside a given file, next let us see how to use doxygen to document other entities like global variable, constants etc.
As we have already seen in the beginning of step 2, a simple one line Doxygen style comment is enough to document a global variable. But some developers don’t like the idea of adding comments between each and every line of code in the global variable declaration section. To get around that problem Doxygen provides a second way of creating comments as shown in the screenshot below.
If you look at the code, you may have noticed that instead of keeping the comments on top of the entity I have kept it at the right-hand side of the macro definition.
Also instead of “/// “
I have used “///< “
This style can also be used to document more complex entities like structs and constants/macros as shown in the screenshots below.
The documentation produced by Doxygen will look something like this.
On clicking the “More..” in the screenshot above, you can get more documentation on the members of the structure like this
Step 2.4: Doxygen Pages
On Doxygen, we can also produce documentation pages which are not connected to any of our source files. These pages can be used to describe the project or individual modules.
Read the below sections to learn more about how to add pages in doxygen.
Page
These are the normal pages. These will show in the first level of pages on your left-hand side of the tree view. In a later section of this article, I have shown you how to enable “TreeView” which I think is better than the default view for C documentation.
The structural command to use for a Doxygen page is @page as shown in the markdown file below
| 12345 | @page module_name**Author:** Author name**Date:** Date## Module's RoleExplain the module's role in the system in general |
After running it through Doxygen the final output will look like this
Subpage
These pages will not be on the first level, rather it will be placed under another page.
The structural command to use for a Doxygen sub-page is @subpage. This @subpage should be used on the module’s page to which the given page is a sub-page to like this.
| 123456 | @page module_name Module Name@subpage sub_page_name**Author:** Author name**Date:** Date## Module's RoleExplain the module's role in the system in general |
The markdown file for the subpage will look like this
| 12 | @page sub_page_name Sub module Namesome text here explaining the role of the sub module |
As you can see in the above picture, the Doxygen output has added the sub-page “Sub module Name” under the page “Module Name” on the tree-view at the left-hand side and added a link to it on our page.
The sub-page itself is an ordinary page and it looks like as it is shown in the image below.
I generally avoid sections and subsections as it increases the complexity of the documentation process. I like doing them with Markdown formatting options instead (even if that will make it hard to interlink a section with another one). I leave it up to you to decide for yourself if you need them in your particular project or not.
Step 3: Produce Documentation
Step 3.1: Configure Doxygen
There are several settings that can be configured to fine tune the output to just the way we want it to look like.
For example consider the example below on how to create different levels of descriptions by tuning the settings of Doxygen.
Brief vs Detailed Descriptions in Doxygen
By default, the descriptions produced by are not divided into “Brief” and “Detailed”
Consider the code below.
Here the description of the entity 2 function has been expanded to have multiple lines. Now running doxygen with default settings will produce a page like this.
As you can see above, there is no documentation next to entity2 function like entity1 variable has.
By tuning the settings of Doxygen (I have explained exactly how to do this in the following section) you can make Doxygen parser to take the first sentence of the comment to be the brief description and the remaining sentences to be detailed description.
Once you have downloaded and installed Doxygen successfully, you can find an app Doxywizard. This will looks something like the below screenshot
So click on Expert->Project
2 simple tweaks that can be done in this section is shown in the image below (the red rectangles show the changes made).
The option FULL_PATH_NAMES has been unchecked so that the final output doesn’t include the entire path name like “C:/User/user_name/Desktop?project_directory/sub_directory/file_name“. Instead, we can get the output to start from the root directory of the project itself. In the above case, the output HTML will only show “sub_directory/file_name“
All these tweaks and configurations will be stored in a file named Doxyfile on your project folder.
This is just one of many configuration parameters available in Doxygen. To see a more comprehensive example of what more you can configure, I suggest reading the article below where I have explained how exactly to configure the Doxyfile to produce documentation for C programs.
Complete Guide On Using Doxygen To Document C Source Code..!!
I have also included the Doxyfile I have used for that project as a Download with that article so do check that out!
Now that we have covered how to configure Doxygen let us go ahead and see how you can run this program.
Step 3.2: Run Doxygen
You can run doxygen from the Doxywizard as follows
- Select the source code directory in the Doxywizard’s main window
- Go to the run tab
- click “Run doxygen”
- click “Show HTML output”
You can view the generated documentation in your project folder. There you can see that doxygen has generated a folder named “html” inside which lies all your documentation that you needed!
Open the “html” folder and double click on the “index.html” file to see all the documentation that has been generated by Doxygen for you!
I will stop here, hope you found this article useful!
Feel free to share this article with your friends and colleagues!
Here are some other articles that might interest you!
