Add a warning about DB actions getting rolled back

yesod-core/src/Yesod/Core/Handler.hs

@@ -91,7 +91,8 @@ module Yesod.Core.Handler
     , permissionDeniedI
     , invalidArgs
     , invalidArgsI
-      -- ** Short-circuit responses.
+      -- ** Short-circuit responses
+      -- $rollbackWarning
     , sendFile
     , sendFilePart
     , sendResponse
@@ -607,6 +608,20 @@ setMessageI = addMessageI ""
 getMessage :: MonadHandler m => m (Maybe Html)
 getMessage = fmap (fmap snd . listToMaybe) getMessages
 
+-- $rollbackWarning
+--
+-- Note that since short-circuiting is implemented by using exceptions,
+-- using e.g. 'sendStatusJSON' inside a runDB block
+-- will result in the database actions getting rolled back:
+--
+-- @
+-- runDB $ do
+--   userId <- insert $ User "username" "email@example.com"
+--   postId <- insert $ BlogPost "title" "hi there!"
+--     /The previous two inserts will be rolled back./
+--   sendStatusJSON Status.status200 ()
+-- @
+
 -- | Bypass remaining handler code and output the given file.
 --
 -- For some backends, this is more efficient than reading in the file to