[Docs] Add intial docs.

.github/workflows/deploy.yml

@@ -2,6 +2,16 @@
 # deployes the build to nuget and github releases
 name: Continuous Deployment
 
+concurrency:
+  group: "deployment"
+  cancel-in-progress: false
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  actions: read
+  pages: write
+  id-token: write
+
 on:
   push:
     tags:
@@ -48,6 +58,37 @@ jobs:
           retention-days: 7
           path: ${{ env.NuGetDirectory }}/*.nupkg
 
+  publish-docs:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+
+      - name: Setup .NET
+        uses: actions/setup-dotnet@v4
+        with:
+          dotnet-version: 8.0.x
+
+      - name: Install Docfx
+        run: dotnet tool update -g docfx
+
+      - name: Run Docfx
+        run: docfx docs/docfx.json
+
+      - name: Upload docs page 
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: 'docs/_site'
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
+
   validate-nuget:
     name: Validate nuget
     runs-on: ubuntu-latest

docs/articles/toc.md

@@ -0,0 +1,7 @@
+#[Introduction](intro.md)
+
+#Samples
+
+## [FSEvents](fsevents_sample.md)
+## [FileSystemWatcher](fswatcher.md)
+

docs/docfx.json

@@ -0,0 +1,45 @@
+{
+  "metadata": [
+    {
+      "src": [
+        {
+          "src": "../src",
+          "files": [
+            "**/Marille.csproj"
+          ]
+        }
+      ],
+      "dest": "api"
+    }
+  ],
+  "build": {
+    "content": [
+      {
+        "files": [
+          "**/*.{md,yml}"
+        ],
+        "exclude": [
+          "_site/**"
+        ]
+      }
+    ],
+    "resource": [
+      {
+        "files": [
+          "images/**"
+        ]
+      }
+    ],
+    "output": "_site",
+    "template": [
+      "default",
+      "modern"
+    ],
+    "globalMetadata": {
+      "_appName": "Marille",
+      "_appTitle": "Marille",
+      "_enableSearch": true,
+      "pdf": true
+    }
+  }
+}

src/Marille/Hub.cs

@@ -210,6 +210,7 @@ bool TryGetChannel<T> (string topicName, [NotNullWhen(true)] out Topic? topic,
 		return true;
 	}
 
+	/// <inheritdoc />
 	public async Task<bool> CreateAsync<T> (string topicName, TopicConfiguration configuration,
 		IErrorWorker<T> errorWorker, params IWorker<T>[] initialWorkers) where T : struct
 	{
@@ -234,28 +235,34 @@ public async Task<bool> CreateAsync<T> (string topicName, TopicConfiguration con
 		}
 	}
 
+	/// <inheritdoc />
 	public Task<bool> CreateAsync<T> (string topicName, TopicConfiguration configuration, IErrorWorker<T> errorWorker,
 		IEnumerable<IWorker<T>> initialWorkers) where T : struct
 		=> CreateAsync (topicName, configuration, errorWorker, initialWorkers.ToArray ());
 
+	/// <inheritdoc />
 	public Task<bool> CreateAsync<T> (string topicName, TopicConfiguration configuration,
 		Func<T, Exception, CancellationToken, Task> errorAction, params Func<T, CancellationToken, Task> [] actions) where T : struct
 		=> CreateAsync (topicName, configuration, new LambdaErrorWorker<T> (errorAction), 
 			actions.Select (a => new LambdaWorker<T> (a)));
 
+	/// <inheritdoc />
 	public Task<bool> CreateAsync<T> (string topicName, TopicConfiguration configuration, IErrorWorker<T> errorWorker) where T : struct
 		=> CreateAsync (topicName, configuration, errorWorker, Array.Empty<IWorker<T>> ());
 
+	/// <inheritdoc />
 	public Task<bool> CreateAsync<T> (string topicName, TopicConfiguration configuration,
 		Func<T, Exception, CancellationToken, Task> errorAction) where T : struct
 		=> CreateAsync (topicName, configuration, new LambdaErrorWorker<T> (errorAction));
 
