[project @ 2003-09-01 09:12:02 by ross]

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

diff --git a/GHC/Base.lhs b/GHC/Base.lhs
index 76ade71..f957a6d 100644 (file)
--- a/GHC/Base.lhs
+++ b/GHC/Base.lhs
@@ -279,6 +279,12 @@ The rest of the prelude list functions are in GHC.List.
 ----------------------------------------------
   
 \begin{code}
+-- | 'foldr', applied to a binary operator, a starting value (typically
+-- the right-identity of the operator), and a list, reduces the list
+-- using the binary operator, from right to left:
+--
+-- > foldr f z [x1, x2, ..., xn] == x1 `f` (x2 `f` ... (xn `f` z)...)
+
 foldr            :: (a -> b -> b) -> b -> [a] -> b
 -- foldr _ z []     =  z
 -- foldr f z (x:xs) =  f x (foldr f z xs)
@@ -344,6 +350,12 @@ augment g xs = g (:) xs
 ----------------------------------------------
 
 \begin{code}
+-- | 'map' @f xs@ is the list obtained by applying @f@ to each element
+-- of @xs@, i.e.,
+--
+-- > map f [x1, x2, ..., xn] == [f x1, f x2, ..., f xn]
+-- > map f [x1, x2, ...] == [f x1, f x2, ...]
+
 map :: (a -> b) -> [a] -> [b]
 map _ []     = []
 map f (x:xs) = f x : map f xs
@@ -383,6 +395,13 @@ mapFB c f x ys = c (f x) ys
 --             append  
 ----------------------------------------------
 \begin{code}
+-- | Append two lists, i.e.,
+--
+-- > [x1, ..., xm] ++ [y1, ..., yn] == [x1, ..., xm, y1, ..., yn]
+-- > [x1, ..., xm] ++ [y1, ...] == [x1, ..., xm, y1, ...]
+--
+-- If the first list is not finite, the result is the first list.
+
 (++) :: [a] -> [a] -> [a]
 (++) []     ys = ys
 (++) (x:xs) ys = x : xs ++ ys
@@ -402,8 +421,9 @@ 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.
+-- first so that the corresponding 'Prelude.Enum' instance will give
+-- 'Prelude.fromEnum' 'False' the value zero, and
+-- 'Prelude.fromEnum' 'True' the value 1.
 data  Bool  =  False | True  deriving (Eq, Ord)
        -- Read in GHC.Read, Show in GHC.Show
 
@@ -495,11 +515,15 @@ data Ordering = LT | EQ | GT deriving (Eq, Ord)
 type String = [Char]
 
 {-| The character type 'Char' is an enumeration whose values represent
-Unicode characters.  A character literal in Haskell has type 'Char'.
-
-To convert a 'Char' to or from an 'Int', use 'Prelude.toEnum' and
-'Prelude.fromEnum' from the 'Enum' class respectively (equivalently
-'ord' and 'chr' also do the trick).
+Unicode (or equivalently ISO 10646) characters.
+This set extends the ISO 8859-1 (Latin-1) character set
+(the first 256 charachers), which is itself an extension of the ASCII
+character set (the first 128 characters).
+A character literal in Haskell has type 'Char'.
+
+To convert a 'Char' to or from the corresponding 'Int' value defined
+by Unicode, use 'Prelude.toEnum' and 'Prelude.fromEnum' from the
+'Prelude.Enum' class respectively (or equivalently 'ord' and 'chr').
 -}
 data Char = C# Char#
 
@@ -526,6 +550,7 @@ instance Ord Char where
 "x# `ltChar#` x#" forall x#. x# `ltChar#` x# = False
   #-}
 
+-- | The 'Prelude.toEnum' method restricted to the type 'Data.Char.Char'.
 chr :: Int -> Char
 chr (I# i#) | int2Word# i# `leWord#` int2Word# 0x10FFFF# = C# (chr# i#)
             | otherwise                                  = error "Prelude.chr: bad argument"
@@ -533,6 +558,7 @@ chr (I# i#) | int2Word# i# `leWord#` int2Word# 0x10FFFF# = C# (chr# i#)
 unsafeChr :: Int -> Char
 unsafeChr (I# i#) = C# (chr# i#)
 
+-- | The 'Prelude.fromEnum' method restricted to the type 'Data.Char.Char'.
 ord :: Char -> Int
 ord (C# c#) = I# (ord# c#)
 \end{code}