如何解决Doxygen提示“匹配多个目录”的问题？

I’ve dealt with exactly this kind of modular directory setup paired with Doxygen configuration before—that "multiple directories matched" warning usually pops up because Doxygen can’t tell apart duplicate path prefixes across nested directories. Here’s how to fix it step by step:

1. Narrow Down INPUT & EXCLUDE to Avoid Redundant Scans #

First, make sure your Doxygen config doesn’t include the top-level gambit directory directly (this would cause Doxygen to scan both gambit/Utils and gambit/Utils/include/gambit/Utils, creating path conflicts). Instead, explicitly list only the include and src directories for each module:

INPUT = gambit/Utils/include gambit/Utils/src \
        gambit/Core/include gambit/Core/src

Also, exclude any build artifacts or temporary files that don’t need documentation:

EXCLUDE = */build */temp *.o *.obj

2. Use STRIP_FROM_PATH to Unify Path Prefixes #

This is the key fix for your issue. It removes specified path prefixes from the generated documentation, aligning the documented paths with how you #include files in code, and eliminates duplicate path matching.

For your structure, set STRIP_FROM_PATH to point to the include directories of each module:

STRIP_FROM_PATH = gambit/Utils/include gambit/Core/include

Now, when Doxygen processes gambit/Utils/include/gambit/Utils/somefile.hpp, it will strip off the gambit/Utils/include prefix, leaving the clean path gambit/Utils/somefile.hpp—exactly what you use in your #include statements. No more conflicting path matches!

3. Configure INCLUDE_PATH and Enable Include File Visibility #

Help Doxygen resolve your header references correctly by adding your compile-time -I paths to INCLUDE_PATH, and turn on SHOW_INCLUDE_FILES to document include relationships clearly:

SHOW_INCLUDE_FILES = YES
INCLUDE_PATH = gambit/Utils/include gambit/Core/include

4. Add Directory-Level Doxygen Comments to Clarify Purpose #

To eliminate any remaining ambiguity between directories with similar names, add @dir comments either in a README.md file in each directory, or directly in one of the files within the directory:

For the top-level module directory (e.g., gambit/Utils):

/**
 * @dir gambit/Utils
 * @brief Utility module providing core helpers like string processing, logging, and config parsing
 */

For the nested include directory (e.g., gambit/Utils/include/gambit/Utils):

/**
 * @dir gambit/Utils/include/gambit/Utils
 * @brief Public header files for the Utility module
 */

Verify Your Fix #

After updating your config, run doxygen your_config_file and check the output logs. If the "multiple directories matched" warning is gone, and the generated documentation shows the same clean paths you use in #include statements, you’re all set!

内容的提问来源于stack exchange，提问作者Ben Farmer