diff --git a/Web/Scotty.hs b/Web/Scotty.hs
index 5b3c3e70..4045650f 100644
--- a/Web/Scotty.hs
+++ b/Web/Scotty.hs
@@ -96,8 +96,6 @@ middleware = Trans.middleware
 -- this could require stripping the current prefix, or adding the prefix to your
 -- application's handlers if it depends on them. One potential use-case for this
 -- is hosting a web-socket handler under a specific route.
--- nested :: Application -> ActionM ()
--- nested :: (Monad m, MonadIO m) => Application -> ActionT Text m ()
 nested :: Application -> ActionM ()
 nested = Trans.nested
 
@@ -107,16 +105,23 @@ nested = Trans.nested
 setMaxRequestBodySize :: Kilobytes -> ScottyM ()
 setMaxRequestBodySize = Trans.setMaxRequestBodySize
 
--- | Throw a "500 Server Error" 'StatusError', which can be caught with 'rescue'. Uncaught exceptions
--- turn into HTTP 500 responses.
+-- | Throw a "500 Server Error" 'StatusError', which can be caught with 'rescue'.
+--
+-- Uncaught exceptions turn into HTTP 500 responses.
 raise :: Text -> ActionM a
 raise = Trans.raise
 
--- | Throw a 'StatusError' exception that has an associated HTTP error code and can be caught with 'rescue'. Uncaught exceptions turn into HTTP responses corresponding to the given status.
+-- | Throw a 'StatusError' exception that has an associated HTTP error code and can be caught with 'rescue'.
+--
+-- Uncaught exceptions turn into HTTP responses corresponding to the given status.
 raiseStatus :: Status -> Text -> ActionM a
 raiseStatus = Trans.raiseStatus
 
--- | Throw an exception. A user-defined 'Handler' will then have to define its interpretation and a translation to HTTP error codes.
+-- | Throw an exception which can be caught within the scope of the current Action with 'rescue' or 'catch'.
+--
+-- If the exception is not caught locally, another option is to implement a global 'Handler' (with 'defaultHandler') that defines its interpretation and a translation to HTTP error codes.
+--
+-- Uncaught exceptions turn into HTTP 500 responses.
 throw :: (E.Exception e) => e -> ActionM a
 throw = Trans.throw
 
diff --git a/Web/Scotty/Action.hs b/Web/Scotty/Action.hs
index 87e6f0f1..726240f5 100644
--- a/Web/Scotty/Action.hs
+++ b/Web/Scotty/Action.hs
@@ -133,19 +133,25 @@ someExceptionHandler :: MonadIO m => ErrorHandler m
 someExceptionHandler = Handler $ \case
   (_ :: E.SomeException) -> status status500
 
-
 -- | Throw a "500 Server Error" 'StatusError', which can be caught with 'rescue'.
+--
 -- Uncaught exceptions turn into HTTP 500 responses.
 raise :: (MonadIO m) =>
          T.Text -- ^ Error text
       -> ActionT m a
 raise  = raiseStatus status500
 
--- | Throw a 'StatusError' exception that has an associated HTTP error code and can be caught with 'rescue'. Uncaught exceptions turn into HTTP responses corresponding to the given status.
+-- | Throw a 'StatusError' exception that has an associated HTTP error code and can be caught with 'rescue'.
+--
+-- Uncaught exceptions turn into HTTP responses corresponding to the given status.
 raiseStatus :: Monad m => Status -> T.Text -> ActionT m a
 raiseStatus s = E.throw . StatusError s
 
--- | Throw an exception. A user-defined 'Handler' will then have to define its interpretation and a translation to HTTP error codes.
+-- | Throw an exception which can be caught within the scope of the current Action with 'rescue' or 'catch'.
+--
+-- If the exception is not caught locally, another option is to implement a global 'Handler' (with 'defaultHandler') that defines its interpretation and a translation to HTTP error codes.
+--
+-- Uncaught exceptions turn into HTTP 500 responses.
 throw :: (MonadIO m, E.Exception e) => e -> ActionT m a
 throw = E.throw