Charting and graphing with Doxygen

This article is included in the resulting series of articles on the Doxygen documentation system:

1. Documenting code efficiently with Doxygen
2. Documentation in Doxygen
3. Charting and graphing with Doxygen

She completes a series of articles on the Doxygen documentation system. This time the article is devoted to the construction of various charts and graphs in Doxygen. In it we will look at their main types, various ways to customize and design them, and also give a number of examples and tips for their use.

Introduction

Doxygen allows you to automatically build on the basis of the source code a sufficiently large number of various diagrams and graphs designed to illustrate certain elements of the source code, while any graph can also serve as a way to navigate through the code and documentation, since Doxygen automatically puts links to the corresponding graphs on top of the graph itself. sections of documentation. You can see the live results of his work, for example, here and here (in the last example, they are collapsed for compactness).
')
The main types of diagrams and graphs that can be constructed with its help are:

• Class inheritance diagram
• Class Collaboration Chart
• Class hierarchy diagram
• Call graph
• Calling function graph
• Dependency graph (direct and inverse)

Next, we will look at each of these types in detail, but first we will make a number of general comments and talk about the basic settings that will be useful to us in their construction. In general, much of what will be described can be found in the corresponding section of the documentation .

Basics of building charts and graphs

By default, the possibilities of Doxygen for constructing various kinds of diagrams and graphs are very limited (only the class inheritance diagram is available), an example of such a diagram is shown below:



In order to build more advanced charts and graphs, Graphviz will be required, special open source software designed to build various kinds of graphs. Download it here .

After installing it, you need to make some changes in the Doxygen settings file. To do this, use the following commands:

Team	Purpose
HAVE_DOT	Indicates that Graphviz must be used to generate charts and graphs (disabled by default)
DOT_PATH	Specifies the path to the dot.exe executable file (by default, it is assumed that the path to it is in the path variable; as a rule, it is).

Among the additional settings that may be useful in the future, you can note the following:

Team	Purpose
DOT_GRAPH_MAX_NODES	Sets the maximum number of nodes that will be displayed in the graph. If the number of nodes becomes more than the specified value, the graph will be cut, resulting in the parent node, whose child nodes were hidden, will be highlighted in red (if the number of nodes was set less than the number of children of the root node, it will not be shown at all)
MAX_DOT_GRAPH_DEPTH	Sets the maximum depth of the graph (the depth is equal to the number of faces from the most distant node of the graph to the root node). Again, if the depth of the graph exceeds this value, it will be cut off, as a result of which the parent node, whose child nodes were hidden, will be highlighted in red
DOT_IMAGE_FORMAT	Specifies the format in which charts and graphs will be created (“png”, “jpg”, “svg”, “gif” are supported)
DOT_FONTNAME	Sets the headset used to display text on graphs and charts.
DOT_FONTSIZE	Specifies the size (height of letters, measured in points) for text on graphs and charts
DOT_FONTPATH	Specifies the path to the folder with the font files.
HTML_DYNAMIC_SECTIONS	If this option is set, Doxygen will minimize certain elements of the HTML documentation (for example, columns) that the user can optionally later reveal.

So, now that we have dealt with the basic settings, we are ready to proceed directly to the main types of diagrams and graphs.

Class inheritance diagram

The class inheritance diagram (class graph) is intended for graphical display of the inheritance relations between classes (both “up” and “down”).

In order to generate such a diagram for all documented classes (if the EXTRACT_ALL option is set in the settings file, for example, all classes belong to the documented classes) you need to set the following option in the settings file:

CLASS_GRAPH = YES 

Below is an example of constructing such a diagram for a test example (it is taken from the legend created by Doxygen), illustrating various types of relations between classes:



Now we will consider what these symbols mean.

	Root node
	Normal node, corresponding to the documented class
	Node corresponding to undocumented class
	Parent node whose child nodes were hidden (for example, due to restrictions on the number of nodes in the graph or its depth)

	Indicates open inheritance
	Indicates Secure Inheritance
	Indicates closed inheritance
	Indicates that the class is a specialization of a certain template class, while the label next to the arrow indicates which template parameter was specified during the specialization

Please note the following options:

Option	Value	Default
HIDE_UNDOC_RELATIONS	Indicates whether it is necessary to hide a link with a certain class, if it is undocumented or is not a class.	YES
TEMPLATE_RELATIONS	Sets whether to display a link indicating that one class is a specialization of another.	NO

Class Collaboration Chart

Collaboration diagram of classes (collaboration graph) is intended for graphical display of inheritance relations between classes (only “upwards”, that is, only parent classes will be shown), as well as interaction between them, which in this case means that one class contains among attributes object of another class.

To enable the class inheritance diagram, you need to set the COLLABORATION_GRAPH command:

 COLLABORATION_GRAPH = YES 

Below is a diagram of class cooperation for the same example that was considered earlier:


It should be noted that in this case, the difference from the class inheritance diagram is only that the connection between the Inherited and Used classes is displayed, which is expressed in the fact that the first class has an attribute that is an instance of the second class. The designation for such a link is as follows:

