feat: add function object support

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 #564.

Author: gennaroprota

docs/mrdocs.schema.json

@@ -36,6 +36,16 @@
       "title": "Automatically provide missing documentation for special functions and trivial metadata",
       "type": "boolean"
     },
+    "auto-function-objects": {
+      "default": true,
+      "description": "When true, MrDocs automatically detects function objects: constexpr variables whose type is a struct or class whose only public non-special members are operator() overloads. Set to false to disable auto-detection and rely solely on the @functionobject doc command.",
+      "enum": [
+        true,
+        false
+      ],
+      "title": "Automatically detect function objects",
+      "type": "boolean"
+    },
     "auto-relates": {
       "default": true,
       "description": "When set to `true`, Mr.Docs automatically finds non-member functions that are related to the current class.",

docs/website/data.json

@@ -106,6 +106,12 @@
       "source": "sqrt.cpp",
       "imageClass": "writing",
       "boxClass": "box3 box-shape3 box270"
+    },
+    {
+      "description": "Function objects are documented as callable entities—operator() signatures appear directly on the variable.",
+      "source": "function_object.cpp",
+      "imageClass": "pointing",
+      "boxClass": "box3 box-shape1 box0"
     }
   ]
 }

docs/website/snippets/function_object.cpp

@@ -0,0 +1,13 @@
+struct abs_fn
+{
+    /** Compute the absolute value.
+
+        @param x The input value.
+        @return The absolute value of x.
+    */
+    double
+    operator()(double x) const noexcept;
+};
+
+/** Return the absolute value of a number. */
+constexpr abs_fn abs = {};

include/mrdocs/Metadata/DocComment.hpp

@@ -6,6 +6,7 @@
 //
 // Copyright (c) 2023 Vinnie Falco (vinnie.falco@gmail.com)
 // Copyright (c) 2023 Krystian Stasiowski (sdkrystian@gmail.com)
+// Copyright (c) 2026 Gennaro Prota (gennaro.prota@gmail.com)
 //
 // Official repository: https://github.com/cppalliance/mrdocs
 //
