Repository navigation
feat: anchors tell symbols that share a name apart by kind and signature - #1365
Open
gennaroprota wants to merge 1 commit into
Open
gennaroprota wants to merge 1 commit into
gennaroprota wants to merge 1 commit 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 #1365 +/- ##
========================================
Coverage 83.44% 83.44%
========================================
Files 36 36
Lines 3861 3861
Branches 891 891
========================================
Hits 3222 3222
Misses 417 417
Partials 222 222
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/anchors_are_disambiguated_by_kind_and_signature
branch
from
October 22, 2026 13:50
7809d8c to
c467fb7
Compare
|
An automated preview of the documentation is available at https://1365.mrdocs.prtest2.cppalliance.org/index.html If more commits are pushed to the pull request, the docs will rebuild at the same URL. 2026-11-13 17:18:06 UTC |
gennaroprota
force-pushed
the
feat/anchors_are_disambiguated_by_kind_and_signature
branch
from
October 22, 2026 14:17
c467fb7 to
e2c6bf9
Compare
gennaroprota
force-pushed
the
feat/anchors_are_disambiguated_by_kind_and_signature
branch
from
October 28, 2026 09:32
e2c6bf9 to
ca3e416
Compare
gennaroprota
force-pushed
the
feat/anchors_are_disambiguated_by_kind_and_signature
branch
from
November 13, 2026 16:08
ca3e416 to
9e274c5
Compare
|
Important Review skippedToo many files! This PR contains 130 files, which is 30 over the limit of 100. To get a review, reduce the PR to 100 files or fewer by splitting it into smaller PRs or changing its base branch. Upgrade to a paid plan to raise the limit. This review couldn't start because sufficient usage credits or metered capacity aren't available. Add credits or update usage-based reviews in the billing tab, then retry.
 |
 [Medium impact] The PR appears safe to merge; both previous findings are fixed and no new actionable issues remain.
