X-Git-Url: http://git.megacz.com/?a=blobdiff_plain;f=GHC%2FIO%2FDevice.hs;h=8f907d590b2f993cad955836263dc56eb648f1c8;hb=8a37d80b44f75105c23b62f89bb7806b1c331c26;hp=ec1bde838185a700b5856ef6157b827c901da6ac;hpb=0001f92b790079cec9df03c2229d6f39268f60af;p=ghc-base.git

diff --git a/GHC/IO/Device.hs b/GHC/IO/Device.hs
index ec1bde8..8f907d5 100644
--- a/GHC/IO/Device.hs
+++ b/GHC/IO/Device.hs
@@ -132,11 +132,35 @@ class IODevice a where
 ioe_unsupportedOperation :: IO a
 ioe_unsupportedOperation = throwIO unsupportedOperation
 
+-- | Type of a device that can be used to back a
+-- 'GHC.IO.Handle.Handle' (see also 'GHC.IO.Handle.mkFileHandle'). The
+-- standard libraries provide creation of 'GHC.IO.Handle.Handle's via
+-- Posix file operations with file descriptors (see
+-- 'GHC.IO.Handle.FD.mkHandleFromFD') with FD being the underlying
+-- 'GHC.IO.Device.IODevice' instance.
+--
+-- Users may provide custom instances of 'GHC.IO.Device.IODevice'
+-- which are expected to conform the following rules:
+
 data IODeviceType
-  = Directory
-  | Stream
-  | RegularFile
-  | RawDevice
+  = Directory -- ^ The standard libraries do not have direct support
+              -- for this device type, but a user implementation is
+              -- expected to provide a list of file names in
+              -- the directory, in any order, separated by @'\0'@
+              -- characters, excluding the @"."@ and @".."@ names. See
+              -- also 'System.Directory.getDirectoryContents'.  Seek
+              -- operations are not supported on directories (other
+              -- than to the zero position).
+  | Stream    -- ^ A duplex communications channel (results in
+              -- creation of a duplex 'GHC.IO.Handle.Handle'). The
+              -- standard libraries use this device type when
+              -- creating 'GHC.IO.Handle.Handle's for open sockets.
+  | RegularFile -- ^ A file that may be read or written, and also
+                -- may be seekable.
+  | RawDevice -- ^ A "raw" (disk) device which supports block binary
+              -- read and write operations and may be seekable only
+              -- to positions of certain granularity (block-
+              -- aligned).
   deriving (Eq)
 
 -- -----------------------------------------------------------------------------