documentation patch for process

[Evan Laforge]

I recently burned some time because I didn't realize that
System.Process.createProcess doesn't report when the binary isn't
found.  I guess I was used to that behaviour from python's subprocess
module, which goes to some effort to report the error from the
fork()ed child when exec() fails.  After a failed solution, I did some
poking around in the source to see exactly what haskell's process
does.

In the interests of saving someone else that time, I submit a patch to
process to add some documentation.  I'm not sure how to do a 'darcs
send' with git, but here's the patch:

% git log | head
commit 5a46937961b3400fa58ccffc785d0de8c1c01d94
Author: Evan Laforge <qdunkan at gmail.com>
Date:   Wed Feb 8 13:25:16 2012 -0800

    More detailed haddock for createProcess: document what happens if
    the binary is not found

commit c8b30a6f1d493ab724f2da05dbc49496b119a051
Author: Simon Marlow <marlowsd at gmail.com>
Date:   Mon Jan 16 16:25:34 2012 +0000

% git diff HEAD\^
diff --git a/System/Process.hs b/System/Process.hs
index f3a8f9b..a372228 100644
--- a/System/Process.hs
+++ b/System/Process.hs
@@ -234,9 +234,18 @@ To create a pipe from which to read the output of @ls@:
 To also set the directory in which to run @ls@:

 >   (_, Just hout, _, _) <-
->       createProcess (proc "ls" []){ cwd = Just "\home\bob",
+>       createProcess (proc "ls" []){ cwd = Just "/home/bob",
 >                                     std_out = CreatePipe }

+Note that this does /not/ throw an error if the binary is not found,
+or not executable.  Instead, the process will fail with the exit code 127.
+But you can't rely on it failing quickly, because it may e.g. hang up
+searching the PATH on a slow NFS mount.  Since there's no way to tell when
+the exec() has succeeded, the only way to reliably know if the createProcess
+failed is to 'waitForProcess'.
+
+If the CreateProcess record's 'cwd' directory doesn't exist, the exit code
+will be 126.
 -}
 createProcess
   :: CreateProcess
diff --git a/System/Process/Internals.hs b/System/Process/Internals.hs
index 11de1f4..2a6c047 100644
--- a/System/Process/Internals.hs
+++ b/System/Process/Internals.hs
@@ -199,7 +199,8 @@ data CmdSpec
   = ShellCommand String
       -- ^ a command line to execute using the shell
   | RawCommand FilePath [String]
-      -- ^ the filename of an executable with a list of arguments
+      -- ^ The filename of an executable with a list of arguments.
+      -- The PATH is searched for the executable.

 data StdStream
   = Inherit                  -- ^ Inherit Handle from parent