Summary: SoftaCheck, a code review web app, has integrated the effortless code documentation tool Doxygen to achieve a better software lifecycle. 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 SoftaCheck, a developer can gain more insight into their code. By using Doxygen, SoftaCheck 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 use Doxygen because your code documentation will be automatically generated, saving you a lot of time and headache. 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, SoftaCheck sets everything up for you, letting you focus on the final outcome – the documentation. 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, there are many other formatting options to explore. 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. With SoftaCheck, the configuration file is already optimized to generate the ideal documentation format for C/C++ code. Suppose you would prefer to use your own configuration file with SoftaCheck. In that case, you need to put the configuration file (named “doxyfile” – without any file extension) in your repository main folder.
Generate Flow Charts 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 goes 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:
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 maintaining 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 make you write better code?
Having a flowchart or a state machine graph allows you to visualize your code implementation. Like with class hierarchy graphs, you can easily detect deficiencies in your code and improve them. 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.
On a Concluding Note
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. Try using the SoftaCheck web app for free now, and experience the seamless code reviewing functionality.
