add a description of the new updateMVar strictness tests (and describ…

…e why they aren't helpful with compiler optimizations turned on)

ouroboros-consensus/test/consensus-test/Test/Consensus/Util/MonadSTM/NormalForm.hs

@@ -13,20 +13,27 @@ import           Ouroboros.Consensus.Util.MonadSTM.NormalForm (MonadSTM,
 import           Test.Tasty
 import           Test.Tasty.QuickCheck
 
-
 -- Note that all of the tests here are only significant with compiler
--- optimizations turned off!
+-- optimizations turned off! These tests ensure that the invariants are
+-- maintained when calling `updateMVar` on consensus' `StrictMVar` values
+-- (which are created with a `NoThunks` "this should not contain any unforced
+-- thunks" invariant). Because the existence of thunks (and therefore the
+-- behaviour of `unsafeNoThunks`) is heavily dependent on compiler
+-- optimizations, these tests will *always* pass at -O1 or higher (at least on
+-- GHC 8.10 and GHC 9.2).
 tests :: TestTree
 tests = testGroup "Ouroboros.Consensus.Util.MonadSTM.NormalForm"
   [ testGroup "updateMVar"
-    [ testProperty "IO @Integer @String"
-        (prop_update_mvar_strictness_io @Integer @String)
-    , testProperty "IOSim @Integer @String"
-        (prop_update_mvar_strictness_iosim @Integer @String)
-    , testProperty "IO @StrictnessTestType @String"
-        (prop_update_mvar_strictness_io @StrictnessTestType @String)
-    , testProperty "IOSim @StrictnessTestType @String"
-        (prop_update_mvar_strictness_iosim @StrictnessTestType @String)
+    [ testGroup "updateMVar strictness"
+      [ testProperty "IO @Integer @String"
+          (prop_update_mvar_strictness_io @Integer @String)
+      , testProperty "IOSim @Integer @String"
+          (prop_update_mvar_strictness_iosim @Integer @String)
+      , testProperty "IO @StrictnessTestType @String"
+          (prop_update_mvar_strictness_io @StrictnessTestType @String)
+      , testProperty "IOSim @StrictnessTestType @String"
+          (prop_update_mvar_strictness_iosim @StrictnessTestType @String)
+      ]
     ]
   ]