feat: add $meta.type and $meta.bases to all DOM objects #1153

gennaroprota · 2026-01-23T15:55:35Z

Closes issue #1148.

github-actions · 2026-01-23T15:56:01Z

🚧 Danger.js checks for MrDocs are experimental; expect some rough edges while we tune the rules.

⚠️ Warnings

Warning

PR description looks empty. Please add a short rationale and testing notes.

Warning

Source changed but no tests or fixtures were updated.

🧾 Changes by Scope

Scope	Lines Δ	Lines +	Lines -	Files Δ	Files +	Files ~	Files ↔	Files -
🛠️ Source	250	193	57	9	-	9	-	-
Total	250	193	57	9	-	9	-	-

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

🔝 Top Files

src/lib/Support/Reflection/MapReflectedType.hpp (Source): 181 lines Δ (+152 / -29)
src/lib/Support/Reflection/Reflection.cpp (Source): 39 lines Δ (+24 / -15)
share/mrdocs/addons/generator/common/partials/symbol/signature/function.hbs (Source): 10 lines Δ (+5 / -5)

Generated by 🚫 dangerJS against 12c2666

cppalliance-bot · 2026-01-23T16:04:07Z

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

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

2026-01-23 17:33:43 UTC

codecov · 2026-01-23T16:23:37Z

Codecov Report

❌ Patch coverage is 93.02326% with 3 lines in your changes missing coverage. Please review.
✅ Project coverage is 86.48%. Comparing base (086becc) to head (44b7447).

Files with missing lines	Patch %	Lines
src/lib/Support/Reflection/MapReflectedType.hpp	90.00%	2 Missing ⚠️
src/lib/Support/Reflection/Reflection.cpp	94.11%	1 Missing ⚠️

Additional details and impacted files

@@             Coverage Diff             @@
##           develop    #1153      +/-   ##
===========================================
- Coverage    86.49%   86.48%   -0.01%     
===========================================
  Files          326      326              
  Lines        23828    23839      +11     
===========================================
+ Hits         20609    20618       +9     
- Misses        3219     3221       +2

☔ 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.

alandefreitas

LGTM :)

What was the process to get to this _meta key?

alandefreitas · 2026-01-23T17:59:03Z

src/lib/Support/Reflection/MapReflectedType.hpp

+*/
+template <typename T>
+constexpr std::string_view
+readableTypeName()


Isn't this information already boost described?

AFAICS, Boost.Describe cannot provide the type name. However, we could use Boost.Core:

template <typename T> std::string readableTypeName() { return std::string(removeNamespaceQualifiers(boost::core::type_name<T>())); }

Is Boost.Core already available?

No, we'd have to add the (private) dependency.

alandefreitas · 2026-01-23T18:01:16Z

src/lib/Support/Reflection/MapReflectedType.hpp

    DomCorpus const* domCorpus)
 {
+    // Add _meta only for the most-derived type.
+    if constexpr (isMostDerived)


Oh... I never thought about this problem. There are some cases where the templates are worried about the base class. For instance, some fields return whether something is a symbol, and the templates often query that, but the derived class would just be a record, a function or something like that. I don't know what the best solution for that would be. Maybe we just include the metadata for the superclass inside the metadata for the class.

Hmm... if there are already templates that do that, why didn't the golden tests fail?

Just to be clear we're not misunderstanting each other, what I meant in practice is that templates often need to do something like {{#if (eq symbol.type "symbol")}}do this{{ else if (eq symbol.type "name")}}do that{{else}}error!{{/if}} because we have two ways to talk about identifiers (Symbol and Name) and we want the template to work for both of them.

https://github.com/cppalliance/mrdocs/blob/develop/include/mrdocs/Metadata/Symbol.hpp

https://github.com/cppalliance/mrdocs/blob/develop/include/mrdocs/Metadata/Name.hpp

So the problem is the current model doesn't give us the parent class. So both conditions would return false here and we would get into error. I don't know about how to fix that. But only representing the most derived type would fail.

Hmm... if there are already templates that do that, why didn't the golden tests fail?

Because the previous code wasn't broken and the new code is not relying on $meta for this distinction yet? So it's still using the previous workaround, which doesn't need $meta. Probably the type is represented with "type" and the parent type is represented with "kind" or something. Whatever the describe function does for Symbol and Name.

gennaroprota · 2026-01-26T15:14:58Z

LGTM :)

What was the process to get to this _meta key?

You mean what led to choosing the underscore as prefix?

