If you are an open-source developer and want to release your project to the public, you may consider publishing source-code documentation for the project. In cases where you are trying to read source code written by others, it will also be helpful if you can get a "bird-eye" view of the otherwise cryptic source code.
In Linux, doxygen is the de facto standard tool for automatically generating cross-reference documentation from annotated source code. It supports major programming languages including C/C++, Objective-C, C#, PHP, Java and Python.
Using doxygen, you can auto-generate API reference documentation of source code, in HTML or Latex format. You can also visualize class dependency and the relationship between different source files.
In this tutorial, I will explain how to automatically generate documentation from source code in Linux by using doxygen.
To install doxygen on Ubuntu, Mint or Debian:
$ sudo apt-get install graphviz
To install doxygen on CentOS, Fedora or RHEL:
$ sudo yum install graphviz
To generate documentation of source code, proceed as follows.
First, generate a project-specific doxygen configuration file:
The above command will generate a template configuration file for a particular project.
Among others, you can edit the following options in the configuration file.
# document all entities in the project. EXTRACT_ALL = YES # document all static members of a file. EXTRACT_STATIC = YES # specify the root directory that contains the project's source files. INPUT = /home/xmodulo/source # search sub-directories for all source files. RECURSIVE = YES # include the body of functions and classes in the documentation. INLINE_SOURCES = YES # generate visualization graph by using dot program (part of graphviz package). HAVE_DOT = YES
Now go ahead and run doxygen with the configuration file.
Documentations are generated in both HTML and Latex formats, and stored in ./html and ./latex directories respectively.
To browse the HTML-formatted documentation, run the following.
$ firefox index.html
Doxygen Documentation Screenshots
Here are several screenshots for doxygen outputs.
This shows a list of header files that are automatically categorized by topics.
This shows a list of classes, structs, unions and interfaces with descriptions.
This shows a source code browser listing all source files recursively in sub-directories.
If you click on a particular source file, you will see a page which shows dependency graph for the file, as well as documentation for all defined functions.
This shows a detailed view of function/macro definitions. Below the figure is shown the actual source code snippet that corresponds to this documented portion.
Subscribe to Xmodulo
Do you want to receive Linux FAQs, detailed tutorials and tips published at Xmodulo? Enter your email address below, and we will deliver our Linux posts straight to your email box, for free. Delivery powered by Google Feedburner.