Indicates that one class contains an attribute that is an instance of another class, and the label next to the arrow points to the name of the corresponding attribute.

All the rest, said earlier about setting the class inheritance diagram, remains fair here.

Class hierarchy diagram

The class hierarchy diagram (graphical hierarchy) is intended only to display the inheritance relations between many different classes. In fact, it is a graphical representation of the textual description of the class hierarchy, which is generated by default:

Call graph

Before proceeding to the description of this type of graph, we agree that everything said below is true for functions and for methods of classes, but for brevity we will use the word "functions". So, the call graph illustrates what functions are called inside the body of the documented function, as well as in all nested functions (the depth can be adjusted by setting the maximum depth of the graph in the settings file).

In order to build a function call graph, two approaches can be used: setting an option that will cause the construction of call graphs for all functions, and using a special command that is added in the function description (the latter may be preferable if you need to illustrate a specific function or your project is very big).

For the first approach, you need to set the following option:

 CALL_GRAPH = YES 

For the second approach, use the following command:

 \callgraph 

An example of the call graph is shown below. The formulas in the image below are given for example (the combination function calculates the number of combinations, and uses the Stirling formula to calculate factorial):

Calling function graph

The graph of calling functions (caller graph), illustrates the chain of calls to various functions as a result of which the documented function is called (the depth of such a chain can be adjusted by setting the maximum graph depth in the settings file).

Again, there are two ways to construct such graphs. The first way is to set the corresponding option in the settings file:

 CALLER_GRAPH = YES 

The second way is to use a special command:

 \callergraph 

A simple example of a calling function graph is shown below:


Let us briefly explain it: the function of raising to a power ( pow ) is used to calculate factorial using the Stirling formula, this function is also used to calculate the exponent, and the calculation of the exponent can be used to calculate the values ​​of hyperbolic functions.

Dependency graph

The dependency graph is ideologically close to the call graph, only it does not illustrate calls, but dependencies between different source code files.

Direct dependency graph

A direct dependency graph (include graph) illustrates a dependency chain down to the file being documented, i.e. which files were connected to the file being documented, then which files, in turn, were connected to those files, etc.

To build such graphs, you need to set the following option in the settings file:

 INCLUDE_GRAPH = YES 

An example is shown below:

Reverse dependency graph

The inverse graph of dependencies (included by graph) illustrates a chain of dependencies on the file being documented, i.e. then which files include the documented file, then which files included these files, etc.

To build such graphs, you need to set the following option in the settings file:

 INCLUDED_BY_GRAPH = YES 

An example is shown below:

Directory graph

The graph of directories (directory graph) is designed to graphically represent the directory in question. To construct such a graph, use the following option:

 DIRECTORY_GRAPH = YES 

Please note that one of the elements of the graph has a red stroke, which means that other directories are nested in this directory.

UML and Doxygen

Doxygen allows you to create diagrams "in a style similar to the Unified Modeling Language." Developers are very carefully expressed in this regard, since this possibility does not imply that an accurate and competent UML scheme will be built on the basis of the code, other tools should be used for this task, and they often fail, because UML is primarily expressed an idea, albeit sometimes quite close to a specific implementation.

So in order to build charts in UML style, you need to set the following option:

 UML_LOOK = YES 

Let us again refer to the example used earlier, just to supplement it with open, closed and protected attributes and methods:


Unfortunately, Doxygen is often not able to reflect many more complex concepts, if only simply because it is not possible to specify which particular classes need to be included in the diagram. Therefore, in cases where it is necessary to illustrate, for example, an applied design pattern or some other solution, it is sometimes easier and more efficient to build a diagram in another editor and simply import it. Fortunately, for one of the very common PlantUML specialized editors, Doxygen has built-in support (to use it, you must specify the path to in the option).

First of all, you need to make sure that Java is installed on your computer and configured correctly, and then specify the correct path to the jar file using the appropriate option:

 PLANTUML_JAR_PATH = __jar_ 

After that, you need to use the corresponding \ startuml and \ enduml commands to insert a PlantUML diagram:

 \startuml [{file}] ["caption"] [<sizeindication>=<size>] ... \enduml 

All parameters in this case are optional. The file parameter specifies the name for the generated file; if not specified, it will be selected automatically; the caption parameter sets a label to the scheme; The last parameter is used to specify the size of the circuit.

Now let's go directly to the example (the diagram for the “linker” design pattern is shown below):

 /*! \file  (. Composite pattern) —   ,            .            .        UML: \startuml interface Component { +doThis() } class Composite { -elements +addElement() +doThis() } class Leaf { +doThis() } Component <|-- Leaf Component<|-- Composite Composite o-- Component \enduml */ 

The result is shown below:

Conclusion

Finally, it should be noted that the schemes can be built in any editor you prefer or with the help of other generators, and then the result can be imported into Doxygen. In general, it all depends on your requirements and the tasks that you face; In some cases, the opportunities that Doxygen provides for you will suffice, and then I hope this article will be a pleasant find for you; and sometimes they may not be enough and then other tools and other solutions will be required.

Thanks for attention!