From c4d0c63df03c3f12c9b6eebf998cd1088cbde630 Mon Sep 17 00:00:00 2001
From: "Paolo G. Giarrusso" <p.giarrusso@gmail.com>
Date: Sun, 14 Aug 2016 12:29:34 +0200
Subject: [PATCH] System.Process.Read/Run: Haddock thrown exceptions

This documentation matters for catching exceptions later, and to make
sure we're catching all exceptions we need to.

Some of the documentation turned out to be incorrect.
---
 src/System/Process/Read.hs | 10 ++++++++++
 src/System/Process/Run.hs  |  5 +++--
 2 files changed, 13 insertions(+), 2 deletions(-)

diff --git a/src/System/Process/Read.hs b/src/System/Process/Read.hs
index 0f1fbdc795..af82d82b31 100644
--- a/src/System/Process/Read.hs
+++ b/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
@@ -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
@@ -277,6 +283,8 @@ sinkProcessStderrStdout wd menv name args sinkStderr sinkStdout = do
     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
@@ -299,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
diff --git a/src/System/Process/Run.hs b/src/System/Process/Run.hs
index da55223427..1148a4083b 100644
--- a/src/System/Process/Run.hs
+++ b/src/System/Process/Run.hs
@@ -85,7 +85,7 @@ 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 ()
@@ -93,7 +93,7 @@ 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