docs: improve documentation

Docs/pages/01-create-mocks.md

@@ -14,9 +14,13 @@ var classMock = Mock.Create<MyChocolateDispenser>();
 var classWithArgsMock = Mock.Create<MyChocolateDispenserWithCtor>(
     BaseClass.WithConstructorParameters("Dark", 42)
 );
+```
+
+You can specify up to eight additional interfaces that the mock also implements (beyond the first type):
 
-// Specify up to 8 additional interfaces for the mock:
-var sut2 = Mock.Create<MyChocolateDispenser, ILemonadeDispenser>();
+```csharp
+// return type is a MyChocolateDispenser that also implements ILemonadeDispenser
+var sut = Mock.Create<MyChocolateDispenser, ILemonadeDispenser>();
 ```
 
 **Notes:**
@@ -29,7 +33,7 @@ var sut2 = Mock.Create<MyChocolateDispenser, ILemonadeDispenser>();
 You can control the default behavior of the mock by providing a `MockBehavior`:
 
 ```csharp
-var strictMock = Mock.Create<IChocolateDispenser>(new MockBehavior { ThrowWhenNotSetup = true });
+var strictMock = Mock.Create<IChocolateDispenser>(MockBehavior.Default with { ThrowWhenNotSetup = true });
 
 // For classes with constructor parameters and custom behavior:
 var classMock = Mock.Create<MyChocolateDispenser>(
@@ -40,18 +44,13 @@ 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.
 - `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.
-- `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.
+- `ThrowWhenNotSetup` (bool):
+  - If `false` (default), the mock will return a default value (see `DefaultValue`), when no matching setup is found.
+  - If `true`, the mock will throw an exception when no matching setup is found.
 - `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:
@@ -60,16 +59,21 @@ var classMock = Mock.Create<MyChocolateDispenser>(
     - 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>()`:
+  - You can add custom default value factories 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?[])`:
+    defaults.
+- `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 (e.g. when mocking databases).
+- `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(…)`.
 
@@ -78,7 +82,7 @@ var classMock = Mock.Create<MyChocolateDispenser>(
 Use `Mock.Factory` to create multiple mocks with a shared behavior:
 
 ```csharp
-var behavior = new MockBehavior { ThrowWhenNotSetup = true };
+var behavior = MockBehavior.Default with { ThrowWhenNotSetup = true };
 var factory = new Mock.Factory(behavior);
 
 var sut1 = factory.Create<IChocolateDispenser>();
@@ -94,7 +98,7 @@ You can wrap an existing instance with mock tracking using `Mock.Wrap<T>()`. Thi
 a real object:
 
 ```csharp
-var realDispenser = new ChocolateDispenser();
+var realDispenser = new MyChocolateDispenser();
 var wrappedDispenser = Mock.Wrap<IChocolateDispenser>(realDispenser);
 
 // Calls are forwarded to the real instance
@@ -109,4 +113,5 @@ wrappedDispenser.VerifyMock.Invoked.Dispense(It.Is("Dark"), It.Is(5)).Once();
 - Only interface types can be wrapped with `Mock.Wrap<T>()`.
 - All calls are forwarded to the wrapped instance.
 - You can still set up custom behavior that overrides the wrapped instance's behavior.
+- You cannot override protected members of the wrapped instance.
 - Verification works the same as with regular mocks.

README.md

@@ -96,9 +96,13 @@ var classMock = Mock.Create<MyChocolateDispenser>();
 var classWithArgsMock = Mock.Create<MyChocolateDispenserWithCtor>(
     BaseClass.WithConstructorParameters("Dark", 42)
 );
+```
+
+You can specify up to eight additional interfaces that the mock also implements (beyond the first type):
 
-// Specify up to 8 additional interfaces for the mock:
-var sut2 = Mock.Create<MyChocolateDispenser, ILemonadeDispenser>();
+```csharp
+// return type is a MyChocolateDispenser that also implements ILemonadeDispenser
+var sut = Mock.Create<MyChocolateDispenser, ILemonadeDispenser>();
 ```
 
 **Notes:**
@@ -111,7 +115,7 @@ var sut2 = Mock.Create<MyChocolateDispenser, ILemonadeDispenser>();
 You can control the default behavior of the mock by providing a `MockBehavior`:
 
 ```csharp
-var strictMock = Mock.Create<IChocolateDispenser>(new MockBehavior { ThrowWhenNotSetup = true });
+var strictMock = Mock.Create<IChocolateDispenser>(MockBehavior.Default with { ThrowWhenNotSetup = true });
 
 // For classes with constructor parameters and custom behavior:
 var classMock = Mock.Create<MyChocolateDispenser>(
@@ -122,18 +126,13 @@ 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.
 - `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.
-- `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.
+- `ThrowWhenNotSetup` (bool):
+  - If `false` (default), the mock will return a default value (see `DefaultValue`), when no matching setup is found.
+  - If `true`, the mock will throw an exception when no matching setup is found.
 - `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:
@@ -142,16 +141,21 @@ var classMock = Mock.Create<MyChocolateDispenser>(
     - 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>()`:
+  - You can add custom default value factories 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?[])`:
+    defaults.
+- `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 (e.g. when mocking databases).
+- `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(…)`.
 
@@ -160,7 +164,7 @@ var classMock = Mock.Create<MyChocolateDispenser>(
 Use `Mock.Factory` to create multiple mocks with a shared behavior:
 
 ```csharp
-var behavior = new MockBehavior { ThrowWhenNotSetup = true };
+var behavior = MockBehavior.Default with { ThrowWhenNotSetup = true };
 var factory = new Mock.Factory(behavior);
 
 var sut1 = factory.Create<IChocolateDispenser>();
@@ -176,7 +180,7 @@ You can wrap an existing instance with mock tracking using `Mock.Wrap<T>()`. Thi
 a real object:
 
 ```csharp
-var realDispenser = new ChocolateDispenser();
+var realDispenser = new MyChocolateDispenser();
 var wrappedDispenser = Mock.Wrap<IChocolateDispenser>(realDispenser);
 
 // Calls are forwarded to the real instance
@@ -191,6 +195,7 @@ wrappedDispenser.VerifyMock.Invoked.Dispense(It.Is("Dark"), It.Is(5)).Once();
 - Only interface types can be wrapped with `Mock.Wrap<T>()`.
 - All calls are forwarded to the wrapped instance.
 - You can still set up custom behavior that overrides the wrapped instance's behavior.
+- You cannot override protected members of the wrapped instance.
 - Verification works the same as with regular mocks.
 
 ## Setup