+	/// <inheritdoc />
 	public Task<bool> CreateAsync<T> (string topicName, TopicConfiguration configuration,
 		Func<T, Exception, CancellationToken, Task> errorAction,
 		Func<T, CancellationToken, Task> action) where T : struct
 		=> CreateAsync (topicName, configuration, new LambdaErrorWorker<T> (errorAction),
 			new LambdaWorker<T> (action));
 
+	/// <inheritdoc />
 	public async Task<bool> RegisterAsync<T> (string topicName, params IWorker<T>[] newWorkers) where T : struct
 	{
 		await semaphoreSlim.WaitAsync ().ConfigureAwait (false);
@@ -279,9 +286,11 @@ public async Task<bool> RegisterAsync<T> (string topicName, params IWorker<T>[]
 		}
 	}
 
+	/// <inheritdoc />
 	public Task<bool> RegisterAsync<T> (string topicName, Func<T, CancellationToken, Task> action)  where T : struct
 		=> RegisterAsync (topicName, new LambdaWorker<T> (action));
 
+	/// <inheritdoc />
 	public async ValueTask PublishAsync<T> (string topicName, T publishedEvent) where T : struct
 	{
 		await semaphoreSlim.WaitAsync ().ConfigureAwait (false);
@@ -296,12 +305,14 @@ public async ValueTask PublishAsync<T> (string topicName, T publishedEvent) wher
 		}
 	}
 
+	/// <inheritdoc />
 	public async ValueTask PublishAsync<T> (string topicName, T? publishedEvent) where T : struct
 	{
 		if (publishedEvent is not null)
 			await PublishAsync (topicName, publishedEvent.Value);
 	}
 
+	/// <inheritdoc />
 	public bool TryPublish<T> (string topicName, T publishedEvent) where T : struct
 	{
 		semaphoreSlim.Wait ();
@@ -316,12 +327,14 @@ public bool TryPublish<T> (string topicName, T publishedEvent) where T : struct
 		}
 	}
 
+	/// <inheritdoc />
 	public bool TryPublish<T> (string topicName, T? publishedEvent) where T : struct
 	{
 		return publishedEvent is not null
 		       && TryPublish (topicName, publishedEvent.Value);
 	}
 
+	/// <inheritdoc />
 	public async Task CloseAllAsync ()
 	{
 		// we are using this format to ensure that we have the right nullable types, if we where to use the following
@@ -353,6 +366,7 @@ public async Task CloseAllAsync ()
 		}
 	}
 
+	/// <inheritdoc />
 	public async Task<bool> CloseAsync<T> (string topicName) where T : struct
 	{
 		await semaphoreSlim.WaitAsync ().ConfigureAwait (false);
@@ -386,6 +400,7 @@ protected virtual void Dispose (bool disposing)
 		}
 	}
 
+	/// <inheritdoc />
 	public void Dispose ()
 	{
 		Dispose (true);
@@ -400,6 +415,7 @@ protected virtual async ValueTask DisposeAsyncCore ()
 		}
 	}
 
+	/// <inheritdoc />
 	public async ValueTask DisposeAsync ()
 	{
 		await DisposeAsyncCore ();

src/Marille/IErrorWorker.cs

@@ -1,8 +1,24 @@
 namespace Marille;
 
+/// <summary>
+/// Interface to be implemented by a worker that will take care of handling the errors from IWorker consumers in a
+/// give channel.
+/// </summary>
+/// <typeparam name="T"></typeparam>
 public interface IErrorWorker<in T> : IDisposable, IAsyncDisposable where T : struct {
 
+	/// <summary>
+	/// Specifies if the worker should use a background thread to process the messages. If set to
+	/// true the implementation of the worker should be thread safe.
+	/// </summary>
 	public bool UseBackgroundThread { get; }
 
+	/// <summary>
+	///
+	/// </summary>
+	/// <param name="message"></param>
+	/// <param name="exception"></param>
+	/// <param name="token"></param>
+	/// <returns></returns>
 	public Task ConsumeAsync (T message, Exception exception, CancellationToken token = default);
 }