feat: add function object support by gennaroprota · Pull Request #1163 · cppalliance/mrdocs

gennaroprota · 2026-03-03T10:17:41Z

Edit: This description is now obsolete. Please refer to the commit messages for up to date info.

This PR adds detection of constexpr variables whose type is a record providing only operator() overloads, and documents them as callable objects in the Functions tranche. The type of the variable is hidden as implementation-defined, and breadcrumbs render in f() style for readability, but operator() signatures remain fully visible in the variable synopsis and each overload gets its own detail page---preserving the fact that the callable is a function object, not an ordinary function.

Detection triggers:

Auto-detection (on by default, controlled by auto-function-objects) for records whose only public non-special members are operator() overloads, including class templates when the variable lives in an enclosing scope of the type.
The @function_object documentation command for cases that fail auto-detection (e.g. types with extra members).

Key implementation details:

FunctionObjectFinalizer runs before OverloadsFinalizer: hides the type of the variable, restores operator() to Regular extraction, re-parents overloads under the variable, and appends a fixed disclaimer note.
VariableSymbol gains FunctionObjectOverloads and satisfies the SymbolParent concept, so MultiPageVisitor generates detail pages for each operator() overload.
Handlebars templates render linked operator() signatures in the variable synopsis with "» more..." links to the detail pages.

Closes #564.

github-actions · 2026-03-03T10:18:03Z

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

✨ Highlights

🧪 Existing golden tests changed (behavior likely shifted)

🧾 Changes by Scope

Scope	Lines Δ	Lines +	Lines -	Files Δ	Files +	Files ~	Files ↔	Files -
🥇 Golden Tests	5962	5880	82	20	17	3	-	-
🛠️ Source	896	823	73	16	2	14	-	-
🧪 Unit Tests	507	507	-	2	2	-	-	-
📄 Docs	16	16	-	2	-	2	-	-
Total	7381	7226	155	40	21	19	-	-

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

🔝 Top Files

test-files/golden-tests/symbols/variable/function-objects.html (Golden Tests): 1592 lines Δ (+1592 / -0)
test-files/golden-tests/symbols/variable/function-objects.xml (Golden Tests): 1355 lines Δ (+1355 / -0)
test-files/golden-tests/symbols/variable/function-objects.adoc (Golden Tests): 1303 lines Δ (+1303 / -0)

Generated by 🚫 dangerJS against 0b823a0

cppalliance-bot · 2026-03-03T10:27:07Z

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

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

2026-03-05 15:57:23 UTC

codecov · 2026-03-03T10:33:10Z

Codecov Report

❌ Patch coverage is 90.50633% with 45 lines in your changes missing coverage. Please review.
✅ Project coverage is 76.69%. Comparing base (a1f9a82) to head (0b823a0).

Files with missing lines	Patch %	Lines
...ib/Metadata/Finalizers/FunctionObjectFinalizer.cpp	78.40%	8 Missing and 30 partials ⚠️
src/lib/Metadata/Symbol/Function.cpp	94.11%	0 Missing and 3 partials ⚠️
src/lib/AST/ExtractDocComment.cpp	81.81%	0 Missing and 2 partials ⚠️
include/mrdocs/Metadata/DocComment.hpp	0.00%	1 Missing ⚠️
src/lib/Support/Reflection/Reflection.hpp	0.00%	1 Missing ⚠️

Additional details and impacted files

@@             Coverage Diff             @@
##           develop    #1163      +/-   ##
===========================================
+ Coverage    76.38%   76.69%   +0.31%     
===========================================
  Files          311      314       +3     
  Lines        29672    30117     +445     
  Branches      5863     5949      +86     
===========================================
+ Hits         22664    23098     +434     
+ Misses        4735     4720      -15     
- Partials      2273     2299      +26

☔ 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 · 2026-03-03T16:24:16Z

How does this solution relate to the proposals in #564? 🙂

(btw, #564 is from Apr 10, 2024 - it's an investigation that took a long time - not 2026 AI slop 😂)

Edit: nevermind. I think I already got it. :)

alandefreitas

Isn't "functors" formal enough to be used here? It would be a much shorter command and a more concise way to describe it over and over again without needing a "_".

The fixtures should go to better directories, though. Maybe the directories need better documentation, but you can see they shouldn't go there by comparing with the siblings (and you'll see it's definitely not "core", which is used for really core functionality that's not optional). Symbol types and their features are tested in the symbols directory for each symbol. And since there's an option involved, every new option should be tested in the options directory. Then we have new features for variables that should be tested. Then we have a new field in variables, and that's not reflected there. Then we have a folder for javadoc commands that should be tested, and we need a test there because we introduced a new command.

