docs: document advanced callback features

Docs/pages/advanced-features/01-advanced-callback-features.md

@@ -0,0 +1,51 @@
+# Advanced callback features
+
+## Conditional callbacks
+
+Execute callbacks conditionally based on the zero-based invocation counter using `.When()`:
+
+```csharp
+sut.SetupMock.Method.Dispense(It.Is("Dark"), It.IsAny<int>())
+    .Do(() => Console.WriteLine("Called!"))
+    .When(count => count >= 2);  // The first two calls are skipped
+```
+
+## Frequency control
+
+Control how many times a callback executes:
+
+```csharp
+// Execute up to 3 times
+sut.SetupMock.Method.Dispense(It.IsAny<string>(), It.IsAny<int>())
+    .Do(() => Console.WriteLine("Up to 3 times"))
+    .Only(3);
+
+// Executes the callback only once
+sut.SetupMock.Method.Dispense(It.IsAny<string>(), It.IsAny<int>())
+    .Do(() => Console.WriteLine("Only once"))
+    .OnlyOnce();
+```
+
+## Parallel callbacks
+
+When you specify multiple callbacks, they are executed sequentially by default. You can change this behavior to always
+run specific callbacks in parallel using `.InParallel()`:
+
+```csharp
+sut.SetupMock.Method.Dispense(It.IsAny<string>(), It.IsAny<int>())
+    .Do(() => { Console.WriteLine("Runs every second iteration"); })
+    .Do(() => { Console.WriteLine("Runs always in parallel"); }).InParallel()
+    .Do(() => { Console.WriteLine("Runs every other iteration"); });
+```
+
+## Invocation counter
+
+Access the zero-based invocation counter in callbacks:
+
+```csharp
+sut.SetupMock.Method.Dispense(It.IsAny<string>(), It.IsAny<int>())
+    .Do((count, _, _) => Console.WriteLine($"Call #{count}"));
+
+sut.SetupMock.Property.TotalDispensed.OnGet
+	.Do((count, value) => Console.WriteLine($"Read #{count}, value: {value}"));
+```

Docs/pages/advanced-features/_category_.json

@@ -1,5 +1,6 @@
 {
 	"label": "Advanced Features",
+	"collapsed": false,
 	"position": 5,
 	"link": {
 		"type": "generated-index"

Docs/pages/special-types/_category_.json

@@ -1,5 +1,6 @@
 {
 	"label": "Special Types",
+	"collapsed": false,
 	"position": 6,
 	"link": {
 		"type": "generated-index"

README.md

@@ -521,6 +521,60 @@ If the order is incorrect or a call is missing, a `MockVerificationException` wi
    This is useful for ensuring that your test setup and test execution match.
    If any setup was not used, this method returns `false`.
 
+## Advanced Features
+
+### Advanced callback features
+
+#### Conditional callbacks
+
+Execute callbacks conditionally based on the zero-based invocation counter using `.When()`:
+
+```csharp
+sut.SetupMock.Method.Dispense(It.Is("Dark"), It.IsAny<int>())
+    .Do(() => Console.WriteLine("Called!"))
+    .When(count => count >= 2);  // The first two calls are skipped
+```
+
+#### Frequency control
+
+Control how many times a callback executes:
+
+```csharp
+// Execute up to 3 times
+sut.SetupMock.Method.Dispense(It.IsAny<string>(), It.IsAny<int>())
+    .Do(() => Console.WriteLine("Up to 3 times"))
+    .Only(3);
+
+// Executes the callback only once
+sut.SetupMock.Method.Dispense(It.IsAny<string>(), It.IsAny<int>())
+    .Do(() => Console.WriteLine("Only once"))
+    .OnlyOnce();
+```
+
+#### Parallel callbacks
+
+When you specify multiple callbacks, they are executed sequentially by default. You can change this behavior to always
+run specific callbacks in parallel using `.InParallel()`:
+
+```csharp
+sut.SetupMock.Method.Dispense(It.IsAny<string>(), It.IsAny<int>())
+    .Do(() => { Console.WriteLine("Runs every second iteration"); })
+    .Do(() => { Console.WriteLine("Runs always in parallel"); }).InParallel()
+    .Do(() => { Console.WriteLine("Runs every other iteration"); });
+```
+
+#### Invocation counter
+
+Access the zero-based invocation counter in callbacks:
+
+```csharp
+sut.SetupMock.Method.Dispense(It.IsAny<string>(), It.IsAny<int>())
+    .Do((count, _, _) => Console.WriteLine($"Call #{count}"));
+
+sut.SetupMock.Property.TotalDispensed.OnGet
+	.Do((count, value) => Console.WriteLine($"Read #{count}, value: {value}"));
+```
+
 ## Special Types
 
 ### HttpClient