feat: move template specializations and deduction guides off parent scope page

[gennaroprota]

Class template specializations, function template specializations, and deduction guides used to share the enclosing scope's listing with their primary template. Users have repeatedly reported this as confusing: vector and vector<int> appearing side by side in the namespace index reads as if they were independent siblings, and a primary's variants were nowhere on its own page.

Specializations now appear in a dedicated "Specializations" section on the primary's documentation page, and deduction guides in a "Deduction Guides" section on the deduced class's page. The parent scope's listing carries only the primary itself. An orphan specialization (one whose primary has been excluded from extraction) stays in the parent's listing so the index can still reach it.

The corpus is unchanged: XML output and consumers of the metadata schema see the same data as before. The new sections are derived in the presentation layer.

Closes issue #1154.

[danger skip docs].

---

Summary

Moves class template specializations, function template specializations, and deduction guides off the enclosing scope's listing and onto the primary template's own documentation page. Closes #1154.

Specializations and primaries used to share the enclosing scope's listing, so vector and vector<int> appeared side by side in the namespace index — readers reported this as confusing, since the two are not independent siblings, and the primary's own page did not mention its variants at all.

After this PR:

• Each primary's documentation page gains a "Specializations" section listing the specializations of that primary.
• Each deduced class's page gains a "Deduction Guides" section listing the guides that deduce it.
• The parent scope's listing carries only the primary, not its variants.
• An orphan specialization — one whose primary has been excluded from extraction — stays in the parent's listing, so the index can still reach it.

The corpus is unchanged: XML output and consumers of the metadata schema see exactly the same data as before. The new sections are derived in the presentation layer. The diff is therefore concentrated in src/lib/Metadata/DomCorpus.{cpp,hpp} (the derivation), a few Handlebars helpers in src/lib/Support/Handlebars.cpp, and the Handlebars templates under share/mrdocs/addons/ that render the new sections. Two metadata headers (Function.hpp, Record.hpp) gain small additions to expose the primary-to-specialization link the derivation needs.

Changes

• Source: Derivation logic in src/lib/Metadata/DomCorpus.cpp (+159) and the public include/mrdocs/Metadata/DomCorpus.hpp (+36). Supporting Handlebars helpers in src/lib/Support/Handlebars.cpp (+54). include/mrdocs/Metadata/Symbol/Function.hpp (+28) and Symbol/Record.hpp (+14) expose the primary-to-specialization relationship the derivation reads. Templates updated under share/mrdocs/addons/: common/partials/symbol/tranche.hbs (the per-tranche listing that no longer prints specializations alongside the primary), and the per-format adoc/partials/symbol.adoc.hbs and html/partials/symbol.html.hbs rendering the new "Specializations" / "Deduction Guides" sections.
• Tests: All exercised through golden tests; no separate unit tests added.
• Golden tests: ~65 HTML and adoc golden-test fixtures updated across test-files/golden-tests/symbols/, test-files/golden-tests/config/, test-files/golden-tests/templates/, test-files/golden-tests/javadoc/, and test-files/golden-tests/filters/ to reflect the new layout — specializations and deduction guides moved off parent listings and onto primary pages. No .xml fixtures change, by design: the corpus is unchanged. Each updated fixture is an intentional rendering change, not a regeneration.
• Breaking changes: None at the user-facing CLI; none in the XML output or metadata schema (consumers of the corpus see the same data). The rendered HTML / adoc output for templates changes — downstream tooling that scrapes the parent scope's listing and expects to find specializations alongside the primary will need to look on the primary's own page instead.

Testing

• The ~65 HTML and adoc golden fixtures are themselves the verification: each runs the full pipeline against a fixed .cpp input and asserts the resulting .html / .adoc byte-for-byte. The unchanged .xml fixtures act as a regression guard for the architectural claim — if the corpus accidentally starts depending on the presentation change, the XML golden tests would fail.
• No CI workflow changes needed — the existing golden-test job runs all of test-files/golden-tests/ on every build, so the new expectations stay enforced going forward.

Documentation

No user-facing documentation page is added ([danger skip docs]). The change is a layout / discoverability improvement for the generated documentation: it does not introduce a new option, flag, or configuration knob a user would need to look up. The new "Specializations" / "Deduction Guides" sections are self-describing in the rendered output.

[github-actions]

✨ Highlights

• 🧪 Existing golden tests changed (behavior likely shifted)

🧾 Changes by Scope

Scope	Lines Δ%	Lines Δ	Lines +	Lines -	Files Δ	Files +	Files ~	Files ↔	Files -
🥇 Golden Tests	88%	3049	2568	481	99	-	99	-	-
🛠️ Source	12%	400	391	9	10	2	8	-	-
🏗️ Build	<1%	9	7	2	1	-	1	-	-
Total	100%	3458	2966	492	110	2	108	-	-

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

🔝 Top Files

• test-files/golden-tests/symbols/record/class-template-specializations-1.xml (Golden Tests): 364 lines Δ (+364 / -0)
• test-files/golden-tests/symbols/record/class-template-specializations-1.html (Golden Tests): 352 lines Δ (+221 / -131)
• test-files/golden-tests/symbols/record/class-template-specializations-1.adoc (Golden Tests): 224 lines Δ (+136 / -88)

Generated by 🚫 dangerJS against cc36d55

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 82.12%. Comparing base (74bf1a3) to head (cc36d55).

Additional details and impacted files

@@           Coverage Diff            @@
##           develop    #1199   +/-   ##
========================================
  Coverage    82.12%   82.12%           
========================================
  Files           33       33           
  Lines         3149     3149           
  Branches       734      734           
========================================
  Hits          2586     2586           
  Misses         387      387           
  Partials       176      176           

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

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

☔ View full report in Codecov by Sentry.
📢 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://1199.mrdocs.prtest2.cppalliance.org/index.html

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

2026-05-20 09:18:46 UTC

[alandefreitas]

This is adding exceptions to reflection. It’s reintroducing the exact problem we were fixing with reflection. It’d be easier to just store the specialization and deduction guides again in the corpus as members of the records and functions. This way, everyone has this data readily available in O(1), and the template changes are trivial. If we need exceptions to reflection, it means the data model is bad.

[alandefreitas]

Also, since we touched on this topic, I think we ended up forgetting about the lazy DOM object directly based on reflection. That could make things much faster.

[gennaroprota]

Please check the new approach. As it concerns building DOM objects lazily, I opened an issue: #1211.

[alandefreitas]

Please check the new approach

What is it?

[gennaroprota]

Please check the new approach

What is it?

It adds new members to RecordSymbol (specifically, IsSpecialization, Specializations and DeductionGuides) and FunctionSymbol (IsSpecialization, Specializations), listing them in their MRDOCS_DESCRIBE_STRUCT invocations, so reflection picks them up everywhere. A new SpecializationFinalizer appends the specialization IDs to the primary's Specializations, sets IsSpecialization=true on specializations, and likewise appends each deduction guide ID to the deduced record's DeductionGuides. This is for each regular specialization whose primary is also regular. "Orphan specializations", i.e. specializations whose primary is excluded from extraction, keep IsSpecialization=false and, thus, stay in the parent scope listing, as before.

Of course, the bespoke (! :-)) tag_invoke overloads on RecordSymbol and FunctionSymbol, and the lazy inverse-index in DomCorpus, are gone.