Doxygen: Generate Documentation from Source Code

Chen Weixiang @ Jun 12, 2016 | TAG: Tools

This article introduces the usage of Doxygen, and generates data structure for Linux kernel project.

What’s Doxygen?

Doxygen is the de facto standard tool for generating documentation from annotated C++ sources, but it also supports other popular programming languages such as C, Objective-C, C#, PHP, Java, Python, IDL (Corba, Microsoft, and UNO/OpenOffice flavors), Fortran, VHDL, Tcl, and to some extent D.

Doxygen can help you in three ways:

  • It can generate an on-line documentation browser (in HTML) and/or an off-line reference manual (in LaTeX) from a set of documented source files. There is also support for generating output in RTF (MS-Word), PostScript, hyperlinked PDF, compressed HTML, and Unix man pages. The documentation is extracted directly from the sources, which makes it much easier to keep the documentation consistent with the source code.

  • You can configure doxygen to extract the code structure from undocumented source files. This is very useful to quickly find your way in large source distributions. Doxygen can also visualize the relations between the various elements by means of include dependency graphs, inheritance diagrams, and collaboration diagrams, which are all generated automatically.

  • You can also use doxygen for creating normal documentation.

Doxygen is developed under Mac OS X and Linux, but is set-up to be highly portable. As a result, it runs on most other Unix flavors as well. Furthermore, executables for Windows are available.

Install Doxygen

Run the following command to install Doxygen:

chenwx@chenwx ~ $ sudo apt install doxygen
[sudo] password for chenwx:
Reading package lists... Done
Building dependency tree       
Reading state information... Done
The following package was automatically installed and is no longer required:
  python3-pycurl
Use 'apt-get autoremove' to remove it.
Suggested packages:
  doxygen-latex doxygen-doc doxygen-gui
The following NEW packages will be installed:
  doxygen
0 upgraded, 1 newly installed, 0 to remove and 4 not upgraded.
Need to get 2479 kB of archives.
After this operation, 10.3 MB of additional disk space will be used.
Get:1 http://mirrors.ustc.edu.cn/linuxmint/ rosa/import doxygen amd64 1.8.7-2~trusty1 [2479 kB]
Fetched 2479 kB in 0s (3262 kB/s)  
Selecting previously unselected package doxygen.
(Reading database ... 465722 files and directories currently installed.)
Preparing to unpack .../doxygen_1.8.7-2~trusty1_amd64.deb ...
Unpacking doxygen (1.8.7-2~trusty1) ...
Processing triggers for man-db (2.6.7.1-1ubuntu1) ...
Setting up doxygen (1.8.7-2~trusty1) ...

chenwx@chenwx ~ $ which doxygen
/usr/bin/doxygen

chenwx@chenwx ~ $ doxygen --version
1.8.7

You can also install doxygen from source code if you like to do so, refer to Doxygen Installation.

Usage of Doxygen

According to Getting started, the following figure shows the relation between the tools and the flow of information between them:

Doxygen_Information_Flow.png

And here is the steps of using Doxygen:

  • Step 0: Check if doxygen supports your programming language
  • Step 1: Creating a configuration file
  • Step 2: Running doxygen
  • Step 3: Documenting the sources

Extract Data Structure for Linux Kernel

Create Configuration File

chenwx@chenwx ~ $ mkdir -p linux_doxygen/config
chenwx@chenwx ~ $ cd linux_doxygen/config

chenwx@chenwx ~/linux_doxygen/config $ doxygen -s -g linux-kernel-config

Configuration file `linux-kernel-config' created.

Now edit the configuration file and enter

  doxygen linux-kernel-config

to generate the documentation for your project

chenwx@chenwx ~/linux_doxygen/config $ cp linux-kernel-config linux-kernel-config.original
chenwx@chenwx ~/linux_doxygen/config $ ll
-rw-rw-r-- 1 chenwx chenwx 11K Jun 12 07:28 linux-kernel-config
-rw-rw-r-- 1 chenwx chenwx 11K Jun 12 07:30 linux-kernel-config.original

chenwx@chenwx ~/linux_doxygen/config $ gedit linux-kernel-config &

Edit the configuration file linux-kernel-config and change the values of the following TAGs. Refer to Doxygen Configuration for more explanation of each TAG.

chenwx@chenwx ~/linux_doxygen/config $ diff linux-kernel-config*                   
11c11
< OUTPUT_DIRECTORY       = /home/chenwx/linux_doxygen/output/
---
> OUTPUT_DIRECTORY       =
32c32
< OPTIMIZE_OUTPUT_FOR_C  = YES
---
> OPTIMIZE_OUTPUT_FOR_C  = NO
101c101
< INPUT                  = /home/chenwx/linux/kernel/
---
> INPUT                  =
103,104c103,104
< FILE_PATTERNS          = *.c *.h
< RECURSIVE              = YES
---
> FILE_PATTERNS          =
> RECURSIVE              = NO
107c107
< EXCLUDE_PATTERNS       = */Documentation/* */firmware/* */samples/* */scripts/* */tools/* */usr/* */virt/*
---
> EXCLUDE_PATTERNS       =
197c197
< GENERATE_LATEX         = NO
---
> GENERATE_LATEX         = YES
281c281
< DOT_NUM_THREADS        = 2
---
> DOT_NUM_THREADS        = 0

Run Doxygen in Linux Kernel

Create output directory by command:

chenwx@chenwx ~/linux_doxygen $ mkdir output

Then, run Doxygen in directory ~/linux/kernel/ to check the data structure in Linux kernel:

chenwx@chenwx ~/linux $ doxygen ../linux_doxygen/config/linux-kernel-config
...
Generating graphical class hierarchy...
Generating member index...
Generating file index...
Generating file member index...
Generating example index...
finalizing index lists...
Running dot...
lookup cache used 3308/65536 hits=14847 misses=4115
finished...

Open Output in Browser

The output is generated in output directory ~/linux_doxygen/output. Check the output by Firefox:

chenwx@chenwx ~/linux $ cd ../linux_doxygen/output/
chenwx@chenwx ~/linux_doxygen/output $ firefox html/index.html &

For instance, here is the data structure of struct worker:

Doxygen_Output_Example

References