How can I make doxygen create full inheritance diagrams across multiple projects?

Question

When using doxygen to generate C++ inheritance diagrams, I've noticed that the diagrams can be incomplete.

If several projects are documented using tag files to allow cross-referencing, doxygen will successfully show all base classes that exist in other tag files, but it will not show derived classes if they are in other tag files. The derived classes shown are always only the classes that exist in the current project.

Example project 1 code:

class A {};

class B : public A {};

class C : public A {};

Example project 2 code:

#include <proj1.h>

class D : public A {};

class E : public A {};

class F : public E {};

An inheritance diagram of A from project 1, using a tag file from project 2 - where is D, E & F?

An inheritance diagram of E from project 2, using a tag file from project 1 - parent class A is shown.

Is there a setting to tell doxygen to generate complete inheritance graphs across projects when tag files are used?

Cubital

This could be a doxygen bug. – Vines

Not sure if it will help you across multiple objects but have you tried Graphviz? – Fruit

@Fruit Yes, doxygen is using Graphviz (specifically the tool dot) to generate those graphs, if I understand you correctly. – Cubital

Sorry for the typo , it should have read "across multiple projects". – Fruit

Not sure whether or not this question is of interest, but as far as I can see when setting HAVE_DOT=YES the correct graph is shown. When not setting the HAVE_DOT=YES the D, E and F are missing. – Selfsealing

Maybe this is a dumb question, but are the project2 tag files included in the project1 configuration file? – Cyanogen

Can you also post your Doxyfile? I was wondering if you use ALLEXTERNALS=YES, or maybe HIDE_UNDOC_RELATIONS=NO or other potentially relevant settings. – Manley

Without have_dot doxigen uses partial diagrams, because it doesn't use Graphviz – Adsorbent

Answer 1

Here's a comprehensive guide detailing how you can use Doxygen to create full inheritance diagrams that cross-reference multiple projects. This is made possible by leveraging Doxygen's tag files.

Steps in Detail

1. Generate Doxygen Tag Files for Each Project: Tag files are a kind of metadata that Doxygen uses to create links between different sets of documentation. First, you need to run Doxygen on each of your projects separately to create individual tag files:

For example, Open Doxyfile in your project directory and set the following parameters:

    GENERATE_HTML = NO
    GENERATE_LATEX = NO
    GENERATE_RTF = NO
    GENERATE_MAN = NO
    GENERATE_TAGFILE = myProj.tag
    INPUT = /path_to_your_project_files/

This configuration will output a file named myProj.tag, which holds all the relation information about the classes and files for your current project. Repeat for all your projects.

2. Cross Reference between Different Projects: Now that we have our tag files, we can make the specific project reference to other projects.

As an example, for project1, you'd set TAGFILES parameter in Doxyfile like so:

    GENERATE_HTML = YES
    GENERATE_LATEX = NO
    GENERATE_RTF = NO
    GENERATE_MAN = NO
    TAGFILES = /path_to_tag_files/project2.tag=/url_or_path_to_project2_documentation \
               /path_to_tag_files/project3.tag=/url_or_path_to_project3_documentation

So, whenever you generate the documentation for project1, Doxygen will also use data from the tag files of project2 and project3.

3. Visualizing Inheritance Diagrams: To get the full view of the inheritance diagrams, make sure you enable Graphviz's dot tool in your Doxyfile. This tool creates graph-based diagrams of the relationships between classes.

Make sure to set:

    HAVE_DOT = YES
    CLASS_DIAGRAMS = YES
    CLASS_GRAPH = YES

These settings ensure that Doxygen generates the inheritance and collaboration diagrams for the classes.

Remember, in order for the cross-referencing to work properly, each project needs to be aware of all others. Hence, be sure to list the tag files of every project in the TAGFILES option when generating the documentation for each individual project.

Let's have a look at your example:

Example project 1 code: Here we group the related classes (A, B, C) under the title "Project 1".

/** @defgroup project1 Project 1
 *  This is the first group
 *  @{
 */
class A {};

class B : public A {};

class C : public A {};
/** @} */ // end of project1

Example project 2 code: Similarly, we group the classes (D, E, F) under "Project 2".

/** @defgroup project2 Project 2
 *  This is the second group
 *  @{
 */
#include <proj1.h>

class D : public A {};

class E : public A {};

class F : public E {};
/** @} */ // end of project2

In these examples, the @defgroup command is used to define a group while the @{ and @} commands are used to close off the classes associated with the group. When you decide to add more member classes to the group, the @ingroup command will be handy.

I hope this helps you, and others who come across this, to generate complete inheritance diagrams across multiple projects using Doxygen!

Huguenot

Which version of doxygen did you use? I assume that what you mention under 3 is part of the settings for the second run? – Selfsealing