feat: warn when a documented declaration names a filtered symbol - #1316
Open
gennaroprota wants to merge 5 commits into
Open
gennaroprota wants to merge 5 commits into
gennaroprota wants to merge 5 commits into
Conversation
The filters that drop whole kinds of symbol - private members, anonymous namespaces, file-level statics - run before the ones that match names, so `@implementationdefined` and `@seebelow` on a private member, and the globs that mirror those commands, were read too late to matter: the member stayed a dependency and a public signature involving it printed the name despite the command. The command is now read when one of those filters rejects a symbol.
Before this fix, a file excluded with `exclude` or `exclude-patterns` lost every symbol in it, commands and all, so `@implementationdefined` on a type in an excluded header did nothing. For instance, a function returning that type was documented with the real type name instead of the placeholder. With the fix, the command wins, because it's a statement about how we want the symbol to appear when something else names it, and that's more specific than excluding a file. A file that was never in `input` is another matter, because a command in a third-party header speaks for that library rather than for the project being documented, so a symbol from one is still dropped.
Contributor
✨ Highlights
🧾 Changes by Scope
🔝 Top Files
|
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## develop #1316 +/- ##
========================================
Coverage 83.12% 83.12%
========================================
Files 35 35
Lines 3662 3662
Branches 844 844
========================================
Hits 3044 3044
Misses 410 410
Partials 208 208
Flags with carried forward coverage won't be shown. Click here to find out more. ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
gennaroprota
force-pushed
the
feat/warn_when_a_documented_declaration_names_a_filtered_symbol
branch
from
September 22, 2026 07:12
67d7bde to
4e976d6
Compare
gennaroprota
changed the title
|
An automated preview of the documentation is available at https://1316.mrdocs.prtest2.cppalliance.org/index.html If more commits are pushed to the pull request, the docs will rebuild at the same URL. 2026-09-23 08:20:47 UTC |
This fixes a bug for which the documented accessor `dom::Function::impl` returned `impl_type const&`, where `impl_type` was a private alias. The alias has no page, so a reader of the signature met a name that led nowhere. Make the alias public and document it, as `dom::Array` and `dom::Object` already do.
A symbol removed by the filters has no page, so a declaration naming it sends the reader nowhere. A corpus pass now walks the documented declarations and reports those names, over return types, parameters, public bases, aliases and variables, and inside the arguments given to a template. Only the project's own symbols are reported. A name that reaches the symbol through a template specialization is left alone as well, since the primary template documents it and the reader lands there.
This gives projects that deliberately use filtered symbols in the public API a way to silence the new warning in one place, instead of e.g. annotating every symbol with `@implementationdefined`. The default is `true`, like for the other options of the `warn-*` family. The golden fixtures set the option to `false`, as several of them exist exactly to exercise a filtered symbol reached from the documented API.
gennaroprota
force-pushed
the
feat/warn_when_a_documented_declaration_names_a_filtered_symbol
branch
from
September 23, 2026 08:14
4e976d6 to
264c2f3
Compare
This branch has not been 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.
This PR:
Fixes the interaction between filters and
@implementationdefined/@seebelow. Before it. the filters won and the commands were thrown away, This meant that, for instance, a function returning a filtered type was rendered with the filtered type name in the docs, and the user had no way to avoid this.Adds the warning issue warning: filtered namespace in public API #337 asks for, and a corresponding option to silence it. Thanks to the above, the user can choose to avoid the warning by marking the filtered symbol
@implementationdefined.Changes
@implementationdefinedor@seebelowcommand outranks the filters that hide kinds of symbols, and survives an exclusion of the file it is in; aFilteredSymbolFinalizerreports filtered symbols named by the documented API.warn-if-filtered-in-public-apioption, with the generated config schema updated.warn-as-errorover an API that names a filtered symbol will start failing. Settingwarn-if-filtered-in-public-api: falserestores the old behavior, and marking the symbol@implementationdefinedfixes the issue properly.Testing
Two ctest entries in tests/CMakeLists.txt run the tool over tests/diagnostics/filtered-in-public-api/, an input that names a filtered symbol as a base class and as a return type.
mrdocs-warn-filtered-in-public-apiruns it with--warn-as-errorand expects the failure;mrdocs-quiet-filtered-in-public-apiruns the same input with the option off and expects a clean exit. The second is what gives the first its meaning, since it shows nothing else in that input warns.The two filter fixes are covered by golden fixtures instead, because their effect is in the generated page: tests/golden/fixtures/filters/symbol-type/private-implementation-defined pins the extraction mode of a marked private member, and
tests/golden/fixtures/filters/file/excluded-implementation-defined pins the rendered signature of a marked type in an excluded header.
Documentation
warn-if-filtered-in-public-apijoins thewarn-*list on the Diagnostics page, with a pointer to@implementationdefinedas the way to settle the warning rather than switch it off. Its own entry in the options reference comes fromConfigOptions.jsonand needs no separate edit.Closes #337.