The test cases in symbols/variable should also explore what happens when there is non-conflicting type information, but the variable is forced to be treated as a function object anyway. There are real-world patterns like this. Another pattern we see very often is the combination of template parameters and arguments: impl function with template, different variables with the same function but different params, and so on.

In the existing test, I'm not sure I understand the mechanism through which it goes to the list of functions in the interface. I'm not sure if cppalliance does that or shows it as a separate kind of entity. Because they do behave differently. All niebloids also have a special banner describing how that function works differently. Another thing to explore is how all of that works when one is visible, and the other is an implementation detail, and so on. Another thing to test and design is what happens when documentation goes on the other symbol.

In the output of the existing test, all functors look wrong. They look nothing like niebloids in cppreference. Many of them look arbitrary and not like valid C++ syntax at all. For instance, it tends to look like:

bool single_overload();

(not very different from an overload set with the main function name replaced from operator() to the variable name and with const removed).

rather than:

constexpr /* implementation-defined */ single_overload = {};

bool
operator()() const;

One more thing missing is the presentation of this feature on the landing page. The snippets on the landing page are meant to showcase features that only Mrdocs can support, and this is definitely one of them.

Good work here overall, though. This is a big design decision.

alandefreitas · 2026-03-03T16:44:47Z

include/mrdocs/Metadata/Symbol/Variable.hpp


+    /** Whether this variable is a function object.
+
+        A function object variable is a constexpr variable whose type


I know I'm nitpicking, but I don't think it has to be constexpr.

alandefreitas · 2026-03-03T16:47:16Z

share/mrdocs/addons/generator/common/partials/symbol/qualified-name-text.hbs

 {{~/if~}}
-{{~#if name ~}}
+{{~#if parent.isFunctionObject ~}}
+()


If functions don't have "()" as part of their qualified name, why should function objects have it?

Hmm, right. I always use "()" after function names, but MrDocs doesn't.

alandefreitas · 2026-03-03T16:53:29Z

include/mrdocs/Metadata/Symbol/Variable.hpp

+        the variable is documented as a callable, and its type is hidden
+        as implementation-defined.
+    */
+    bool IsFunctionObject = false;


Mmmm... I often got the recommendation to use a single bool IsFunctionObject in the variable, rather than creating a new symbol type for that. That is valid, but it's not anything but simple. For instance,

How do I know if something is only the "impl" of a function object? Does it also get a boolean?

And if I don't, how do I remove it from indices in the end?

And how do we ensure the generator doesn't generate a page for them?

And since function objects have a completely different way of being presented to the user, will we create a new template with ways of presenting them to the user that look more like functions (signature templates, etc), or will we sprinkle a lot of if/else throughout the templates?

How do we get the impl object from the variable?

If we don't, how do we render information from the impl object in the variable page if we have to? That could happen very often.

I'll probably get some of these answers as I review the PR, but I'm leaving them here so I don't lose context.

alandefreitas · 2026-03-03T16:59:32Z

include/mrdocs/Metadata/Symbol/Variable.hpp

