Merge pull request #2490 from commercialhaskell/2489-exception-cleanup

Cleanup Exception docs

src/System/Process/Read.hs

@@ -142,6 +142,8 @@ envHelper :: EnvOverride -> Maybe [(String, String)]
 envHelper = Just . eoStringList
 
 -- | Read from the process, ignoring any output.
+--
+-- Throws a 'ReadProcessException' exception if the process fails.
 readProcessNull :: (MonadIO m, MonadLogger m, MonadBaseControl IO m, MonadCatch m)
                 => Maybe (Path Abs Dir) -- ^ Optional working directory
                 -> EnvOverride
@@ -164,7 +166,7 @@ tryProcessStdout wd menv name args =
 
 -- | Produce a strict 'S.ByteString' from the stdout of a process.
 --
--- Throws a 'ReadProcessException' exception if the  process fails.
+-- Throws a 'ReadProcessException' exception if the process fails.
 readProcessStdout :: (MonadIO m, MonadLogger m, MonadBaseControl IO m, MonadCatch m)
                   => Maybe (Path Abs Dir) -- ^ Optional directory to run in
                   -> EnvOverride
@@ -215,6 +217,8 @@ instance Exception ReadProcessException
 -- If the process fails, spits out stdout and stderr as error log
 -- level. Should not be used for long-running processes or ones with
 -- lots of output; for that use 'sinkProcessStdoutLogStderr'.
+--
+-- Throws a 'ReadProcessException' if unsuccessful.
 sinkProcessStdout
     :: (MonadIO m, MonadLogger m, MonadBaseControl IO m, MonadCatch m)
     => Maybe (Path Abs Dir) -- ^ Optional directory to run in
@@ -258,6 +262,8 @@ logProcessStderrStdout mdir name menv args = liftBaseWith $ \restore -> do
     void $ restore $ sinkProcessStderrStdout mdir menv name args logLines logLines
 
 -- | Consume the stdout and stderr of a process feeding strict 'S.ByteString's to the consumers.
+--
+-- Throws a 'ReadProcessException' if unsuccessful in launching, or 'ProcessExitedUnsuccessfully' if the process itself fails.
 sinkProcessStderrStdout :: forall m e o. (MonadIO m, MonadLogger m)
                         => Maybe (Path Abs Dir) -- ^ Optional directory to run in
                         -> EnvOverride
@@ -276,6 +282,9 @@ sinkProcessStderrStdout wd menv name args sinkStderr sinkStdout = do
     f :: Source IO S.ByteString -> Source IO S.ByteString -> IO (e, o)
     f err out = (err $$ sinkStderr) `concurrently` (out $$ sinkStdout)
 
+-- | Like sinkProcessStderrStdout, but receives Handles for stderr and stdout instead of 'Sink's.
+--
+-- Throws a 'ReadProcessException' if unsuccessful in launching, or 'ProcessExitedUnsuccessfully' if the process itself fails.
 sinkProcessStderrStdoutHandle :: (MonadIO m, MonadLogger m)
                               => Maybe (Path Abs Dir) -- ^ Optional directory to run in
                               -> EnvOverride
@@ -298,6 +307,8 @@ sinkProcessStderrStdoutHandle wd menv name args err out = do
 
 -- | Perform pre-call-process tasks.  Ensure the working directory exists and find the
 -- executable path.
+--
+-- Throws a 'ReadProcessException' if unsuccessful.
 preProcess :: (MonadIO m)
   => Maybe (Path Abs Dir) -- ^ Optional directory to create if necessary
   -> EnvOverride       -- ^ How to override environment

src/System/Process/Run.hs

@@ -85,15 +85,15 @@ runCmd' modCP cmd@(Cmd{..}) mbErrMsg = do
 
 -- | Like 'System.Process.callProcess', but takes an optional working directory and
 -- environment override, and throws 'ProcessExitedUnsuccessfully' if the
--- process exits unsuccessfully.
+-- process exits unsuccessfully and a 'ReadProcessException' if the executable is not found.
 --
 -- Inherits stdout and stderr.
 callProcess :: (MonadIO m, MonadLogger m) => Cmd -> m ()
 callProcess = callProcess' id
 
 -- | Like 'System.Process.callProcess', but takes an optional working directory and
 -- environment override, and throws 'ProcessExitedUnsuccessfully' if the
--- process exits unsuccessfully.
+-- process exits unsuccessfully and a 'ReadProcessException' if the executable is not found.
 --
 -- Inherits stdout and stderr.
 callProcess' :: (MonadIO m, MonadLogger m)
@@ -140,6 +140,7 @@ createProcess' tag modCP cmd = do
     $logCreateProcess c
     liftIO $ System.Process.createProcess_ tag c
 
+-- Throws a 'ReadProcessException' if process is not found.
 cmdToCreateProcess :: MonadIO m => Cmd -> m CreateProcess
 cmdToCreateProcess (Cmd wd cmd0 menv args) = do
     cmd <- preProcess wd menv cmd0