alandefreitas · 2026-01-26T16:54:48Z

You mean what led to choosing the underscore as prefix?

I mean the whole thing. This combination of prefix + keyword. Did we compare it with existing practices for that anywhere? Or the set of valid chars that could go there? Getting this convention wrong now could be annoying later.

gennaroprota · 2026-01-26T17:10:13Z

You mean what led to choosing the underscore as prefix?

I mean the whole thing. This combination of prefix + keyword. Did we compare it with existing practices for that anywhere? Or the set of valid chars that could go there? Getting this convention wrong now could be annoying later.

I was going with @meta, which you suggested, but @ is not allowed. So I considered a different prefix. It didn't seem something to spend too much time on (maybe I'm wrong), so I considered $ and _, and quickly chose the latter (which I like more, maybe because I use C++ more than PHP :-)).

_meta also mirrors the OData v2/v3 __metadata convention, which was specifically designed for the same purpose: storing entity metadata alongside properties.

This enables the Handlebars templates to identify object types and base classes at runtime. The '$' prefix follows the JSON Schema conventions for system metadata. Closes issue cppalliance#1148.

We renamed some members into different Handlebars key names. But there's no particular reason to do that. So we switch to use the canonical names everywhere.

gennaroprota marked this pull request as draft January 23, 2026 16:50

gennaroprota marked this pull request as ready for review January 23, 2026 17:22

alandefreitas reviewed Jan 23, 2026

View reviewed changes

gennaroprota force-pushed the feat/add_meta_key_to_all_dom_objects branch 2 times, most recently from 97424a4 to bcda061 Compare January 26, 2026 18:33

gennaroprota changed the title ~~feat: add a _meta key to all DOM objects for type identification~~ feat: add $meta.type to all DOM objects Jan 26, 2026

gennaroprota marked this pull request as draft January 26, 2026 18:35

gennaroprota force-pushed the feat/add_meta_key_to_all_dom_objects branch 4 times, most recently from 44b7447 to 2b8e5c1 Compare January 27, 2026 11:46

gennaroprota added 2 commits January 27, 2026 12:49

feat: add $meta.type and $meta.bases to all DOM objects

cbdc760

This enables the Handlebars templates to identify object types and base classes at runtime. The '$' prefix follows the JSON Schema conventions for system metadata. Closes issue cppalliance#1148.

fix: remove all special name re-mappings for Handlebars

12c2666

We renamed some members into different Handlebars key names. But there's no particular reason to do that. So we switch to use the canonical names everywhere.

gennaroprota force-pushed the feat/add_meta_key_to_all_dom_objects branch from 2b8e5c1 to 12c2666 Compare January 27, 2026 11:50

gennaroprota changed the title ~~feat: add $meta.type to all DOM objects~~ feat: add $meta.type and $meta.bases to all DOM objects Jan 27, 2026

feat: add $meta.type and $meta.bases to all DOM objects #1153

Are you sure you want to change the base?

feat: add $meta.type and $meta.bases to all DOM objects #1153

Uh oh!

Conversation

gennaroprota commented Jan 23, 2026

Uh oh!

github-actions bot commented Jan 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

⚠️ Warnings

🧾 Changes by Scope

🔝 Top Files

Uh oh!

cppalliance-bot commented Jan 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

codecov bot commented Jan 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

alandefreitas left a comment

Choose a reason for hiding this comment

Uh oh!

alandefreitas Jan 23, 2026

Choose a reason for hiding this comment

Uh oh!

gennaroprota Jan 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

alandefreitas Jan 26, 2026

Choose a reason for hiding this comment

Uh oh!

gennaroprota Jan 26, 2026

Choose a reason for hiding this comment

Uh oh!

alandefreitas Jan 23, 2026

Choose a reason for hiding this comment

Uh oh!

gennaroprota Jan 26, 2026

Choose a reason for hiding this comment

Uh oh!

alandefreitas Jan 26, 2026

Choose a reason for hiding this comment

Uh oh!

gennaroprota commented Jan 26, 2026

Uh oh!

alandefreitas commented Jan 26, 2026

Uh oh!

gennaroprota commented Jan 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

github-actions bot commented Jan 23, 2026 •

edited

Loading

cppalliance-bot commented Jan 23, 2026 •

edited

Loading

codecov bot commented Jan 23, 2026 •

edited

Loading

gennaroprota Jan 26, 2026 •

edited

Loading

gennaroprota commented Jan 26, 2026 •

edited

Loading