--- a/dyncallback/dyncallback.3	Thu Sep 08 16:15:52 2022 +0200
+++ b/dyncallback/dyncallback.3	Thu Sep 08 17:36:20 2022 +0200
@@ -103,7 +103,7 @@
 parameter, meaning it can only be used for callbacks that do not use any
 aggregate by value.
 .Pp
-.Sy NOTE:
+.Em NOTE :
 C++ non-trivial aggregates (check with the std::is_trivial type trait) do not
 use aggregate descriptions, so the respective pointers in the provided array
 must be NULL. See
@@ -159,7 +159,7 @@
 where
 .Ar target
 must point to memory large enough for the aggregate to be copied to,
-.Sy iff
+.Em iff
 the aggregate is trivial (see below for non-trivial C++ aggregates), in which case
 .Ar target
 is returned.
@@ -190,12 +190,19 @@
 point to (implicit, caller-provided) memory where the aggregate should be
 copied to.
 
-.Sh EXAMPLE
-Let's say, we want to create a callback object and call it. For simplicity, this
-example will omit passing it as a function pointer to a function (e.g. compar
-in qsort(), etc.) and demonstrate calling it, directly. First, we need to define
-our callback handler - the following handler illustrates how to access the passed-
-in arguments:
+.Sh EXAMPLES
+.Em Note :
+for simplicity, none of the examples below do any error checking. Also, none of
+them pass the callback object pointer as an argument to a function doing the
+respective callback (e.g.
+.Ar compar
+in
+.Xr qsort 3 ,
+etc.), but demonstrate calling it, directly, for clarity.
+.Pp
+Let's say, we want to create a callback object and call it. First, we need to
+define our callback handler - the following handler illustrates how to access
+the passed-in arguments, optional userdata, and how to return values:
 .Bd -literal -offset indent
 DCsigchar cbHandler(DCCallback* cb,
                     DCArgs*     args,
@@ -216,21 +223,185 @@
 }
 .Ed
 .Pp
-Note that the return value of the handler is a signature character, not the
-actual return value, itself.
-Now, let's call it through a DCCallback object:
+Note that the return value of the handler is a signature character, and not the
+actual return value, itself.  Now, let's call it through a
+.Sy DCCallback
+object:
+.Bd -literal -offset indent
+DCCallback* cb;
+short result = 0;
+int userdata = 1337;
+cb = dcbNewCallback("ifsdl)s", &cbHandler, &userdata);
+
+/* call the callback object */
+result = ((short(*)(int, float, short, double, long long))cb)
+  (123, 23.f, 3, 1.82, 9909ll);
+
+dcbFreeCallback(cb);
+.Ed
+.Ss C/trivial aggregates by-value
+Onto an example calling back a function which takes an aggregate
+.Em "by value"
+(note that this is only available on platforms where macro
+.Dv DC__Feature_AggrByVal
+is defined). E.g. with the following function
+.Fn f
+and
+.Sy struct S :
+.Bd -literal -offset indent
+struct S { char x[3]; double y; };
+int f(struct S, float);
+.Ed
+.Pp
+the callback handler would look like:
+.Bd -literal -offset indent
+DCsigchar cbHandler(DCCallback* cb,
+                    DCArgs*     args,
+                    DCValue*    result,
+                    void*       userdata)
+{
+  struct S arg1;
+  float arg2;
+  dcbArgAggr(args, (DCpointer)&arg1);
+  arg2 = dcbArgFloat(args);
+
+  /* ... */
+
+  result->i = 1;
+  return 'i';
+}
+.Ed
+.Pp
+and the callback object as well as the aggregate field/layout description are
+set up (and the former called back) as follows:
+.Bd -literal -offset indent
+struct S s = { { 56, -23, 0 }, -6.28 };
+int result;
+
+DCCallback* cb;
+
+DCaggr *a = dcNewAggr(2, sizeof(struct S));
+dcAggrField(a, DC_SIGCHAR_CHAR,   offsetof(struct S, x), 3);
+dcAggrField(a, DC_SIGCHAR_DOUBLE, offsetof(struct S, y), 1);
+dcCloseAggr(a);
+
+/* an array of DCaggr* must be passed as last arg, with one
+ * entry per 'A' signature character; we got only one, here
+ */
+cb = dcbNewCallback2("Af)v", &cbHandler, NULL, &a);
+
+/* call the callback object */
+result = ((int(*)(struct S, float))cb)(s, 42.f);
+
+dcbFreeCallback(cb);
+dcFreeAggr(a);
+.Ed
+.Pp
+Let's extend the last example, so that the callback function also returns
+.Sy struct S
+.Em "by value" .
+The struct definition, function declaration and handler definition would be:
 .Bd -literal -offset indent
