From d41474fa35572d64f1cec0f371e75163b3da336d Mon Sep 17 00:00:00 2001
From: "Jeremy D. Miller" <Jeremy.Miller@medeanalytics.com>
Date: Mon, 6 Mar 2023 19:39:41 -0600
Subject: [PATCH] Little docs on handler discovery diagnostics

---
 docs/guide/handlers/discovery.md              | 24 +++++++++++++++++-
 .../HandlerDiscoverySamples.cs                | 25 +++++++++++++++++++
 2 files changed, 48 insertions(+), 1 deletion(-)

diff --git a/docs/guide/handlers/discovery.md b/docs/guide/handlers/discovery.md
index caa5e688b..19f2e8427 100644
--- a/docs/guide/handlers/discovery.md
+++ b/docs/guide/handlers/discovery.md
@@ -1,12 +1,34 @@
 # Message Handler Discovery
 
+::: warning
+The handler type scanning and discovery is done against an allow list of assemblies rather than
+running through your entire application's dependency tree. Watch for this if handlers are missing.
+:::
+
 Wolverine has built in mechanisms for automatically finding message handler methods in your application
 based on a set of naming conventions or using explicit interface or attribute markers. If you really wanted to, 
 you could also explicitly add handler types programmatically.
 
+## Troubleshooting Handler Discovery
+
+It's an imperfect world and sometimes Wolverine isn't finding handler methods for some reason or another -- or
+seems to be using types and methods you'd rather it didn't. Not to fear, there's some diagnostic tools
+to help Wolverine explain what's going on.
+
+Directly on `WolverineOptions` itself is a diagnostic method named `DescribeHandlerMatch` that will give
+you a full textual report on why or why not Wolverine is identifying that type as a handler type, then if
+it is found by Wolverine to be a handler type, 
+also giving you a full report on each public method about why or why not Wolverine considers it to be a valid
+handler method.
+
+snippet: sample_describe_handler_match
+
+Even if the report itself isn't exactly clear to you, using this textual report in a Wolverine issue or
+within the [Critter Stack Discord](https://discord.gg/wBkZGpe3) group will help the Wolverine team be able to assist you much quicker. 
+
 ## Assembly Discovery
 
-:::
+::: tip
 The handler discovery uses the `JasperFx.TypeDiscovery` library for type scanning that is shared with several other JasperFx projects. 
 :::
 
diff --git a/src/Samples/DocumentationSamples/HandlerDiscoverySamples.cs b/src/Samples/DocumentationSamples/HandlerDiscoverySamples.cs
index 6778c6bc8..187400170 100644
--- a/src/Samples/DocumentationSamples/HandlerDiscoverySamples.cs
+++ b/src/Samples/DocumentationSamples/HandlerDiscoverySamples.cs
@@ -1,3 +1,4 @@
+using System.Diagnostics;
 using JasperFx.Core.Reflection;
 using Microsoft.Extensions.Hosting;
 using TestingSupport.Compliance;
@@ -153,4 +154,28 @@ public static async Task custom_handler_config()
 
         #endregion
     }
+
+    public static async Task explain_handler()
+    {
+        #region sample_describe_handler_match
+
+        using var host = await Host.CreateDefaultBuilder()
+            .UseWolverine(opts =>
+            {
+                // Surely plenty of other configuration for Wolverine...
+
+                // This *temporary* line of code will write out a full report about why or 
+                // why not Wolverine is finding this handler and its candidate handler messages
+                Console.WriteLine(opts.DescribeHandlerMatch(typeof(MyMissingMessageHandler)));
+            }).StartAsync();
+
+        #endregion
+    }
+    
+    
+}
+
+public class MyMissingMessageHandler
+{
+    public void Handle(){}
 }
\ No newline at end of file