|
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
gennaroprota
force-pushed
the
feat/anchors_are_disambiguated_by_kind_and_signature
branch
from
November 13, 2026 16:44
9e274c5 to
1afd409
Compare
With `legible-names`, symbols of one scope that share a name, ignoring case, were told apart by a suffix taken from their symbol IDs: an overload set of `abs` and its two functions got `abs-043`, `abs-04b` and `abs-01`. The suffix meant nothing to a reader. It changed whenever the IDs did, as they can on a Clang upgrade or with an unrelated configuration change, and it appeared, or grew longer, when one more symbol of that name joined the scope, so links into the documentation broke although nothing they pointed to had changed. We now give the plain name to the overload set (to the most accessible of the functions of one name, when a class splits them by access), to the primary template, or, between symbols of different kinds, to the kind that comes first, such as a class next to a concept. Each of the others adds the words that tell it apart: its kind (`Quantity-concept`), the number of its parameters or template arguments (`resize-1`), then their types and the qualifiers (`resize-2-double-comma-int`, and `at-1-int-const` for `at(int) const`). The other overload sets add their access, followed by `static` if their functions are static, and using-declarations add `using` and the class they name the member in. A conversion function is named after the type it converts to (`2conversion-int`), so only conversions to one type share a name. A new symbol thus changes only the anchors of the symbols it has to be told apart from. Each suffix starts with a keyword or a digit, so it can never be the name of a member, whose anchor follows its parent's after a `-` in a single-page fragment. The symbol ID remains the suffix of last resort, for symbols that nothing else tells apart, such as overloads that differ only in their constraints, or classes whose names differ only in case. Note that anchors change, and with them the file names of multipage output, for every symbol that shares its name with another and for every conversion function, so existing links to those pages break once. Fixes cppalliance#1288. Fixes cppalliance#1308.
gennaroprota
force-pushed
the
feat/anchors_are_disambiguated_by_kind_and_signature
branch
from
November 13, 2026 17:05
1afd409 to
be8332c
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
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.
With
legible-names, symbols of one scope that share a name, ignoring case, were told apart by a suffix taken from their symbol IDs: an overload set ofabsand its two functions gotabs-043,abs-04bandabs-01. The suffix meant nothing to a reader, changed whenever the IDs did (as they can on a Clang upgrade, or with an unrelated configuration change, as #1308 shows), and appeared, or grew longer, when one more symbol of that name joined the scope. Links into the documentation broke although nothing they pointed to had changed.This PR implements the scheme #1288 proposes, with the symbol kind as an extra step for the case #1308 reports. At most one of the members that share a name keeps it: the most accessible of the functions of that name, an overload set before a lone function, the primary template, or, between symbols of different kinds, the kind that comes first, such as a class next to a concept. Each of the others adds the words that tell it apart: its kind (
Quantity-concept), the number of its parameters or template arguments (resize-1), then their types and qualifiers (resize-2-double-comma-int, andat-1-int-constforat(int) const), and for function templates the number of template parameters (f-0-t1), then for their specializations the template arguments (make-0-t0-int). The other overload sets add their access andstatic(foo-protected-static), and using-declarations addusingand the scope they name the member in (get-using-First,g-using-A-scope-B). A conversion function is named after the type it converts to (2conversion-int), so adding one no longer renames the others. A new symbol thus changes only the anchors of the symbols it has to be told apart from, and turning onextract-privateno longer changes the anchor of the public overload set, or of a public function with no public overloads. Between two functions of one name and access with no overloads, one static and one not, the non-static one keeps the name, as between overload sets.A parameter's type is spelled as the function's type holds it: without a top-level
constorvolatile, sinceat(int const)declares the same function asat(int), and an array or a function as the pointer it is adjusted to, also inside a function type that a parameter is built from. Every punctuation character of a spelling becomes a word, such asscopefor::,ltandgtfor<and>,comma,minus,ptr,ref,rrefandpack, so that spellings which differ only in their punctuation stay apart:Offset<-1>andOffset<1>,Key<'$'>andKey<'@'>, orA<B<int>, C>andA<B<int, C>>. Acommaalso separates two parameters, or two template arguments, as in the source, so thatf(long, long long)andf(long long, long)stay apart too. A parameter of typestd::vector<int>&thus addsstd-scope-vector-lt-int-gt-ref. An identifier outside ASCII is spelled whole. When the words that spell a signature, the arguments of a specialization, the target of a conversion function or the scope of a using-declaration would take more than 64 characters, they are replaced byhand the first eight hex digits of their xxh3 hash, which is the same on every platform.Each suffix starts with a keyword or a digit, so it can never be the name of a member, whose anchor follows its parent's after a
-in a single-page fragment. The words that start with a digit (2function,2variable,2guide,2namespace-alias,2enumerator,2macro) follow the reserved names MrDocs already gives to special functions, such as2constructor; the other kind words (class,enum,typedef,concept,using,namespace) and the access words are keywords. No two kinds share a word, so that two members of different kinds that add their words never coincide. Every record addsclass, whatever its key, so that turning astructinto aclassdoes not change its anchor.Names are still compared ignoring case, so that two anchors never collide as files on a case-insensitive filesystem. The symbol ID remains the suffix of last resort, for symbols that nothing else tells apart: overloads and specializations that differ only in their constraints, names of one kind that differ only in case, redefined macros, several unnamed records in one scope, copies of inherited members with the same signature.
Two cases are left as they are. Overloads that differ only in a dependent expression, such as
f(Bits<~N>)andf(Bits<N>), are merged into one symbol before anchors are computed, so there is nothing for this PR to tell apart. And the adjustment of parameter types does not look inside the constraint of anautotype or inside adecltype. A per-symbol anchor override, which #1308 also asks for, is left for a follow-up.Changes
foo-1-int-ptr, which spells thefoo(int*)its own@copydocnames.Testing
The disambiguation fixture pins the anchors of overloads,
constoverloads, a parameter with a top-levelconstnext to aconstmember function, conversion functions (two of them to one type, and one to a type too long to spell), overload sets that a class splits by access, a public function next to protected overloads, a public and a protected function of one name, a static and a non-static function of one name, overloads whose signatures are too long to spell, class template specializations, specializations whose arguments differ only in a sign or in a character, overloads and specializations whose lists differ only in where one type ends, explicit specializations of a function template, overloads whose template arguments differ only in their nesting, overloads on types named outside ASCII, parameters declared as arrays and as functions, also inside a parameter of function pointer type, a class next to a concept whose name differs only in case, a struct next to a function, deduction guides, a struct named like the globalindex, a namespace next to a namespace alias whose name differs from it only in case, and a class next to both an alias-declaration whose name differs from it only in case and a using-declaration of its own name. The using-declarations fixture pins using-declarations of one name, including one with no qualifier, two whose qualifiers differ only before their last component, and one whose qualifier is too long to spell. The without-overload-sets fixture pins the function called with no arguments keeping the plain name whenoverloadsis off, and the visibility fixture pins overload sets split by access and bystatic. Every anchor removed from the regenerated goldens is an old symbol-ID anchor or the old anchor of a conversion function.Documentation
configuration/output.adoc describes how colliding names are told apart, next to its mention of
legible-names, with an example taken from the new options snippet.Fixes #1288.
Fixes #1308.