[project @ 2003-08-30 22:55:42 by ross]

docs for System.Environment & System.Exit

diff --git a/GHC/IOBase.lhs b/GHC/IOBase.lhs
index c25c69e..312fda9 100644 (file)
--- a/GHC/IOBase.lhs
+++ b/GHC/IOBase.lhs
@@ -701,18 +701,17 @@ instance Eq Exception where
 -- -----------------------------------------------------------------------------
 -- The ExitCode type
 
--- The `ExitCode' type defines the exit codes that a program
--- can return.  `ExitSuccess' indicates successful termination;
--- and `ExitFailure code' indicates program failure
--- with value `code'.  The exact interpretation of `code'
--- is operating-system dependent.  In particular, some values of 
--- `code' may be prohibited (e.g. 0 on a POSIX-compliant system).
-
 -- We need it here because it is used in ExitException in the
 -- Exception datatype (above).
 
-data ExitCode = ExitSuccess | ExitFailure Int 
-                deriving (Eq, Ord, Read, Show)
+data ExitCode
+  = ExitSuccess        -- ^ indicates successful termination;
+  | ExitFailure Int
+               -- ^ indicates program failure with an exit code.
+               -- The exact interpretation of the code is
+               -- operating-system dependent.  In particular, some values
+               -- may be prohibited (e.g. 0 on a POSIX-compliant system).
+  deriving (Eq, Ord, Read, Show)
 
 -- --------------------------------------------------------------------------
 -- Primitive throw

diff --git a/System/Environment.hs b/System/Environment.hs
index 31f6765..a0761d5 100644 (file)
--- a/System/Environment.hs
+++ b/System/Environment.hs
@@ -51,7 +51,7 @@ import System
 -- ---------------------------------------------------------------------------
 -- getArgs, getProgName, getEnv
 
--- Computation `getArgs' returns a list of the program's command
+-- | Computation 'getArgs' returns a list of the program's command
 -- line arguments (not including the program name).
 
 #ifdef __GLASGOW_HASKELL__
@@ -107,11 +107,13 @@ unpackProgName argv = do
    isPathSeparator _    = False
 
 
--- Computation `getEnv var' returns the value
--- of the environment variable {\em var}.  
-
--- This computation may fail with
---    NoSuchThing: The environment variable does not exist.
+-- | Computation 'getEnv' @var@ returns the value
+-- of the environment variable @var@.  
+--
+-- This computation may fail with:
+--
+--  * 'System.IO.Error.isDoesNotExistError' if the environment variable
+--    does not exist.
 
 getEnv :: String -> IO String
 getEnv name =

diff --git a/System/Exit.hs b/System/Exit.hs
index bce69e6..1dab14f 100644 (file)
--- a/System/Exit.hs
+++ b/System/Exit.hs
@@ -40,9 +40,22 @@ import System
 -- ---------------------------------------------------------------------------
 -- exitWith
 
--- `exitWith code' terminates the program, returning `code' to the
--- program's caller.  Before it terminates, any open or semi-closed
--- handles are first closed.
+-- | Computation 'exitWith' @code@ throws 'ExitException' @code@.
+-- Normally this terminates the program, returning @code@ to the
+-- program's caller.  Before the program terminates, any open or
+-- semi-closed handles are first closed.
+--
+-- A program that fails in any other way is treated as if it had
+-- called 'exitFailure'.
+-- A program that terminates successfully without calling 'exitWith'
+-- explicitly is treated as it it had called 'exitWith' 'ExitSuccess'.
+--
+-- As an 'ExitException' is not an 'IOError', 'exitWith' bypasses
+-- the error handling in the 'IO' monad and cannot be intercepted by
+-- 'catch' from the "Prelude".  However it is an 'Exception', and can
+-- be caught using the functions of "Control.Exception".  This means
+-- that cleanup computations added with 'Control.Exception.bracket'
+-- (from "Control.Exception") are also executed properly on 'exitWith'.
 
 #ifndef __NHC__
 exitWith :: ExitCode -> IO a
@@ -54,5 +67,8 @@ exitWith code@(ExitFailure n)
 #endif
 #endif  /* ! __NHC__ */
 
+-- | The computation 'exitFailure' is equivalent to
+-- 'exitWith' @(@'ExitFailure' /exitfail/@)@,
+-- where /exitfail/ is implementation-dependent.
 exitFailure :: IO a
 exitFailure = exitWith (ExitFailure 1)