TrafficControl: Doxygen

In order to get a better understanding of the code structure of my project TrafficControl, I need to use Doxygen.

Doxygen is one of the most popular tools for documenting source code. The developer adds Doxygen-style comments to the source. When Doxygen analyses the code, it uses the structure along with the comments to generate a set of files with an overview of the program, and the relations.

Step 1 - Select how to use Doxygen

At first, I wanted to integrate Doxygen into Qt Creator. After digging into how to do it, it seemed to be quite difficult. I would either need to find pre-compiled binaries that matches my system and my Qt installation, or recompile Qt Creator. I tried to follow the video below, but the URL they used was broken.

I'm not the only one to pay too little attention to my pet projects.

Instead, I installed the program on my computer from the Doxygen web site. I also installed GraphViz for creating graphs - that will be useful for getting an overview of my code.

Step 2 - Configuring Doxygen

The next step was to use an appropriate set of parameters for my project. The most important ones are listed below:

• QT_AUTOBRIEF           = YES - Assume that the first line of the class descriptor to be the brief description.
• EXTRACT_ALL            = YES - Assume all entities to be documented. Maybe not needed?
• EXTRACT_PRIVATE    = YES
• EXTRACT_PRIV_VIRTUAL = YES
• EXTRACT_STATIC      = YES
• EXTRACT_LOCAL_METHODS = YES 
• INPUT          = C:/Users/gusta/GIT/trafficControl-dev/src \ - All folders to be documented. IMPORTANT!
•                          C:/Users/gusta/GIT/trafficControl-dev/inc \
•                          C:/Users/gusta/GIT/trafficControl-dev/test
• RECURSIVE                  = YES - Include sub directories
• HAVE_DOT                    = YES - Use Dot tool from GraphVix to generate graphs - IMPORTANT!
• UML_LOOK                   = YES - Make graphs look more like UML
• DOT_UML_DETAILS    = YES - Add bytes and info to UML graphs
• CALL_GRAPH               = YES
• CALLER_GRAPH          = YES
• DOT_PATH                     = C:/Program Files/Graphviz/bin

Step 3 - Insights from Doxygen

My first insight is that there is lot's of more to learn about Doxygen, and that it will be useful to check the relations between different parts of my program. Listing everything will be too exhaustive for a blog post, and I don't know yet know how to publish Doxygen output in a reasonable way. 

I'll show some examples of the graphs below:

Train::move() will call different functions depending on the current state.

A lot of functions are calling NetworkControl::parseCmd()

A lot of functions are calling parseCmd. This means that bugs that are introduced hwere will have a huge impact - extensive testing will be needed.