fix: specializations and deduction guides are listed in order

[gennaroprota]

SpecializationFinalizer::sortBackPointers compared Symbol::Name and fell back to comparing the SymbolIDs. But every entry in the lists of specializations and deduction guides carries the name of the primary, so the name never decided anything and the order was always the fallback (the order of the hashes). That is the "weird" order both #1250 and #1260 report, and it is one root cause behind both of them, since specializations and deduction guides go through the same comparator.

These lists now go through SymbolIDCompareFn, the comparison every other list of symbols uses, which already ranked template arguments. Only the guides needed anything new: GuideSymbol::operator<=> never compared Deduced, although its documentation said it did, so guides that deduce different specializations were ordered by the types they take instead. What a guide deduces decides first now, with the types it takes deciding between guides that deduce the same thing.

The new fixture declares everything out of order on purpose. Its specializations come out as:

A<int, int>
A<T&, U>
A<T*, U>

and its deduction guides as:

B<T>     declared B(T*) -> B<T>
B<char>  declared B(int) -> B<char>
B<int>   declared B(bool) -> B<int>
B<int>   declared B(char) -> B<int>

(Note the two guides that deduce B<int>.)

Types rank by kind, in the order the type nodes are declared: a named type, then a reference, then a pointer. That is why A<int, int> comes first and A<T*, U> last. It is the same ranking the existing comparison already applied to template arguments elsewhere.

Fixes #1250.
Fixes #1260.

Changes

• Source: the specialization and deduction-guide lists are ordered with SymbolIDCompareFn, the comparison used for every other list of symbols, which moves to a header of its own so both finalizers share it. GuideSymbol::operator<=> gained the Deduced comparison its documentation already promised. The doc comments on the affected fields of RecordSymbol and FunctionSymbol are corrected too, as they referred to sorting by referent name then ID.
• Tests: New fixture tests/golden/fixtures/symbols/record/specialization-order.cpp, covering partial and explicit specializations and a set of deduction guides, declared in an order that can't be the same as the output order. It uses the adoc generator so the golden records the names, which makes the resulting order reviewable.
• Golden tests: Regenerated the XML goldens that record these lists. Every changed line is a permutation of the same IDs, verified line by line: nothing is added, removed, or renamed. The XML records only IDs, not the arguments the order now follows, so those diffs cannot be checked by eye; the AsciiDoc fixture above is where the ordering is legible.

Testing

The new fixture pins both lists and the tie-break between guides that deduce the same specialization, in a generator whose output shows names rather than hashes.

Documentation

No change is needed under docs/.

[github-actions]

✨ Highlights

• 🧪 Existing golden tests changed (behavior likely shifted)

🧾 Changes by Scope

Scope	Lines Δ%	Lines Δ	Lines +	Lines -	Files Δ	Files +	Files ~	Files ↔	Files -
🛠️ Source	62%	583	303	280	8	1	7	-	-
🥇 Golden Tests	38%	350	312	38	13	3	10	-	-
Total	100%	933	615	318	21	4	17	-	-

Legend: Files + (added), Files ~ (modified), Files ↔ (renamed), Files - (removed)

🔝 Top Files

• src/mrdocs/Metadata/Finalizers/SymbolIDCompare.hpp (Source): 273 lines Δ (+273 / -0)
• src/mrdocs/Metadata/Finalizers/SortMembersFinalizer.cpp (Source): 251 lines Δ (+1 / -250)
• tests/golden/fixtures/symbols/record/specialization-order.adoc (Golden Tests): 221 lines Δ (+221 / -0)

Generated by 🚫 dangerJS against be3f6d7

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 83.12%. Comparing base (e31308f) to head (be3f6d7).

Additional details and impacted files

@@           Coverage Diff            @@
##           develop    #1264   +/-   ##
========================================
  Coverage    83.12%   83.12%           
========================================
  Files           35       35           
  Lines         3662     3662           
  Branches       844      844           
========================================
  Hits          3044     3044           
  Misses         410      410           
  Partials       208      208           

Flag	Coverage Δ
bootstrap	83.12% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[cppalliance-bot]

An automated preview of the documentation is available at https://1264.mrdocs.prtest2.cppalliance.org/index.html

If more commits are pushed to the pull request, the docs will rebuild at the same URL.

2026-08-26 10:06:37 UTC