#140: Add docs for LogLevel

Author: colinangusmackay

docs/_config.yml

@@ -18,9 +18,8 @@ kramdown:
 github:
   repository_url: https://github.com/Stravaig-Projects/Stravaig.Extensions.Logging.Diagnostics
 
-# UPDATE ME IN A NEW REPOSITORY
 nuget:
   urls:
     - https://www.nuget.org/packages/Stravaig.Extensions.Logging.Diagnostics
     - https://www.nuget.org/packages/Stravaig.Extensions.Logging.Diagnostics.XUnit
-#    - https://www.nuget.org/packages/Stravaig.Package3.etc
+    - https://www.nuget.org/packages/Stravaig.Extensions.Logging.Diagnostics.Verify

docs/docs/library/verify-extensions.md

@@ -67,4 +67,5 @@ Nondeterministic values in the verified file produce brittle tests, so the parts
 ## How do I set up to verify the things I want?
 
 * Configure the [Sequence](verify/sequence.md)
+* Verify the [LogLevel](verify/loglevel.md)
 

docs/docs/library/verify/loglevel.md

@@ -0,0 +1,78 @@
+---
+layout: default
+title: Verify Logs - Sequence
+---
+
+# Verifying the log level of log entries
+
+The `LoggingCaptureVerifySettings` has a Boolean `LogLevel` property that defines if the log level is to be verified or not.
+
+```csharp
+public async Task VerifyWarningLogsAreEmittedCorrectlyTestAsync()
+{
+    // ... Code that produces logs
+    
+    VerifySettings verifySettings = new VerifySettings()
+        .AddCapturedLogs(new LoggingCaptureVerifySettings()
+        {
+            LogLevel = true,
+        });
+
+    await Verifier.Verify(logs, verifySettings);
+}
+```
+
+## Example output
+
+### LogLevel = false
+
+```
+[
+  {
+    Sequence: 0,
+    CategoryName: Stravaig.LoggingExample.Program,
+    MessageTemplate: This is the first default log message.
+  },
+  {
+    Sequence: 1,
+    CategoryName: Stravaig.LoggingExample.Program,
+    MessageTemplate: This is a warning.
+  },
+  {
+    Sequence: 2,
+    CategoryName: Stravaig.LoggingExample.Program,
+    MessageTemplate: An unexpected error occurred.,
+    Exception: {
+      Type: System.ApplicationException
+    }
+  },
+]
+```
+
+### LogLevel = true
+
+```
+[
+  {
+    Sequence: 0,
+    LogLevel: Information,
+    CategoryName: Stravaig.LoggingExample.Program,
+    MessageTemplate: This is the first default log message.
+  },
+  {
+    Sequence: 1,
+    LogLevel: Warning,
+    CategoryName: Stravaig.LoggingExample.Program,
+    MessageTemplate: This is a warning.
+  },
+  {
+    Sequence: 2,
+    LogLevel: Error,
+    CategoryName: Stravaig.LoggingExample.Program,
+    MessageTemplate: An unexpected error occurred.,
+    Exception: {
+      Type: System.ApplicationException
+    }
+  },
+]
+```

docs/docs/library/verify/sequence.md

@@ -25,6 +25,14 @@ public async Task VerifyWarningLogsAreEmittedCorrectlyTestAsync()
 }
 ```
 
+## When is this useful?
+
+`ShowAsConsecutive` is useful if you want to verify logs in a custom order, but still want to verify which sequence they were originally in.
+
+`ShowAsCadence` is useful if you are only interested in verifying certain logs (e.g. Warnings and above), and want to show that there were some skipped logs in between those you are verifying. However, this may intruduce some brittleness to the verify process as it is easy to insert or remove logs that you may not wish to test for when diagnosing bugs or tidying up the application.
+
+`Hide` is useful if you want to reduce the size of the verify files and you have the logs directly from one of the various `Get...Logs()` methods on the `TestCaptureLoggerProvider` or `TestCaptureLogger`, as they return the logs in the sequence in which they were logged.
+
 ## Example output
 
 Here are some examples of the verify output for difference `Sequence` settings.

docs/scripts/contributors.md

@@ -2,17 +2,17 @@
 
 This is a list of all the contributors to this repository in ascending order by the contributor name.
 
-**Colin Mackay** contributed 350 commits from Saturday, 26 September, 2020 @ 20:26:19 +00:00 to Sunday, 17 March, 2024 @ 22:16:23 +00:00.
+**Colin Mackay** contributed 352 commits from Saturday, 26 September, 2020 @ 20:26:19 +00:00 to Wednesday, 20 March, 2024 @ 22:53:33 +00:00.
 
 **dependabot[bot]** contributed 59 commits from Wednesday, 14 October, 2020 @ 19:13:43 +00:00 to Monday, 26 February, 2024 @ 14:54:09 +00:00.
 
 **StravaigBot** contributed 28 commits from Monday, 14 December, 2020 @ 19:28:09 +00:00 to Tuesday, 27 February, 2024 @ 21:50:14 +00:00.
 
 ## Summary
 
-:octocat: 437 commits in total.
+:octocat: 439 commits in total.
 
 :date: From Saturday, 26 September, 2020 @ 20:26:19 +00:00.
 
-:date: Until Sunday, 17 March, 2024 @ 22:16:23 +00:00.
+:date: Until Wednesday, 20 March, 2024 @ 22:53:33 +00:00.
 

src/Stravaig.Extensions.Logging.Diagnostics.Verify/LoggingCaptureVerifySettings.cs

@@ -36,7 +36,7 @@ public class LoggingCaptureVerifySettings
     public Sequence Sequence { get; init; } = Sequence.ShowAsConsecutive;
 
     /// <summary>
-    /// Gets whether the log leve is to be verified.
+    /// Gets whether the log level is to be verified.
     /// Default is true.
     /// </summary>
     public bool LogLevel { get; init; } = true;