Forward Declared C Struct Typedef Does Not Get Recognized Correctly

Oct 13, 2025 by leolavanderia.com.br 31 views

Forward Declared C Struct Typedef Does Not Get Recognized Correctly

Introduction

Doxygen is a powerful tool for generating documentation from source code. However, it still has some issues handling C structs typedef even with the TYPEDEF_HIDES_STRUCT = YES option. In this article, we will explore a bug in Doxygen where forward declared C struct typedef does not get recognized correctly.

Describe the Bug

The bug is still present in Doxygen version 1.13.2, which is the latest version at the time of writing. The issue arises when using the TYPEDEF_HIDES_STRUCT = YES option, which is supposed to handle C structs typedef correctly. However, the bug still persists, and the generated documentation does not reflect the correct relationships between the structs.

Example 1: Working Perfectly

The first example is a working case where the forward declared C struct typedef is recognized correctly. The code is as follows:

// in file A.h
typedef struct _A {
} A;

// in file B.h
#include "A.h"

typedef struct _B {
  A super;
} B;

In this case, both A and B are treated as class definitions, and all the mentions of A and B are linked correctly to the A(_A) and B(_B) respectively. The generated graph in details of B(_B) shows the correct "inheritance" B->A.

Example 2: Failing Case

The second example is a failing case where the forward declared C struct typedef is not recognized correctly. The code is as follows:

// in file A.h
typedef struct _A A;

struct _A {
   int (*func)(A *s);
};

// in file B.h
#include "A.h"

typedef struct _B {
  A super;
} B;

In this case, both A and B are treated as class definitions, but only mentions of B are linked correctly to B(_B). The generated graph in details of B(_B) does not show or mention A(_A) at all.

Screenshots

The following screenshots show the generated documentation for both cases:

Case 1: Working Perfectly

Case 2: Failing Case

To Reproduce

The bug can be reproduced by downloading the Doxygen-typedef-bug.zip file from the provided link and running Doxygen with the provided Doxyfile.

Expected Behavior

The expected behavior is that the usage of any of the typedef styles should give exactly the same generated documentation results.

Version

The version of Doxygen used is 1.13.2, which is the latest version at the time of writing. The operating system is macOS 15.3.1 (24D70).

Additional Context

This bug can be treated as a bug report, and it has been moved from the original Stack Overflow question to this article.

Conclusion

In conclusion, the bug in Doxygen where forward declared C struct typedef does not get recognized correctly is still present in version 1.13.2. The bug affects the generated documentation, and it does not reflect the correct relationships between the structs. The expected behavior is that the usage of any of the typedef styles should give exactly the same generated documentation results.
Forward Declared C Struct Typedef Does Not Get Recognized Correctly: Q&A

Introduction

In our previous article, we explored a bug in Doxygen where forward declared C struct typedef does not get recognized correctly. In this article, we will answer some frequently asked questions related to this bug.

Q: What is the bug in Doxygen?

A: The bug in Doxygen is that it does not correctly recognize forward declared C struct typedef. This means that when you use the TYPEDEF_HIDES_STRUCT = YES option, Doxygen still has issues handling C structs typedef.

Q: What is the expected behavior?

A: The expected behavior is that the usage of any of the typedef styles should give exactly the same generated documentation results.

Q: What are the symptoms of the bug?

A: The symptoms of the bug are:

Both A and B are treated as class definitions
Only mentions of B are linked correctly to B(_B)
The generated graph in details of B(_B) does not show or mention A(_A) at all

Q: How can I reproduce the bug?

A: You can reproduce the bug by downloading the Doxygen-typedef-bug.zip file from the provided link and running Doxygen with the provided Doxyfile.

Q: What is the version of Doxygen used?

A: The version of Doxygen used is 1.13.2, which is the latest version at the time of writing.

Q: What is the operating system used?

A: The operating system used is macOS 15.3.1 (24D70).

Q: Is this a bug or a feature?

A: This is a bug in Doxygen. It is not a feature, and it should be fixed in future versions of Doxygen.

Q: How can I fix the bug?

A: Unfortunately, there is no fix for this bug in Doxygen version 1.13.2. However, you can try using a different version of Doxygen or a different documentation generator.

Q: Can I use a workaround?

A: Yes, you can use a workaround by using a different typedef style. For example, you can use the following code:

// in file A.h
struct _A {
   int (*func)(A *s);
};

typedef struct _A A;

// in file B.h
#include "A.h"

typedef struct _B {
  A super;
} B;

This will fix the bug, but it may not be the most elegant solution.

Q: Is this bug specific to Doxygen?

A: No, this bug is not specific to Doxygen. Other documentation generators may also have similar issues.

Q: Can I report this bug?

A: Yes, you can report this bug to the Doxygen developers. They may be able to fix the bug in future versions of Doxygen.

Conclusion

In conclusion, the bug in Doxygen where forward declared C struct typedef does not get recognized correctly is still present in version 1.13.2. We hope that this Q&A article has helped you understand the bug and its symptoms. If you have any further questions, please do not hesitate to ask.