[project @ 2002-06-18 13:01:43 by simonmar]

[ghc-base.git] / GHC / Base.lhs

diff --git a/GHC/Base.lhs b/GHC/Base.lhs
index 7c43dc3..45138d2 100644 (file)
--- a/GHC/Base.lhs
+++ b/GHC/Base.lhs
@@ -1,11 +1,5 @@
-% -----------------------------------------------------------------------------
-% $Id: Base.lhs,v 1.8 2002/04/24 16:10:21 simonmar Exp $
-%
-% (c) The University of Glasgow, 1992-2002
-%
 \section[GHC.Base]{Module @GHC.Base@}
 
-
 The overall structure of the GHC Prelude is a bit tricky.
 
   a) We want to avoid "orphan modules", i.e. ones with instance
@@ -71,9 +65,21 @@ GHC.ByteArr  Types: ByteArray, MutableByteArray
 
 Other Prelude modules are much easier with fewer complex dependencies.
 
-
 \begin{code}
 {-# OPTIONS -fno-implicit-prelude #-}
+-----------------------------------------------------------------------------
+-- |
+-- Module      :  GHC.Base
+-- Copyright   :  (c) The University of Glasgow, 1992-2002
+-- License     :  see libraries/base/LICENSE
+-- 
+-- Maintainer  :  cvs-ghc@haskell.org
+-- Stability   :  internal
+-- Portability :  non-portable (GHC extensions)
+--
+-- Basic data types and classes.
+-- 
+-----------------------------------------------------------------------------
 
 #include "MachDeps.h"
 
@@ -362,21 +368,34 @@ mapFB c f x ys = c (f x) ys
 %*********************************************************
 
 \begin{code}
+-- |The 'Bool' type is an enumeration.  It is defined with 'False'
+-- first so that the corresponding 'Enum' instance will give @'fromEnum'
+-- False@ the value zero, and @'fromEnum' True@ the value 1.
 data  Bool  =  False | True  deriving (Eq, Ord)
        -- Read in GHC.Read, Show in GHC.Show
 
 -- Boolean functions
 
-(&&), (||)             :: Bool -> Bool -> Bool
+-- | Boolean \"and\"
+(&&)                   :: Bool -> Bool -> Bool
 True  && x             =  x
 False && _             =  False
+
+-- | Boolean \"or\"
+(||)                   :: Bool -> Bool -> Bool
 True  || _             =  True
 False || x             =  x
 
+-- | Boolean \"not\"
 not                    :: Bool -> Bool
 not True               =  False
 not False              =  True
 
+-- |'otherwise' is defined as the value 'True'; it helps to make
+-- guards more readable.  eg.
+--
+-- >  f x | x \< 0     = ...
+-- >      | otherwise = ...
 otherwise              :: Bool
 otherwise              =  True
 \end{code}
@@ -490,6 +509,10 @@ eqString cs1      cs2         = False
 
 \begin{code}
 data Int = I# Int#
+-- ^A fixed-precision integer type with at least the range @[-2^29
+-- .. 2^29-1]@.  The exact range for a given implementation can be
+-- determined by using 'minBound' and 'maxBound' from the 'Bounded'
+-- class.
 
 zeroInt, oneInt, twoInt, maxInt, minInt :: Int
 zeroInt = I# 0#
@@ -771,10 +794,7 @@ unpacking the strings of error messages.
 \begin{code}
 unpackCString# :: Addr# -> [Char]
 {-# NOINLINE [1] unpackCString# #-}
-unpackCString# a = unpackCStringList# a
-
-unpackCStringList# :: Addr# -> [Char]
-unpackCStringList# addr 
+unpackCString# addr 
   = unpack 0#
   where
     unpack nh
@@ -843,10 +863,10 @@ unpackNBytes#  addr len# = unpack [] (len# -# 1#)
 
 {-# RULES
 "unpack"       [~1] forall a   . unpackCString# a                 = build (unpackFoldrCString# a)
-"unpack-list"  [1]  forall a   . unpackFoldrCString# a (:) [] = unpackCStringList# a
+"unpack-list"  [1]  forall a   . unpackFoldrCString# a (:) [] = unpackCString# a
 "unpack-append"     forall a n . unpackFoldrCString# a (:) n  = unpackAppendCString# a n
 
--- There's a built-in rule (in GHC.Rules.lhs) for
+-- There's a built-in rule (in PrelRules.lhs) for
 --     unpackFoldr "foo" c (unpackFoldr "baz" c n)  =  unpackFoldr "foobaz" c n
 
   #-}