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?

[cantonios]

The documentation won't currently build from the main source yet - I'm working to fix it. But I do have a branch with my current fixes:

git clone -b doxyfix --single-branch https://gitlab.com/cantonios/eigen.git
cd eigen
cmake -B .build
make -C .build doc 1>doc.log

You should see all the warnings about unable to resolve link. The html folder will be under .build/doc/html. One example page with broken links is

• group__CoeffwiseMathFunctions.html

For example, in table of math functions pretty much all the member function links (a.abs(), m.cwiseAbs(), etc...) are broken. If I remove the Eigen/Eigen header and re-run the build

rm Eigen/Eigen
make -C .build doc -j12 1>doc.log

then all the symbols are resolved, and the links start working.

[albert-github]

With the instructions given I can confirm that the problem occurs.

On the mentioned page (group__CoeffwiseMathFunctions.html resulting from source file doc/CoeffwiseMathFunctionsTable.dox) we see:

Here:

• for a.abs() we see the code a.<a class="el" href="">abs</a>(); this is strange an empty href
• for abs(a) we see <a class="el" href="namespaceEigen.html#a5199fee63bdda17eed082406ba1a98c3">abs</a>, this is as expected
• for m.cwiseAbs() we see m.<a class="el" href="">cwiseAbs</a> so again an empty href.

When removing the file Eigen/Eigen we get for everything proper links:

• for a.abs() we see the code a.<a class="el" href="classEigen_1_1ArrayBase.html#a86c66d70354eb6b0d098e75c99f5aede">abs</a>
• for abs(a) we see <a class="el" href="namespaceEigen.html#a5199fee63bdda17eed082406ba1a98c3">abs</a>
• for m.cwiseAbs() we see m.<a class="el" href="classEigen_1_1MatrixBase.html#ae04b39cbc74f2e12e3609df7117b0394">cwiseAbs</a>

Some side notes:

• I tried to run the problem under Cygwin and this went fairly smoothly except
  • first run failed when compiling the (test) examples as M_PI was not known replacing in doc/special_examples/Tutorial_sparse_example_details.cpp the line

    Eigen::ArrayXd boundary = Eigen::ArrayXd::LinSpaced(n, 0, M_PI).sin().pow(2);
    

    by

    Eigen::ArrayXd boundary = Eigen::ArrayXd::LinSpaced(n, 0, 3.141565359).sin().pow(2);
    

    solved this issue
  • initial run was quite slow as compilation of the (test) examples took quite a bit of time and also the generation of the images took some time (especially as I had to set, due to s specific Cygwin threading problem: DOT_NUM_THREADS = 1 and I also set USE_MATHJAX=YES).
  • subsequent runs went quite a bit faster.
• I tried to run under Windows (MSVC 2019), but this failed with compilation errors for the (test) examples, so I didn't try this path further (with some tricks I could run just doxygen though, i.e. manipulating the Doxyfile and running just doxygen on the right directory ).

[doxygen]

[edit: I overlooked the resolver.tar.gz which is also a small example to capture the problem]

I was able to capture the problem is a very small example issue11282.zip

running doxygen Doxyfile.nok will show the problem, while doxygen Doxyfile.ok is ok.

I think doxygen's symbol resolving algorithm gets confused by the file and namespace with the same name.

[doxygen]

@cantonios Please verify if the referenced commit fixes the problem for you. Do not close the issue, this will be done automatically when the next official release becomes available.

[cantonios]

@cantonios Please verify if the referenced commit fixes the problem for you. Do not close the issue, this will be done automatically when the next official release becomes available.

Yes, that commit fixes the issue, thank you!

[doxygen]

This issue was previously marked 'fixed but not released',
which means it should be fixed in doxygen version 1.13.0.
Please verify if this is indeed the case. Reopen the
issue if you think it is not fixed and please include any additional information
that you think can be relevant (preferably in the form of a self-contained example).