getDefsNew fails to find symbols if a filename matches a namespace name

[cantonios]

Describe the bug

For the Eigen project, we have a namespace Eigen, and a header file named Eigen. Doxygen fails to find certain symbols like Eigen::Aligned because of the conflicting scope names.

The reason seems to be because in the getDefsNew function here, the function first looks for a single scope. It finds the file version of Eigen (instead of the namespace scope), then tries to search that file scope for the symbol and fails.

To Reproduce

resolver.tar.gz

Expected behavior

If there are multiple matching scopes, doxygen should search all of them for the match.

Version

Compiled from master commit 163ed03282c894bd9a15cc2a81182cb5336daefd.

Possible Solutions

The most intrusive solution is to change the SymbolResolver to return all matching symbols. You would then iterate through all possible scopes.

The least intrusive seems to be to add an argument startIndex to SymbolResolver::resolveSymbol, that would only search the range starting at startIndex. In getDefsNew, you would then increment the startIndex when searching for the scope until either you find a match, or run out of scopes.

[albert-github]

I can imagine that there might be a conflict, but I don't understand yet where this is in the output, so where does the problem:

Doxygen fails to find certain symbols like Eigen::Aligned because of the conflicting scope names.

show?

Also I don't understand the usage / purpose of the file example.dox is this intended for the normal documentation or intended to be used in a \include statement?

[cantonios]

This is a minimal reproducer extracted from Eigen's documentation.

I don't understand the usage / purpose of the file example.dox

It is a separate documentation page. We have many such pages, like https://libeigen.gitlab.io/docs/TopicInsideEigenExample.html. The purpose is usually to describe some particular usage in detail.

Where does ... show?

Since it's a \page, it shows up as a separate page, in this case under html/Bug.html. Since it doesn't find the reference to Eigen::Aligned, the page just says:

Aligned cannot be found.

where Aligned is not a link, when it should be.

[albert-github]

Shines a bit of a light on the problem.
When adding:

#include "math.h"

to example.dox the problem is gone, also when explicitly listing the used files so:

INPUT                  = src/example.dox src/math.h

and setting

INCLUDE_PATH = src

the problem as well.

I don't say the last (with the settings) is the solution as this would mean that the documentation information from the (include) file Eigen might not be added to the output.

We have to dive into the problem a bit.

[albert-github]

I dove a bit into the problem and ran with the current master (1.13.0 (163ed03)) and the problem is not present.

I think the problem is fixed but not released.

[cantonios]

Ah, I think you're right, thanks.

I was working off master, but I guess it was originally from an older commit. Running git bisect, it looks like it was "fixed" by 4ebaa8b.

[cantonios]

Actually, although this minimal reproducer seems fixed, we still do have the bug in Eigen's codebase. Temporarily renaming our Eigen header resolves the issue, meaning the name collision between the header filename and the Eigen namespace still exists. It's just that in the reproducer I provided above, we luckily happen to find the namespace scope first.

I'll see if I can rework the reproducer.

[albert-github]

I see that the repository package can easily be obtained by: git clone https://gitlab.com/libeigen/eigen.git
I also found the Doxyfile.in but I see there quite a few variables used and filenames that I cannot find at first glance (like eigendoxy_layout.xml but I see eigendoxy_layout.xml.in so some cmake commands have to be used).

• which commands have to be given to generate just the documentation (I'm not really interested in compiling Eigen)?
• where do we see in the resulting documentation an example of the problem?