From: Simon Marlow <marlowsd@gmail.com>
Date: Tue, 29 Jun 2010 12:21:18 +0000 (+0000)
Subject: doc updates in System.IO
X-Git-Url: http://git.megacz.com/?p=ghc-base.git;a=commitdiff_plain;h=0001f92b790079cec9df03c2229d6f39268f60af

doc updates in System.IO
---

diff --git a/GHC/IO/Device.hs b/GHC/IO/Device.hs
index 67ea242..ec1bde8 100644
--- a/GHC/IO/Device.hs
+++ b/GHC/IO/Device.hs
@@ -142,7 +142,7 @@ data IODeviceType
 -- -----------------------------------------------------------------------------
 -- SeekMode type
 
--- | A mode that determines the effect of 'hSeek' @hdl mode i@, as follows:
+-- | A mode that determines the effect of 'hSeek' @hdl mode i@.
 data SeekMode
   = AbsoluteSeek        -- ^ the position of @hdl@ is set to @i@.
   | RelativeSeek        -- ^ the position of @hdl@ is set to offset @i@
diff --git a/GHC/IO/Handle.hs b/GHC/IO/Handle.hs
index ff37738..bf706e0 100644
--- a/GHC/IO/Handle.hs
+++ b/GHC/IO/Handle.hs
@@ -393,6 +393,8 @@ hSetPosn (HandlePosn h i) = hSeek h AbsoluteSeek i
 --
 -- This operation may fail with:
 --
+--  * 'isIllegalOperationError' if the Handle is not seekable, or does
+--    not support the requested seek mode.
 --  * 'isPermissionError' if a system resource limit would be exceeded.
 
 hSeek :: Handle -> SeekMode -> Integer -> IO () 
@@ -417,6 +419,15 @@ hSeek handle mode offset =
     IODevice.seek haDevice mode offset
 
 
+-- | Computation 'hTell' @hdl@ returns the current position of the
+-- handle @hdl@, as the number of bytes from the beginning of
+-- the file.  The value returned may be subsequently passed to
+-- 'hSeek' to reposition the handle to the current position.
+-- 
+-- This operation may fail with:
+--
+--  * 'isIllegalOperationError' if the Handle is not seekable.
+--
 hTell :: Handle -> IO Integer
 hTell handle = 
     wantSeekableHandle "hGetPosn" handle $ \ handle_@Handle__{..} -> do
diff --git a/GHC/IO/Handle/Types.hs b/GHC/IO/Handle/Types.hs
index 0a56d9a..73a9927 100644
--- a/GHC/IO/Handle/Types.hs
+++ b/GHC/IO/Handle/Types.hs
@@ -86,15 +86,6 @@ import Data.Typeable
 -- enough information to identify the handle for debugging.  A handle is
 -- equal according to '==' only to itself; no attempt
 -- is made to compare the internal state of different handles for equality.
---
--- GHC note: a 'Handle' will be automatically closed when the garbage
--- collector detects that it has become unreferenced by the program.
--- However, relying on this behaviour is not generally recommended:
--- the garbage collector is unpredictable.  If possible, use explicit
--- an explicit 'hClose' to close 'Handle's when they are no longer
--- required.  GHC does not currently attempt to free up file
--- descriptors when they have run out, it is your responsibility to
--- ensure that this doesn't happen.
 
 data Handle 
   = FileHandle                          -- A normal handle to a file
diff --git a/GHC/IO/IOMode.hs b/GHC/IO/IOMode.hs
index dbae088..606f24f 100644
--- a/GHC/IO/IOMode.hs
+++ b/GHC/IO/IOMode.hs
@@ -22,5 +22,6 @@ import GHC.Read
 import GHC.Arr
 import GHC.Enum
 
+-- | See 'System.IO.openFile'
 data IOMode      =  ReadMode | WriteMode | AppendMode | ReadWriteMode
                     deriving (Eq, Ord, Ix, Enum, Read, Show)
diff --git a/System/IO.hs b/System/IO.hs
index a543f2b..cbcc453 100644
--- a/System/IO.hs
+++ b/System/IO.hs
@@ -25,6 +25,15 @@ module System.IO (
 
     Handle,             -- abstract, instance of: Eq, Show.
 
+    -- | GHC note: a 'Handle' will be automatically closed when the garbage
+    -- collector detects that it has become unreferenced by the program.
+    -- However, relying on this behaviour is not generally recommended:
+    -- the garbage collector is unpredictable.  If possible, use explicit
+    -- an explicit 'hClose' to close 'Handle's when they are no longer
+    -- required.  GHC does not currently attempt to free up file
+    -- descriptors when they have run out, it is your responsibility to
+    -- ensure that this doesn't happen.
+
     -- ** Standard handles
 
     -- | Three handles are allocated during program initialisation,
@@ -615,8 +624,7 @@ foreign import ccall "getpid" c_getpid :: IO Int
 -- $locking
 -- Implementations should enforce as far as possible, at least locally to the
 -- Haskell process, multiple-reader single-writer locking on files.
--- That is, /there may either be many handles on the same file which manage
--- input, or just one handle on the file which manages output/.  If any
+-- That is, /there may either be many handles on the same file which manage input, or just one handle on the file which manages output/.  If any
 -- open or semi-closed handle is managing a file for output, no new
 -- handle can be allocated for that file.  If any open or semi-closed
 -- handle is managing a file for input, new handles can only be allocated