docs: added maintainer documentation with FileSystemWatcherMock

CONTRIBUTING.md

@@ -35,3 +35,7 @@ These can be enabled by explicitely running the [`Testably.Abstractions.TestSett
   All tests against the real file system. Per default, they are disabled in DEBUG mode.
 
 *Note: These settings are stored locally in `test.settings.json` which is excluded in [`.gitignore`](https://github.com/Testably/Testably.Abstractions/blob/main/.gitignore) so that it only affects the individual developer!*
+
+## Documentation
+To get a better understanding of the different mock implementations, see [Maintainer.md](./Docs/Maintainer.md).
+The document outlines the different behaviors the mocks replicate.

Docs/FileSystemWatcherMock.md

@@ -0,0 +1,69 @@
+# FileSystemWatcherMock
+
+This document explains the implementation of the `FileSystemWatcherMock` class.
+
+## Events
+
+Before we can go into the different events the operating systems fire, we first have to define the locations the entry
+can be moved from and to.
+
+| Location | Description                                            |
+|----------|--------------------------------------------------------|
+| _        | Entry was created or deleted                           |
+| Outside  | The location is outside the watching path              |
+| Inside   | The location is immediately inside the watching path   |
+| Nested   | The location is nested under the watching path         |
+| Deep     | The location is deeply nested inside the watching path |
+
+For `IncludeSubdirectories = false` we have the following event table:
+
+| From -> To        | Linux     | Windows   | Mac       |
+|-------------------|-----------|-----------|-----------|
+| _ -> Inside       | `Created` | `Created` | `Created` |
+| Inside -> _       | `Deleted` | `Deleted` | `Deleted` |
+| _ -> Nested       | -         | -         | -         |
+| Nested -> _       | -         | -         | -         |
+| _ -> Deep         | -         | -         | -         |
+| Deep -> _         | -         | -         | -         |
+| Outside -> Inside | `Created` | `Created` | `Created` |
+| Inside -> Inside  | `Renamed` | `Renamed` | `Renamed` |
+| Inside -> Outside | `Deleted` | `Deleted` | `Deleted` |
+| Outside -> Nested | -         | -         | -         |
+| Nested -> Nested  | -         | -         | -         |
+| Nested -> Outside | -         | -         | -         |
+| Outside -> Deep   | -         | -         | -         |
+| Deep -> Deep      | -         | -         | -         |
+| Deep -> Outside   | -         | -         | -         |
+| Inside -> Nested  | `Deleted` | `Deleted` | `Renamed` |
+| Inside -> Deep    | `Deleted` | `Deleted` | `Renamed` |
+| Nested -> Inside  | `Created` | `Created` | `Created` |
+| Deep -> Inside    | `Created` | `Created` | `Created` |
+| Nested -> Deep    | -         | -         | -         |
+| Deep -> Nested    | -         | -         | -         |
+
+For `IncludeSubdirectories = true` we have the following event table:
+
+| From -> To        | Linux     | Windows               | Mac       |
+|-------------------|-----------|-----------------------|-----------|
+| _ -> Inside       | `Created` | `Created`             | `Created` |
+| Inside -> _       | `Deleted` | `Deleted`             | `Deleted` |
+| _ -> Nested       | `Created` | `Created`             | `Created` |
+| Nested -> _       | `Deleted` | `Deleted`             | `Deleted` |
+| _ -> Deep         | `Created` | `Created`             | `Created` |
+| Deep -> _         | `Deleted` | `Deleted`             | `Deleted` |
+| Outside -> Inside | `Created` | `Created`             | `Created` |
+| Inside -> Inside  | `Renamed` | `Renamed`             | `Renamed` |
+| Inside -> Outside | `Deleted` | `Deleted`             | `Deleted` |
+| Outside -> Nested | `Created` | `Created`             | `Created` |
+| Nested -> Nested  | `Renamed` | `Renamed`             | `Renamed` |
+| Nested -> Outside | `Deleted` | `Deleted`             | `Deleted` |
+| Outside -> Deep   | `Created` | `Created`             | `Created` |
+| Deep -> Deep      | `Renamed` | `Renamed`             | `Renamed` |
+| Deep -> Outside   | `Deleted` | `Deleted`             | `Deleted` |
+| Inside -> Nested  | `Renamed` | `Deleted` + `Created` | `Renamed` |
+| Inside -> Deep    | `Renamed` | `Deleted` + `Created` | `Renamed` |
+| Nested -> Inside  | `Renamed` | `Deleted` + `Created` | `Renamed` |
+| Deep -> Inside    | `Renamed` | `Deleted` + `Created` | `Renamed` |
+| Nested -> Deep    | `Renamed` | `Deleted` + `Created` | `Renamed` |
+| Deep -> Nested    | `Renamed` | `Deleted` + `Created` | `Renamed` |
+

Docs/Maintainer.md

@@ -0,0 +1,8 @@
+# Maintainer Documentation
+
+This document provides different information about the internal workings of the mocks.
+Outlining complexities and design decisions.
+
+## Implementations
+
+- [FileSystemWatcherMock](FileSystemWatcherMock.md)

Source/Testably.Abstractions.Testing/FileSystem/FileSystemWatcherMock.cs

@@ -18,6 +18,10 @@ namespace Testably.Abstractions.Testing.FileSystem;
 /// <summary>
 ///     Mocked instance of a <see cref="IFileSystemWatcher" />
 /// </summary>
+/// <remarks>
+///  For more information about the implementation,
+///  see <see href="https://github.com/Testably/Testably.Abstractions/blob/main/Docs/FileSystemWatcherMock.md">_/Docs/FileSystemWatcherMock.md</see>
+/// </remarks>
 internal sealed class FileSystemWatcherMock : Component, IFileSystemWatcher
 {
 	/// <summary>

Testably.Abstractions.sln

@@ -68,6 +68,10 @@ EndProject
 Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Testably.Abstractions.Compression.Tests", "Tests\Testably.Abstractions.Compression.Tests\Testably.Abstractions.Compression.Tests.csproj", "{5330AEEE-A915-4FF6-A85D-E9CCA161B654}"
 EndProject
 Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Docs", "Docs", "{4D70CF83-2EEE-439E-AA30-3FADAACAEB0C}"
+	ProjectSection(SolutionItems) = preProject
+		Docs\FileSystemWatcherMock.md = Docs\FileSystemWatcherMock.md
+		Docs\Maintainer.md = Docs\Maintainer.md
+	EndProjectSection
 EndProject
 Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Helpers", "Helpers", "{B6C45D8A-A545-402E-A6B0-47BC7D9BBCF5}"
 EndProject