docs: improve method setup documentation

Docs/pages/setup/01-properties.md

@@ -74,7 +74,8 @@ sut.SetupMock.Property.TotalDispensed.OnGet
 
 **Notes:**
 
-- All callbacks support more advanced features like conditional execution, frequency control, parallel execution, and
-  access to the invocation counter.
+- Use `.SkippingBaseClass(…)` to override the base class behavior for a specific property (only for class mocks).
+- AAll callbacks and return values support more advanced features like conditional execution, frequency control,
+  parallel execution, and access to the invocation counter.
   See [Advanced callback features](https://awexpect.com/docs/mockolate/advanced-features/advanced-callback-features)
   for details.

Docs/pages/setup/02-methods.md

@@ -2,6 +2,16 @@
 
 Use `mock.SetupMock.Method.MethodName(…)` to set up methods. You can specify argument matchers for each parameter.
 
+## Returns / Throws
+
+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.
+
+You can call `.Returns(…)` and `.Throws(…)` multiple times to define a sequence of return values or exceptions (cycled
+on each call).
+
 ```csharp
 // Setup Dispense to decrease stock and raise event
 sut.SetupMock.Method.Dispense(It.Is("Dark"), It.IsAny<int>())
@@ -17,32 +27,44 @@ sut.SetupMock.Method.Dispense(It.Is("Dark"), It.IsAny<int>())
         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.
+// Sequence of returns and throws
+sut.SetupMock.Method.Dispense(It.IsAny<string>(), It.IsAny<int>())
+    .Returns(true)
+    .Throws(new Exception("Error"))
+    .Returns(false);
+```
 
-## Async Methods
+### Async Methods
 
-For `Task<T>` or `ValueTask<T>` methods, use `.ReturnsAsync(…)` or `ThrowsAsync(…)`:
+For async methods returning `Task`/`Task<T>` or `ValueTask`/`ValueTask<T>`, use `.ReturnsAsync(…)` or `ThrowsAsync(…)`
+respectively:
 
 ```csharp
 sut.SetupMock.Method.DispenseAsync(It.IsAny<string>(), It.IsAny<int>())
     .ReturnsAsync((_, v) => v)            // First execution returns the value of the `int` parameter
     .ThrowsAsync(new TimeoutException())  // Second execution throws a TimeoutException
     .ReturnsAsync(0).Forever();           // Subsequent executions return 0
 ```
+
+## Callbacks
+
+Use `.Do(…)` to run code when the method is called. Supports parameterless or parameter callbacks.
+
+```csharp
+// Setup method with callback
+sut.SetupMock.Method.Dispense(It.Is("White"), It.IsAny<int>())
+    .Do((type, amount) => Console.WriteLine($"Dispensed {amount} {type} chocolate."));
+```
+
+**Notes:**
+
+- 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.
+- All callbacks and return values support more advanced features like conditional execution, frequency control,
+  parallel execution, and access to the invocation counter.
+  See [Advanced callback features](https://awexpect.com/docs/mockolate/advanced-features/advanced-callback-features)
+  for details.

README.md

@@ -140,8 +140,8 @@ var classMock = Mock.Create<MyChocolateDispenser>(
   - You can provide custom default values for specific types using `.WithDefaultValueFor<T>()`:
     ```csharp
     var behavior = MockBehavior.Default
-        .WithDefaultValueFor<string>(() => "default")
-        .WithDefaultValueFor<int>(() => 42);
+      .WithDefaultValueFor<string>(() => "default")
+      .WithDefaultValueFor<int>(() => 42);
     var sut = Mock.Create<IChocolateDispenser>(behavior);
     ```
     This is useful when you want mocks to return specific default values for certain types instead of the standard
@@ -269,14 +269,25 @@ sut.SetupMock.Property.TotalDispensed.OnGet
 
 *Notes:*
 
-- All callbacks support more advanced features like conditional execution, frequency control, parallel execution, and
-  access to the invocation counter.
+- Use `.SkippingBaseClass(…)` to override the base class behavior for a specific property (only for class mocks).
+- All callbacks and return values support more advanced features like conditional execution, frequency control,
+  parallel execution, and access to the invocation counter.
   See [Advanced callback features](#advanced-callback-features) for details.
 
 ### Methods
 
 Use `mock.SetupMock.Method.MethodName(…)` to set up methods. You can specify argument matchers for each parameter.
 
+**Returns / Throws**
+
+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.
+
+You can call `.Returns(…)` and `.Throws(…)` multiple times to define a sequence of return values or exceptions (cycled
+on each call).
+
 ```csharp
 // Setup Dispense to decrease stock and raise event
 sut.SetupMock.Method.Dispense(It.Is("Dark"), It.IsAny<int>())
@@ -292,28 +303,21 @@ sut.SetupMock.Method.Dispense(It.Is("Dark"), It.IsAny<int>())
         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.
+// Sequence of returns and throws
+sut.SetupMock.Method.Dispense(It.IsAny<string>(), It.IsAny<int>())
+    .Returns(true)
+    .Throws(new Exception("Error"))
+    .Returns(false);
+```
 
 **Async Methods**
 
-For `Task<T>` or `ValueTask<T>` methods, use `.ReturnsAsync(…)` or `ThrowsAsync(…)`:
+For async methods returning `Task`/`Task<T>` or `ValueTask`/`ValueTask<T>`, use `.ReturnsAsync(…)` or `ThrowsAsync(…)`
+respectively:
 
 ```csharp
 sut.SetupMock.Method.DispenseAsync(It.IsAny<string>(), It.IsAny<int>())
@@ -322,6 +326,24 @@ sut.SetupMock.Method.DispenseAsync(It.IsAny<string>(), It.IsAny<int>())
     .ReturnsAsync(0).Forever();           // Subsequent executions return 0
 ```
 
+**Callbacks**
+
+Use `.Do(…)` to run code when the method is called. Supports parameterless or parameter callbacks.
+
+```csharp
+// Setup method with callback
+sut.SetupMock.Method.Dispense(It.Is("White"), It.IsAny<int>())
+    .Do((type, amount) => Console.WriteLine($"Dispensed {amount} {type} chocolate."));
+```
+
+*Notes:*
+
+- 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.
+- All callbacks and return values support more advanced features like conditional execution, frequency control,
+  parallel execution, and access to the invocation counter.
+  See [Advanced callback features](#advanced-callback-features) for details.
+
 ### Indexers
 
 Set up indexers with argument matchers. Supports initialization, returns/throws sequences, and callbacks.