@@ -106,6 +107,9 @@ struct MRDOCS_DECL DocComment {
     */
     std::vector<doc::ReferenceInline> related;
 
+    /// True if the @functionobject (or @functor) command was used on this symbol.
+    bool IsFunctionObject = false;
+
     /** Constructor.
     */
     MRDOCS_DECL
@@ -171,6 +175,10 @@ struct MRDOCS_DECL DocComment {
 inline
 void merge(DocComment& I, DocComment&& other)
 {
+    // Merge the function-object flag before comparing so
+    // the flag alone doesn't cause spurious inequality.
+    I.IsFunctionObject |= other.IsFunctionObject;
+
     // FIXME: this doesn't merge parameter information;
     // parameters with the same name but different directions
     // or descriptions end up being duplicated

include/mrdocs/Metadata/Symbol/Function.hpp

@@ -128,6 +128,14 @@ struct FunctionSymbol final
     */
     ExplicitInfo Explicit;
 
+    /** Back-reference to the function object implementation type.
+
+        When set, this function was synthesized from a function
+        object variable: the function does not participate in ADL
+        and taking its address is undefined behavior.
+    */
+    Optional<SymbolID> FunctionObjectImpl;
+
     //--------------------------------------------
 
     /** Construct a function symbol with its ID.

include/mrdocs/Metadata/Symbol/SymbolID.hpp

@@ -207,6 +207,26 @@ tag_invoke(
     SymbolID const& id,
     DomCorpus const* domCorpus);
 
+/** Convert an optional SymbolID to dom::Value or null.
+*/
+inline
+void
+tag_invoke(
+    dom::ValueFromTag,
+    dom::Value& v,
+    Optional<SymbolID> const& id,
+    DomCorpus const* domCorpus)
+{
+    if (!id)
+    {
+        v = nullptr;
+    }
+    else
+    {
+        tag_invoke(dom::ValueFromTag{}, v, *id, domCorpus);
+    }
+}
+
 /** Convert SymbolID pointers to dom::Value or null.
 
     @param v The output parameter to receive the dom::Value.

include/mrdocs/Metadata/Symbol/Variable.hpp

@@ -5,6 +5,7 @@
 //
 // Copyright (c) 2023 Vinnie Falco (vinnie.falco@gmail.com)
 // Copyright (c) 2023 Krystian Stasiowski (sdkrystian@gmail.com)
+// Copyright (c) 2026 Gennaro Prota (gennaro.prota@gmail.com)
 //
 // Official repository: https://github.com/cppalliance/mrdocs
 //

src/lib/AST/ASTVisitor.cpp

@@ -7,6 +7,7 @@
 // Copyright (c) 2023 Vinnie Falco (vinnie.falco@gmail.com)
 // Copyright (c) 2023 Krystian Stasiowski (sdkrystian@gmail.com)
 // Copyright (c) 2024 Alan de Freitas (alandefreitas@gmail.com)
+// Copyright (c) 2026 Gennaro Prota (gennaro.prota@gmail.com)
 //
 // Official repository: https://github.com/cppalliance/mrdocs
 //
@@ -22,6 +23,7 @@
 #include <lib/Support/Radix.hpp>
 #include <mrdocs/Metadata.hpp>
 #include <mrdocs/Support/Algorithm.hpp>
+#include <mrdocs/Support/Assert.hpp>
 #include <mrdocs/Support/ScopeExit.hpp>
 #include <clang/AST/AST.h>
 #include <clang/AST/Attr.h>

src/lib/AST/ASTVisitor.hpp

@@ -7,6 +7,7 @@
 // Copyright (c) 2023 Vinnie Falco (vinnie.falco@gmail.com)
 // Copyright (c) 2023 Krystian Stasiowski (sdkrystian@gmail.com)
 // Copyright (c) 2024 Alan de Freitas (alandefreitas@gmail.com)
+// Copyright (c) 2026 Gennaro Prota (gennaro.prota@gmail.com)
 //
 // Official repository: https://github.com/cppalliance/mrdocs
 //

src/lib/AST/ExtractDocComment.cpp

@@ -98,6 +98,28 @@ dumpCommentContent(
 namespace mrdocs {
 namespace {
 
+// -------- Custom doc commands that set a boolean flag
+
+/** Entry for a custom block command that sets a boolean flag
+    on DocComment and processes its paragraph content.
+
+    To add a new custom flag command, add an entry to the
+    customFlagCommands array below: both registration and
+    handling are driven from this single table.
+*/
+struct CustomFlagCommand
+{
+    char const* name;
+    bool DocComment::* flag;
+};
+
+constexpr CustomFlagCommand customFlagCommands[] = {
+    {"functionobject", &DocComment::IsFunctionObject},
+    // "functionobject", without an underscore, isn't particularly
+    // readable, so provide "functor" as an alternative.
+    {"functor",        &DocComment::IsFunctionObject},
+};
+
 // -------- Small helpers
 
 static std::string
@@ -1004,6 +1026,23 @@ class DocCommentVisitor
             MRDOCS_UNREACHABLE();
 
         default:
+            // Custom flag commands registered at runtime:
+            // set the corresponding flag and preserve any
+            // paragraph text in the doc comment.
+            for (auto const& custom : customFlagCommands)
+            {
+                if (llvm::StringRef(cmd->Name) == custom.name)
+                {
+                    jd_.*(custom.flag) = true;
+                    auto p = parseBlock(
+                        std::in_place_type<doc::ParagraphBlock>);
+                    if (!p.children.empty())
+                    {
+                        jd_.Document.emplace_back(std::move(p));
+                    }
+                    return;
+                }
+            }
             // unsupported → ignore
             return;
         }
@@ -1157,8 +1196,11 @@ class DocCommentVisitor
 void
 initCustomCommentCommands(clang::ASTContext& context)
 {
-    (void) context;
-    // Reserved for future custom commands registration.
+    auto& traits = context.getCommentCommandTraits();
+    for (auto const& cmd : customFlagCommands)
+    {
+        traits.registerBlockCommand(cmd.name);
+    }
 }
 
 void