docs: add remarks explaining when class instances change

Author: thomhurst

TUnit.Engine/Extensions/TestContextExtensions.cs

@@ -36,13 +36,20 @@ internal static class TestContextExtensions
     /// <summary>
     /// Checks if the class instance has changed since caches were built, and invalidates if needed.
     /// </summary>
+    /// <remarks>
+    /// Class instances change in these scenarios:
+    /// - Test retries: A new instance is created for each retry attempt
+    /// - Keyed test instances: Different data combinations may use different instances
+    /// When this happens, eligible event objects may include the new instance (if it implements
+    /// event receiver interfaces), so all caches must be invalidated and rebuilt.
+    /// </remarks>
     private static void InvalidateCachesIfClassInstanceChanged(TestContext testContext)
     {
         var currentClassInstance = testContext.Metadata.TestDetails.ClassInstance;
         if (testContext.CachedClassInstance != null &&
             !ReferenceEquals(testContext.CachedClassInstance, currentClassInstance))
         {
-            // Class instance changed (e.g., on retry), invalidate all caches
+            // Class instance changed - invalidate all caches so they're rebuilt with the new instance
             testContext.InvalidateEventReceiverCaches();
         }
         testContext.CachedClassInstance = currentClassInstance;