docs: document advanced paramter matching features

Docs/pages/setup/01-properties.md

@@ -0,0 +1,33 @@
+# Properties
+
+Set up property getters and setters to control or verify property access on your mocks.
+
+**Initialization**
+
+You can initialize properties so they work like normal properties (setter changes the value, getter returns the last set
+value):
+
+```csharp
+sut.SetupMock.Property.TotalDispensed.InitializeWith(42);
+```
+
+**Returns / Throws**
+
+Alternatively, set up properties with `Returns` and `Throws` (supports sequences):
+
+```csharp
+sut.SetupMock.Property.TotalDispensed
+    .Returns(1)
+    .Returns(2)
+    .Throws(new Exception("Error"))
+    .Returns(4);
+```
+
+**Callbacks**
+
+Register callbacks on the setter or getter:
+
+```csharp
+sut.SetupMock.Property.TotalDispensed.OnGet.Do(() => Console.WriteLine("TotalDispensed was read!"));
+sut.SetupMock.Property.TotalDispensed.OnSet.Do((oldValue, newValue) => Console.WriteLine($"Changed from {oldValue} to {newValue}!") );
+```

Docs/pages/setup/02-methods.md

@@ -0,0 +1,46 @@
+# Methods
+
+Use `mock.SetupMock.Method.MethodName(…)` to set up methods. You can specify argument matchers for each parameter.
+
+```csharp
+// Setup Dispense to decrease stock and raise event
+sut.SetupMock.Method.Dispense(It.Is("Dark"), It.IsAny<int>())
+    .Returns((type, amount) =>
+    {
+        var current = sut[type];
+        if (current >= amount)
+        {
+            sut[type] = current - amount;
+            sut.RaiseOnMock.ChocolateDispensed(type, amount);
+            return true;
+        }
+        return false;
+    });
+
+// Setup method with callback
+sut.SetupMock.Method.Dispense(It.Is("White"), It.IsAny<int>())
+    .Do((type, amount) => Console.WriteLine($"Dispensed {amount} {type} chocolate."));
+
+// Setup method to throw
+sut.SetupMock.Method.Dispense(It.Is("Green"), It.IsAny<int>())
+    .Throws<InvalidChocolateException>();
+```
+
+- Use `.Do(…)` to run code when the method is called. Supports parameterless or parameter callbacks.
+- Use `.Returns(…)` to specify the value to return. You can provide a direct value, a callback, or a callback with
+  parameters.
+- Use `.Throws(…)` to specify an exception to throw. Supports direct exceptions, exception factories, or factories with
+  parameters.
+- Use `.Returns(…)` and `.Throws(…)` repeatedly to define a sequence of return values or exceptions (cycled on each
+  call).
+- Use `.SkippingBaseClass(…)` to override the base class behavior for a specific method (only for class mocks).
+- When you specify overlapping setups, the most recently defined setup takes precedence.
+
+**Async Methods**
+
+For `Task<T>` or `ValueTask<T>` methods, use `.ReturnsAsync(…)`:
+
+```csharp
+sut.SetupMock.Method.DispenseAsync(It.IsAny<string>(), It.IsAny<int>())
+    .ReturnsAsync(true);
+```

Docs/pages/setup/03-indexers.md

@@ -0,0 +1,27 @@
+# Indexers
+
+Set up indexers with argument matchers. Supports initialization, returns/throws sequences, and callbacks.
+
+```csharp
+sut.SetupMock.Indexer(It.IsAny<string>())
+    .InitializeWith(type => 20)
+    .OnGet.Do(type => Console.WriteLine($"Stock for {type} was read"));
+
+sut.SetupMock.Indexer(It.Is("Dark"))
+    .InitializeWith(10)
+    .OnSet.Do((value, type) => Console.WriteLine($"Set [{type}] to {value}"));
+```
+
+- `.InitializeWith(…)` can take a value or a callback with parameters.
+- `.Returns(…)` and `.Throws(…)` support direct values, callbacks, and callbacks with parameters and/or the current
+  value.
+- `.OnGet.Do(…)` and `.OnSet.Do(…)` support callbacks with or without parameters.
+- `.Returns(…)` and `.Throws(…)` can be chained to define a sequence of behaviors, which are cycled through on each
+  call.
+- Use `.SkippingBaseClass(…)` to override the base class behavior for a specific indexer (only for class mocks).
+- When you specify overlapping setups, the most recently defined setup takes precedence.
+
+**Note**:
+You can use the same [parameter matching](https://awexpect.com/docs/mockolate/setup/parameter-matching)
+and [interaction](https://awexpect.com/docs/mockolate/setup/parameter-matching#parameter-interaction) options as for
+methods.