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
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-10-01 10:37:26 UTC |
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
The filters that drop whole kinds of symbol, such as private members, anonymous namespaces and file-level statics, ran before the ones that match names, so `@implementationdefined` on a private member was read too late to matter: the member stayed a dependency, and a public signature naming it printed the name instead of the placeholder. We now read the command written on the declaration when one of those filters rejects it. A glob, or a mode inherited from a parent, still doesn't override those filters, since it doesn't speak for that one declaration. I've added tests. Note that a private member marked `@seebelow` is still dropped: it would get a page, and the only way to reach that page would be the list of private members, which `extract-private: false` hides.
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: a function returning that type, for instance, was documented with the real name of the type instead of the placeholder. We now let the command win, as it says how the symbol should appear when something else names it, which is more specific than excluding a file. Only a command written on the declaration counts, though: a glob, or a mode inherited from a parent, doesn't speak for that declaration, so a symbol it covers in an excluded file is still dropped. I've added tests. Note that a file which was never in `input` is another matter: a command in a third-party header speaks for that library, not for the project being documented, so a symbol from such a header is still dropped.
The documented accessor `dom::Function::impl` returned a reference to `impl_type`, a private alias. The alias has no page, so a reader of the signature met a name that led nowhere. This makes the alias public and documents 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. We now report such names in return types, parameters, public bases, aliases, variables and data members, and in the type arguments of a template. A filtered template named with arguments, such as `detail::impl<int>`, is reported as well. The report goes through the same list as the other `warn-*` diagnostics, so it's printed under the same file, line and column header and counts toward `max-errors`. Only symbols declared in the input files are reported, since a symbol from anywhere else belongs to another library. A member reached through a specialization of its enclosing template, such as `inner` in `outer<int>::inner`, isn't reported either, since the primary template documents it.
This gives projects which deliberately use filtered symbols in their public API a way to silence the new warning in one place, instead of, e.g., marking each such symbol `@implementationdefined`. As for most of the other `warn-*` options, the default is `true`. Note that the golden fixtures set the option to `false`, as several of them exist precisely 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
October 1, 2026 10:28
264c2f3 to
15166a6
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
@implementationdefineddoes so: a@seebelowmember would get a page reachable only from the list of private members. The warning is one of thewarn-*diagnostics of the doc-comment finalizer, so it is grouped and printed like them and counts towardmax-errors. It reports a filtered symbol named in a return type, a parameter, a public base, an alias, a variable, a data member or a template argument, and a filtered template named with arguments.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
The ctest entries in tests/CMakeLists.txt run the tool over three inputs in tests/diagnostics/. filtered-in-public-api names a filtered symbol in each position the warning covers:
mrdocs-warn-filtered-in-public-apiruns it with--warn-as-errorand expects the failure, eachmrdocs-warn-filtered-<position>entry matches the warning for one position, so one working position can't hide a broken one, andmrdocs-quiet-filtered-in-public-apiruns the same input with the option off and expects a clean exit. filtered-not-reported holds the cases that must stay silent (a private base, an@implementationdefinedtarget, a specialization of a documented template, a member reached through a specialization), andmrdocs-unreported-filtered-in-public-apiexpects a clean--warn-as-errorrun. filtered-outside-inputs checks that a filtered symbol from a header outside the inputs isn't reported, and that the same symbol is reported once its directory is an input, even an excluded one.The two filter fixes are covered by golden fixtures instead, because their effect is in the generated page. Under tests/golden/fixtures/filters/symbol-type, private-implementation-defined, private-see-below and private-implementation-defined-glob pin which private members a command or a glob brings back. Under tests/golden/fixtures/filters/file, excluded-implementation-defined, excluded-directory-implementation-defined, excluded-directory-see-below-glob and outside-input-implementation-defined pin the rendered signature of a marked type in an excluded file, in an excluded directory, under a glob, and outside the inputs.
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.