docs: improve method setup documentation

Author: vbreuss

Docs/pages/setup/01-properties.md

@@ -74,6 +74,7 @@ sut.SetupMock.Property.TotalDispensed.OnGet
 
 **Notes:**
 
+- Use `.SkippingBaseClass(…)` to override the base class behavior for a specific property (only for class mocks).
 - All callbacks 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)

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

@@ -118,37 +118,37 @@ var classMock = Mock.Create<MyChocolateDispenser>(
 **`MockBehavior` options**
 
 - `ThrowWhenNotSetup` (bool):
-  - If `false` (default), the mock will return a default value (see `DefaultValue`).
-  - If `true`, the mock will throw an exception when a method or property is called without a setup.
+	- If `false` (default), the mock will return a default value (see `DefaultValue`).
+	- If `true`, the mock will throw an exception when a method or property is called without a setup.
 - `SkipBaseClass` (bool):
-  - If `false` (default), the mock will call the base class implementation and use its return values as default
-    values, if no explicit setup is defined.
-  - If `true`, the mock will not call any base class implementations.
+	- If `false` (default), the mock will call the base class implementation and use its return values as default
+	  values, if no explicit setup is defined.
+	- If `true`, the mock will not call any base class implementations.
 - `Initialize<T>(params Action<IMockSetup<T>>[] setups)`:
-  - Automatically initialize all mocks of type T with the given setups when they are created.
-  - The callback can optionally receive an additional counter parameter which allows to differentiate between multiple
-    instances. This is useful when you want to ensure that you can distinguish between different automatically created
-    instances.
+	- Automatically initialize all mocks of type T with the given setups when they are created.
+	- The callback can optionally receive an additional counter parameter which allows to differentiate between multiple
+	  instances. This is useful when you want to ensure that you can distinguish between different automatically created
+	  instances.
 - `DefaultValue` (IDefaultValueGenerator):
-  - Customizes how default values are generated for methods/properties that are not set up.
-  - The default implementation provides sensible defaults for the most common use cases:
-    - Empty collections for collection types (e.g., `IEnumerable<T>`, `List<T>`, etc.)
-    - Empty string for `string`
-    - Completed tasks for `Task`, `Task<T>`, `ValueTask` and `ValueTask<T>`
-    - Tuples with recursively defaulted values
-    - `null` for other reference types
-  - You can provide custom default values for specific types using `.WithDefaultValueFor<T>()`:
-    ```csharp
-    var behavior = MockBehavior.Default
-        .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
-    defaults (e.g., `null`, `0`, empty strings).
+	- Customizes how default values are generated for methods/properties that are not set up.
+	- The default implementation provides sensible defaults for the most common use cases:
+		- Empty collections for collection types (e.g., `IEnumerable<T>`, `List<T>`, etc.)
+		- Empty string for `string`
+		- Completed tasks for `Task`, `Task<T>`, `ValueTask` and `ValueTask<T>`
+		- Tuples with recursively defaulted values
+		- `null` for other reference types
+	- You can provide custom default values for specific types using `.WithDefaultValueFor<T>()`:
+	  ```csharp
+	  var behavior = MockBehavior.Default
+		  .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
+	  defaults (e.g., `null`, `0`, empty strings).
 - `.UseConstructorParametersFor<T>(object?[])`:
-  - Configures constructor parameters to use when creating mocks of type `T`, unless explicit parameters are provided
-    during mock creation via `BaseClass.WithConstructorParameters(…)`.
+	- Configures constructor parameters to use when creating mocks of type `T`, unless explicit parameters are provided
+	  during mock creation via `BaseClass.WithConstructorParameters(…)`.
 
 ### Using a factory for shared behavior
 
@@ -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 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.