Doxygen – What is Code Documentation and How to Generate it?
Code Documentation using Doxygen
“Comments often are used as a deodorant.”
— Martin Fowler and Kent Beck, Refactoring, page 87
Forward
The agile software manifesto states:
Individuals and interactions over processes and tools
Working software over comprehensive documentation
Customer collaboration over contract negotiation
Responding to change over following a plan
That it values items to the left more (emphasis mine) than items to the right. Of the four universal statements, I believe the second one is the most misunderstood. Without working software, comprehensive documentation is null and void. The operative word here is comprehensive. It takes time and effort to create comprehensive documentation. But it should never be an excuse to not create code documentation.
What use is code documentation?
I believe documenting the code is different from just commenting on it. If you are trying to reduce the “odour” of code by commenting on it you better refactor the code to make it more understandable. I believe code documentation should:
Provide information that cannot be expressed by the code
So, what kind of information does code documentation provide that cannot be expressed by code?
- Requirement traceability: A unit of code – be it a function, class, module, or component – should be traceable to one or more requirements. Requirement traceability is required to answer two fundamental questions: are we building the right product? Are we building the product right? Code documentation can embed requirement identifies that enable forward and backward tracing to code.
- Design by contract: This method of software development has its roots in the formal verification of software. A contract is a unit of code. We have the following three questions that need to be answered by this contract:
- What does the contract expect?
- What does the contract guarantee?
- What does the contract maintain?
Such strict rules ensure software correctness and can be written by code comments – especially in languages that have no native support for contracts.
- 4+1 architectural view model: In the 4+1 architectural view model, the development view is concerned with code. This is the implementation view. There is no reason why code documentation cannot allude to other views – especially the dynamic view and the deployment view.
- As a heads-up to the maintainers: I cannot describe it any better than the image I found on the internet:
- Regulatory requirement: In some domains like medical image processing, code documentation is mandatory as it is a requirement to pass Food and Drugs Authority (FDA) regulations. In such situations, the metric of code to comment ratio will be enforced.
- API documentation: Systems which expose services through APIs (REST-based) need to provide API documentation. This documentation is exposed to the clients as API documentation. It helps clients to understand the functionality of exposed APIs and consume them as per specification. Also, as APIs change over time (with new functionalities getting added, older ones getting depreciated) API documentation should state the versioning information.
Doxygen
In the previous section, I believe I have driven home the point that code documentation is important. Although code and code documentation both goes into the source code file, it would be unwise to read the file for documentation. Separation of concerns is what we need:
Doxygen is a well-known tool to generate documentation from annotated sources for different programming languages like:
- C and C++
- Objective C
- C#
- PHP
- Java
- Python
- Fortran
- ..etc
Doxygen can generate both Online (HTML hosted on a server viewable through a browser, e.g. D-Bus documentation https://dbus.freedesktop.org/doc/api/html/index.html) and offline documentation (in RTF, PDF, PostScript, or LaTeX formats).
Doxygen is a mature open-source project and has been around for more than 20 years. It is well maintained because it solves a vital problem of generating code documentation from annotated files thereby delivering value.
Doxygen Example
For this demonstration, I am creating a blogging system in C++ to show off some code. Here is one header:
BlogEntry.h:
BlogEntry.cpp:
As you can see, I have documented my code using Doxygen markups. To create an html documentation that I can host online two paths could be taken.
- Path 1: Download and Install doxygen myself, configure it myself, run it myself and upload the documentation to the cloud to a hosting service myself.
- Path 2: Use SoftaCheck that takes care of all of that and does it automatically in the cloud with a selected GitHub repository and stores the documentation in the cloud with a password-protected link.
Here is the experience with Path 1:
- Download and install Doxygen. Once installation is done, you should be able to print the version of Doxygen from the command line using doxygen -v
- Create a configuration file in the same directory of your sources by the command doxygen -g <configfilename>
- The created democonfig file needs some edits. Here is what you need to do:
- Now run the command: doxygen democonfig
You will see Doxygen preprocessing and parsing the headers and sources of your project. Once done, you can check the generated documentation using a web browser navigating to .\html\index.html page.
Let us give a project number and see what changes.
PROJECT_NUMBER = 3.14
And regenerate the documentation.
- Here is how the documentation for the class would look like:
Here is how the documentation for the header would look like:
Adding versioning to the documentation is very important – as important as versioning the source code itself. Keeping documentation and code versions in sync manually is a pain. To alleviate the pain, we in Softacheck have an excellent solution.
Softacheck solution for code documentation
Softacheck is a GitHub app available through the GitHub marketplace which allows you to automate your static code analysis and code documentation process within GitHub workflow. There is no local installation required on developer machines. This ensures there are no circumvention possibilities on Softacheck as it is run on every commit. 😊
Once you configure Softacheck to run on your repositories, the Doxygen code documentation will be generated and stored in servers managed by Softacheck. We ensure that only members of the repository shall have access to the documentation. GitHub credentials have to be supplied for a successful login. Since code documentation generation does not involve any manual steps, up-to-date documentation is always ensured. Also, on the pull request page, a link to the documentation page will be available. Most importantly, all past revisions of the documentation are maintained so that you can always view your earlier code versions with synced documentation. Isn’t that a great USP?
Also, if you do want to use your own doxygen configuration file to have more control over your doxygen output you can simply include the configuration file in the repository and SoftaCheck will use it as the default configuration file for your doxygen settings.
And yes, for a limited time, we are giving our excellent app for you to try – for free! 😊
Afterword
Comments definitely should not be used as deodorants. Code should never smell. If there are design or code smells in the project, use that as a guiding principle to refactor your code. Maintain code documentation. It has a direct impact on the internal quality of your system. You must maintain your code as well as your documentation making sure that they are in sync. I will be pleased if you try out Softacheck for this purpose!