Update the docs for version 6.1.0

Author: TolikPylypchuk

CHANGELOG.md

@@ -1,5 +1,10 @@
 # SharpHook Changelog
 
+## [v6.1.0](https://github.com/TolikPylypchuk/SharpHook/releases/tag/v6.1.0) (May 23, 2025)
+
+- The ability to control the behaviour of `TestGlobalHook` and `TestProvider` (simple dispatching from version 5 vs an
+event loop from version 6) was added. The simple behaviour from version 5 is the default as it is much easier to use.
+
 ## [v6.0.0](https://github.com/TolikPylypchuk/SharpHook/releases/tag/v6.0.0) (May 18, 2025)
 
 ### Platform Support

docs/articles/about.md

@@ -55,6 +55,11 @@ You need .NET 9 to build SharpHook.
 
 ## Changelog
 
+### [v6.1.0](https://github.com/TolikPylypchuk/SharpHook/releases/tag/v6.1.0) (May 23, 2025)
+
+- The ability to control the behaviour of `TestGlobalHook` and `TestProvider` (simple dispatching from version 5 vs an
+event loop from version 6) was added. The simple behaviour from version 5 is the default as it is much easier to use.
+
 ### [v6.0.0](https://github.com/TolikPylypchuk/SharpHook/releases/tag/v6.0.0) (May 18, 2025)
 
 #### Platform Support

docs/articles/migration.md

@@ -30,9 +30,7 @@ All obsolete values in the `KeyCode` enum were removed.
 
 `HookException` doesn't support `BinaryFormatter` serialization anymore.
 
-The behaviour of `TestGlobalHook` and `TestProvider` was changed. Instead of dispatching events in the same thread that
-simulates them, they now instead add events into an event loop running on a different thread. `TestProvider` now throws
-an exception if `Run` or `RunAsync` is called and it's already running.
+`TestProvider` now throws an exception if `Run` or `RunAsync` is called and it's already running.
 
 The minimum .NET Framework version was bumped to 4.7.2 and direct support for .NET 6 and .NET 7 was dropped (though they
 are still supported through .NET Standard 2.0).

docs/articles/testing.md

@@ -38,11 +38,18 @@ public async Task TestLastPressedKey()
 If this class is used as an `IEventSimulator` in the tested code, then the `SimulatedEvents` property can be checked to
 see which events were simulated using the test instance.
 
-It's recommended to stop the global hook and wait for it to stop before asserting any events. The test global hook runs
-an event loop using `BlockingCollection`, and posting an event will add this event to this collection for the global
-hook to dispatch. Since these actions are done in different threads, it is not guaranteed that an event will be
-dispatched immediately after it is simulated. `Run` and the task returned by `RunAsync` will complete after every event
-has been dispatched.
+`TestGlobalHook` can be used with two different threading modes - the simple mode and the event loop mode.
+
+When running in simple mode (the default mode) the hook will dispatch events immediately in the same thread which
+simulates them.
+
+When running the event loop, the hook will run an actual even loop on the thread on which `Run` was called. When
+simulating events, they will be posted to the event loop, and then dispatched in the hook thread. This mode is much more
+difficult to use correctly, so it is useful only when it is important for event handlers to run in the same thread on
+which the hook itself is running. It's recommended to stop the global hook and wait for it to stop before asserting any
+events. Since these actions are done in different threads, it is not guaranteed that an event will be dispatched
+immediately after it is simulated. `Run` and the task returned by `RunAsync` will complete after every event has been
+dispatched.
 
 Other than that, members of `TestGlobalHook` are quite straightforward; the API reference should be viewed for more
 info.
@@ -56,12 +63,19 @@ If the low-level functionality of SharpHook should be mocked, or mocking should
 then `SharpHook.Testing.TestProvider` can be used. It implements every interface in the `SharpHook.Providers` namespace,
 and as such, it can be used instead of normal low-level functionality providers.
 
-Like `TestGlobalHook`, this class can post events using the `PostEvent` method and dispatch them if `Run` has been
+Like `TestProvider`, this class can post events using the `PostEvent` method and dispatch them if `Run` has been
 called. It also contains the `PostedEvents` property.
 
-It's recommended to stop the provider and wait for it to stop before asserting any events. The test provider runs an
-event loop using `BlockingCollection`, and posting an event will add this event to this collection for the provider to
-dispatch. Since these actions are done in different threads, it is not guaranteed that an event will be dispatched
+`TestProvider` can be used with two different threading modes - the simple mode and the event loop mode.
+
+When running in simple mode (the default mode) the provider will dispatch events immediately in the same thread which
+simulates them.
+
+When running the event loop, the provider will run an actual even loop on the thread on which `Run` was called. When
+simulating events, they will be posted to the event loop, and then dispatched in the hook thread. This mode is much more
+difficult to use correctly, so it is useful only when it is important for event handlers to run in the same thread on
+which the hook itself is running. It's recommended to stop the provider and wait for it to stop before asserting any
+events. Since these actions are done in different threads, it is not guaranteed that an event will be dispatched
 immediately after it is simulated. `Run` and the task returned by `RunAsync` will complete after every event has been
 dispatched.
 
@@ -82,6 +96,3 @@ var simulator = new EventSimulator(simulationProvider: testProvider);
 > `TaskPoolGlobalHook` shouldn't be used this way since its event handlers are asynchronous and there is no built-in
 > way to know when they are actually executed. As such, it's difficult to check event handler results. If you want
 > to use a real hook, e.g. for integration testing, then use `SimpleGlobalHook` instead.
-
-It's recommended to stop the provider and wait for it to stop before asserting any events. The test provider runs
-an event loop just like the test global hook so the same constraints apply to its usage.