-  DCCallback* cb;
-  short result = 0;
-  int userdata = 1337;
-  cb = dcbNewCallback("ifsdl)s", &cbHandler, &userdata);
+/* callback function decl */
+struct S f(struct S, float);
+
+struct S { char x[3]; double y; };
+
+DCsigchar cbHandler(DCCallback* cb,
+                    DCArgs*     args,
+                    DCValue*    result,
+                    void*       userdata)
+{
+  struct S arg1, r;
+  float arg2;
+  dcbArgAggr(args, (DCpointer)&arg1);
+  arg2 = dcbArgFloat(args);
+
+  /* ... */
+
+  /* use helper to write aggregate return value to result */
+  dcbReturnAggr(args, result, (DCpointer)&r);
+  return 'A';
+}
+.Ed
+.Pp
+.Pp
+and the callback object as well as the aggregate field/layout descriptions are
+set up (and the former called back) as follows:
+.Bd -literal -offset indent
+struct S s = { { 33, 29, -1 }, 6.8 };
+struct S result;
+
+DCCallback* cb;
+
+DCaggr *a = { dcNewAggr(2, sizeof(struct S)) };
+dcAggrField(a, DC_SIGCHAR_CHAR,   offsetof(struct S, x), 3);
+dcAggrField(a, DC_SIGCHAR_DOUBLE, offsetof(struct S, y), 1);
+dcCloseAggr(a);
+
+/* an array of DCaggr* must be passed as last arg, with one
+ * entry per 'A' signature character
+ */
+cb = dcbNewCallback2("Af)A", &cbHandler, NULL, (DCaggr*[2]){a,a});
+
+/* call the callback object */
+result = ((struct S(*)(struct S, float))cb)(s, 42.f);
 
-  /* call the callback object */
-  result = ((short(*)(int, float, short, double, long long))cb)
-    (123, 23.f, 3, 1.82, 9909ll);
+dcbFreeCallback(cb);
+dcFreeAggr(a);
+.Ed
+.Ss C++
+In our next example, let's look at setting up a
+.Sy DCCallback
+object to call back a simple C++ method (illustrating the need to specify the
+thiscall calling convention). If the class and method is declared as:
+.Bd -literal -offset indent
+class Klass {
+public:
+	virtual void Method(float, int);
+};
+.Ed
+.Pp
+the respective callback handler would be something along the lines of:
+.Bd -literal -offset indent
+DCsigchar cbHandler(DCCallback* cb,
+                    DCArgs*     args,
+                    DCValue*    result,
+                    void*       userdata)
+{
+  Klass*    thisptr = (Klass*)dcbArgPointer(args);
+  float     arg1 = dcbArgFloat(args);
+  int       arg2 = dcbArgInt(args);
+
+  /* ... */
 
-  dcbFreeCallback(cb);
+  return 'v';
+}
 .Ed
+.Pp
+and the callback object would be used as follows:
+.Bd -literal -offset indent
+DCCallback* cb;
+cb = dcbNewCallback("_*pfi)v", &cbHandler, NULL);
+
+/* HACK: this is a hack just for this example to force the compiler
+ * generating a thiscall, below (creates a fake vtable mimicking
+ * Klass, setting all of its possible entries to our callback handler;
+ */
+DCpointer fakeClass[sizeof(Klass)/sizeof(DCpointer)];
+for(int j=0; j<sizeof(Klass)/sizeof(DCpointer); ++j)
+	fakeClass[j] = &cb;
+
+/* (this)call the callback object */
+((Klass*)&fakeClass)->Method(8, 23.f);
+
+dcbFreeCallback(cb);
+.Ed
+.Pp
+.Em NOTE :
+In a real world scenario one would figure out the precise location of the vtable entry of
+.Fn Klass::Method ,
+of course; the above example omits this for simplicity.
 .Sh CONFORMING TO
 The dyncallback library needs at least a c99 compiler with additional support
 for anonymous structs/unions (which were introduced officially in c11). Given