+auto&
+allMembers(VariableSymbol const& T)
+{
+    return T.FunctionObjectOverloads;


So the overloads are both members of the impl object and the variable? Is there a mechanism to ensure visitors don't go through them twice?

Yes. The operator() functions are removed from the record's interface and re-parented under the variable. So visitors won't encounter them twice.

alandefreitas · 2026-03-03T17:00:54Z

share/mrdocs/addons/generator/common/partials/symbol/qualified-name-title.hbs

 --}}
 {{~#if (and parent parent.parent)~}}
-{{~> symbol/qualified-name-title parent is-qualified-name-parent=true ~}}{{#if parent.name }}::{{/if}}
+{{~> symbol/qualified-name-title parent is-qualified-name-parent=true ~}}{{#if parent.name }}{{~#unless parent.isFunctionObject~}}::{{~/unless~}}{{/if}}


There's something wrong with this pattern. Functions work without it. My intuition and the PR is forcing this template to do something is was not meant to do. qualified names in the standard don't include ()

alandefreitas · 2026-03-03T17:15:28Z

src/lib/Metadata/Finalizers/FunctionObjectFinalizer.cpp

+// constructor, copy/move assignment operator, or destructor
+// ([special]).
+bool
+isSpecialMemberFunction(


Same thing. I just remember doing this somewhere already.

Aha. I think you mean the code in DocComment/Function.hpp. I see some issues with that:

It doesn't handle default constructors with all-default parameters (only no parameters).

It doesn't handle by-value copy assignment.

It doesn't check for non-template.

I could fix these issues and re-use it. Should we extract those helpers (which are currently in an unnamed namespace) to a shared location? (BTW, unnamed namespaces in include files are bad! :-))

Yes. I think so. Whatever you think is best, though. You understand the problem much better than I do. :)

alandefreitas · 2026-03-03T17:32:05Z

src/lib/Metadata/Finalizers/FunctionObjectFinalizer.cpp

+FunctionObjectFinalizer::
+markImplementationDefined(RecordSymbol& R)
+{
+    R.Extraction = ExtractionMode::ImplementationDefined;


Oh... This answers one of my questions above. Good strategy :)

alandefreitas · 2026-03-03T17:32:54Z

src/lib/Metadata/Finalizers/FunctionObjectFinalizer.cpp

+markImplementationDefined(RecordSymbol& R)
+{
+    R.Extraction = ExtractionMode::ImplementationDefined;
+    for (SymbolID const& childId : allMembers(R.Interface))


What about potentially deeper levels?

Yup, fixed :-).

alandefreitas · 2026-03-03T17:38:47Z

src/lib/Metadata/Symbol/Variable.cpp

 }

 void
 merge(VariableSymbol& I, VariableSymbol&& Other)


All these merge functions could use some reflection. That's one of the strongest use cases. I don't know if this should be incremental or in a single issue though.

src/lib/Support/Reflection/Reflection.hpp

Variables with a type that is a record whose only public non-special members are operator() overloads are now documented as functions. For each operator() overload, the finalizer creates a synthetic FunctionSymbol that carries the variable name and parent but the operator signature, return type, and source location. The original variable and its type are hidden as implementation-defined. Detection triggers: - Auto-detection (on by default, controlled by `auto-function-objects`) for records whose only public non-special members are operator() overloads, including class templates when the variable lives in an enclosing scope of the type. - The `@functionobject` (or `@functor`) doc command for cases that fail auto-detection (e.g. types with extra public members) or when auto-detection is off. Key implementation details: - FunctionObjectFinalizer runs early in the pipeline (before OverloadsFinalizer). It creates synthetic FunctionSymbol entries, hides the variable and its type, and appends a fixed disclaimer note about ADL and address-taking. - FunctionSymbol gains an optional FunctionObjectImpl field that links each synthetic function back to the operator() it models. An example of this feature is added to the landing page. Closes cppalliance#564.

This moves isSpecialMemberFunction() out of FunctionObjectFinalizer's unnamed namespace into Function.hpp/cpp as a shared API, and introduces individual helpers (isDefaultConstructor(), isCopyConstructor(), isMoveConstructor(), isCopyAssignment(), isMoveAssignment())---isSpecialMemberFunction() becomes a composition of these individual helpers. Contextually, this fixes three bugs in the existing detection logic in DocComment/Function.hpp: - Default constructors with all-default parameters were not recognized (only empty parameter lists were handled). - Default constructors with parameter packs were not recognized. - By-value copy assignment operator=(X) was not recognized.

gennaroprota force-pushed the feat/function_object_support branch from 19d7451 to e9b70af Compare March 3, 2026 15:56

alandefreitas reviewed Mar 3, 2026

View reviewed changes

gennaroprota force-pushed the feat/function_object_support branch 7 times, most recently from 92be269 to 2799c42 Compare March 5, 2026 11:25

gennaroprota added 2 commits March 5, 2026 16:36

gennaroprota force-pushed the feat/function_object_support branch from 2799c42 to 0b823a0 Compare March 5, 2026 15:47


		/** Whether this variable is a function object.

		A function object variable is a constexpr variable whose type

Conversation

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

Uh oh!

Uh oh!

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

Uh oh!

✨ Highlights

🧾 Changes by Scope

🔝 Top Files

Uh oh!

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

Uh oh!

Uh oh!

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

Uh oh!

Codecov Report

Uh oh!

alandefreitas commented Mar 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

alandefreitas left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

gennaroprota commented Mar 3, 2026 •

edited

Loading

github-actions bot commented Mar 3, 2026 •

edited

Loading

cppalliance-bot commented Mar 3, 2026 •

edited

Loading

codecov bot commented Mar 3, 2026 •

edited

Loading

alandefreitas commented Mar 3, 2026 •

edited

Loading