Summary: In this post, you will get an insight into how Doxygen helps create exceptional documentation and how it enables you to write C/C++ code more professionally.
Doxygen is an open-source tool used to generate documentation for a software codebase. Doxygen supports various languages, including C and C++. It generates the software documentation in HTML, pdf, or Latex from the code and the comments formatted with Doxygen markup syntax.
Using Doxygen, a developer can gain more insight into their code. Doxygen enables you to navigate easily throughout the code by using auto-generated cross-referenced links. In addition, functions, namespaces, structures, enumerations, and code examples are laid out in an organized manner in the documentation.
Why Should You Use Doxygen for C++ Code?
It would help if you used Doxygen because your code documentation will be automatically generated, saving you a lot of time and headaches. In addition, in the case of C++ code, class hierarchy diagrams are automatically created, allowing you to visualize your code professionally. For example, here is a snapshot of a few class hierarchy diagrams generated by Doxygen from the qbittorrent open-source project written in C++:
Such class hierarchy diagrams allow you to see deficiencies in your code and avoid “spaghetti” code.
Formatting Your Doxygen Documentation
Doxygen does seem a bit complicated at first, especially if you try and use it and set it up on your own. However, if you don’t want to do any heavy lifting you can just use a free online tool called CodeDocs which sets everything up for you, letting you focus on the final outcome – the documentation (warning: the Doxygen configuration setup by CodeDocs is not ideal in my opinion for C/C++ language, and you won’t get any graph images. For that, you would need to set up another tool to work with Doxygen called Dot, but that is not part of the scope of this post). By reviewing the documentation, developers can improve their code by examining the class hierarchy diagrams. You don’t need to do anything special in your code to create your first documentation. That being said, if you would like to format the generated documentation, you need to learn a few specific comment styles.
Once you get familiar with Doxygen, many other formatting options exist. For example, you can add diagrams in the document or link in the blocks of source code & take advantage of specific formatting capabilities.
For controlling Doxygen behavior, the code generator uses a text-based configuration file. Doxygen has a GUI-based tool called Doxywizard to modify its configuration file if you dislike editing text files by hand.
Generate Flow Charts and State Machines with Doxygen
Another fantastic feature that Doxygen has is generating flow charts to depict how your code works. Unfortunately, this is not automatic and requires you to do an extra step of manual maintenance. However, trust me, it is worth the effort since this habit will force you to write your code in an organized manner. Here is an example flowchart I generated using Doxygen:
So the way that flow charts are generated from your code is by adding a block comment containing a DOT script. DOT is a third-party tool that Doxygen uses to create graphs in the documentation. Don’t worry; I will not bore you with explanations on how to write DOT scripts. Luckily, the script language is relatively intuitive for creating flowcharts, as I showed above. And you can easily play around with the script and see the graph change in this excellent link: https://edotor.net/
And if you still want to dig into all the nuances of DOT, you can go to their documentation here: https://graphviz.org/documentation/
You might be wondering how does this go hand-in-hand with Doxygen? Let’s say you have a function StateMachine(), that manages a state machine in your code. You can add a block comment above the function depicting this state machine in DOT language. And if you want Doxygen to “detect” your DOT script, you need to put it between \dot and \enddot. Here is an example of the script that generated the above state machine:
/*!
State Machine dot graph:
\dot
digraph finite_state_machine {
rankdir=LR;
size="8,5"
node [shape = doublecircle]; LR_0 LR_3 LR_4 LR_8;
node [shape = circle];
LR_0 -> LR_2 [ label = "SS(B)" ];
LR_0 -> LR_1 [ label = "SS(S)" ];
LR_1 -> LR_3 [ label = "S($end)" ];
LR_2 -> LR_6 [ label = "SS(b)" ];
LR_2 -> LR_5 [ label = "SS(a)" ];
LR_2 -> LR_4 [ label = "S(A)" ];
LR_5 -> LR_7 [ label = "S(b)" ];
LR_5 -> LR_5 [ label = "S(a)" ];
LR_6 -> LR_6 [ label = "S(b)" ];
LR_6 -> LR_5 [ label = "S(a)" ];
LR_7 -> LR_8 [ label = "S(b)" ];
LR_7 -> LR_5 [ label = "S(a)" ];
LR_8 -> LR_6 [ label = "S(b)" ];
LR_8 -> LR_5 [ label = "S(a)" ];
}
\enddot
*/
void StateMachine()
{
//Write some code here…
}The graph will appear in the documentation output generated by Doxygen within the description of the function StateMachine().
Indeed, the disadvantage of this feature is that it requires investing time to design the flow chart and then maintain it. Also, you run the risk of not accurately depicting the actual code. So it would be best if you were careful. Nonetheless, the advantage of having fantastic flowcharts and state machines in your documentation that boost readability and overall code understanding outweigh the risks.
How Does This Improve Your Code Quality?
Having a flowchart or a state machine graph allows you to visualize your code implementation. Like with class hierarchy graphs, you can easily detect and improve deficiencies in your code. Also, especially in the case of writing new code (and not just adding documentation to legacy code), if you write the DOT script first to try and visualize your planned implementation, then you will be able to design your code architecture in a more optimal way which would lead to a cleaner and more organized code.
Final Summary
This article explains how Doxygen can extract a great deal of valuable data from C/C++ code and organize it in a user-friendly manner. When used correctly, Doxygen is an excellent tool for maintaining and managing your code documentation.
