Repository navigation
Conversation
`clanguru docs` documented every function definition and class of the translation unit, including those of the headers it includes. For a GoogleTest file this lists libstdc++'s `__gthread_*` functions from gthr-default.h and gtest's `RUN_ALL_TESTS`, with those headers' line numbers, under the title of the test file. Wherever libclang finds the system headers, test_doc_structure_for_gtest_files failed on main for the same reason. The parser keeps every declaration, because the mock generator needs the headers' ones; the documentation now takes only those located in the source file.
Only -I and -D were taken from the compilation database. A directory passed as -isystem (CMake does so for SYSTEM includes, and for the generated configuration headers of some build systems) was dropped, as were -iquote, -idirafter, -include, -imacros and -U. libclang then parsed the file without those headers, and every `#ifdef` on a macro they define took the wrong branch: the documentation showed the code of a configuration the file is not built in.
cuinixam
approved these changes
Oct 5, 2026
| def _filter_includes_and_defines(options: list[str]) -> list[str]: | ||
| """Keep only -I and -D flags (including their values when passed as separate arguments).""" | ||
| #: Options that decide what the preprocessor sees: include paths, macros and forced includes. | ||
| PREPROCESSOR_OPTIONS = ("-I", "-D", "-U", "-isystem", "-iquote", "-idirafter", "-include", "-imacros") |
Owner
There was a problem hiding this comment.
There might still be options which are ignored but the gap is smaller than before.
Owner
|
@ubmarco is there anything else you want to change in this PR? Otherwise I will remove the draft flag and merge it. |
This branch had an error being deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Two fixes for
clanguru docs, found while generating the source listings of SPLED with spl-core. Both made a listing show code that is not the file's, or not the configuration the file is built in.1. Document only the declarations of the source file itself
generate_doc_structuredocumented every function definition and class of the translation unit, including those of the headers the file includes. For a GoogleTest file this lists libstdc++'s__gthread_*functions fromgthr-default.hand gtest'sRUN_ALL_TESTS, with those headers' line numbers, under the title of the test file.On a machine where libclang finds the system headers,
test_doc_structure_for_gtest_filesalready fails onmainfor this reason (the expected file has no__gthread_*functions).RUN_ALL_TESTSis gone fromtests/data/test_gtest.cc.md: it comes fromgtest.h, not from the test file.2. Keep every preprocessor option of the compile command
Only
-Iand-Dwere taken from the compilation database. This one is the more serious of the two:-isystem, and the options-iquote,-idirafter,-include,-imacrosand-U.#ifdefon a macro they define took the wrong branch.-isystem. Its listings showed the "no feature defined" branch, which put a test specification of another product variant into the variant's report.-std=,-W*and-O*are still not passed, as before.Tests
test_doc_structure_lists_only_the_declarations_of_the_source_file: a source including a local header that defines a function and a class.test_doc_structure_follows_the_branches_of_a_system_include: a macro from an-isystemheader selects the branch.test_get_includes_and_defineswith the added options.Both new tests fail without their fix.
pypeline runpasses locally: pre-commit, 139 passed / 4 skipped, and the docs build. The docs build's 7 autodoc import warnings are the same as without these changes.