X-Git-Url: http://git.megacz.com/?a=blobdiff_plain;f=GHC%2FBase.lhs;h=6a6926917f6cdbed4e0055645bca05b1dbd1cd3c;hb=a34fb5505b42a5f019d1fdf0dd586a5239400346;hp=76ade714e2764c65e927b8827f95c57736a7df35;hpb=550bd82e4fa20eb3ac0613d5a8e145bf69e4d9cd;p=ghc-base.git

diff --git a/GHC/Base.lhs b/GHC/Base.lhs
index 76ade71..6a69269 100644
--- a/GHC/Base.lhs
+++ b/GHC/Base.lhs
@@ -16,8 +16,6 @@ GHC.Prim		Has no implementation.  It defines built-in things, and
 		The source file is GHC.Prim.hi-boot, which is just
 		copied to make GHC.Prim.hi
 
-		Classes: CCallable, CReturnable
-
 GHC.Base	Classes: Eq, Ord, Functor, Monad
 		Types:   list, (), Int, Bool, Ordering, Char, String
 
@@ -66,7 +64,7 @@ GHC.ByteArr	Types: ByteArray, MutableByteArray
 Other Prelude modules are much easier with fewer complex dependencies.
 
 \begin{code}
-{-# OPTIONS -fno-implicit-prelude #-}
+{-# OPTIONS_GHC -fno-implicit-prelude #-}
 -----------------------------------------------------------------------------
 -- |
 -- Module      :  GHC.Base
@@ -163,14 +161,22 @@ class  Eq a  where
     x /= y		 = not (x == y)
     x == y		 = not (x /= y)
 
+-- | The 'Ord' class is used for totally ordered datatypes.
+--
+-- Instances of 'Ord' can be derived for any user-defined
+-- datatype whose constituent types are in 'Ord'.  The declared order
+-- of the constructors in the data declaration determines the ordering
+-- in derived 'Ord' instances.  The 'Ordering' datatype allows a single
+-- comparison to determine the precise ordering of two objects.
+--
+-- Minimal complete definition: either 'compare' or '<='.
+-- Using 'compare' can be more efficient for complex types.
+--
 class  (Eq a) => Ord a  where
     compare		 :: a -> a -> Ordering
     (<), (<=), (>), (>=) :: a -> a -> Bool
     max, min		 :: a -> a -> a
 
-    -- An instance of Ord should define either 'compare' or '<='.
-    -- Using 'compare' can be more efficient for complex types.
-
     compare x y
 	| x == y    = EQ
 	| x <= y    = LT	-- NB: must be '<=' not '<' to validate the
@@ -225,8 +231,10 @@ satisfy these laws.
 -}
 
 class  Monad m  where
-    (>>=)       :: m a -> (a -> m b) -> m b
-    (>>)        :: m a -> m b -> m b
+    (>>=)       :: forall a b. m a -> (a -> m b) -> m b
+    (>>)        :: forall a b. m a -> m b -> m b
+	-- Explicit for-alls so that we know what order to
+	-- give type arguments when desugaring
     return      :: a -> m a
     fail	:: String -> m a
 
@@ -279,6 +287,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 +358,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 +403,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 +429,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 +523,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 +558,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 +566,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}
@@ -557,10 +591,9 @@ 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.
+-- ^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
+-- 'Prelude.minBound' and 'Prelude.maxBound' from the 'Prelude.Bounded' class.
 
 zeroInt, oneInt, twoInt, maxInt, minInt :: Int
 zeroInt = I# 0#
@@ -608,7 +641,7 @@ compareInt# x# y#
 %*********************************************************
 
 \begin{code}
--- identity function
+-- | Identity function.
 id			:: a -> a
 id x			=  x
 
@@ -620,40 +653,48 @@ id x			=  x
 lazy :: a -> a
 lazy x = x
 
--- Assertion function. This simply ignores its boolean argument.
--- The compiler may rewrite it to (assertError line)
+-- | Assertion function.  This simply ignores its boolean argument.
+-- The compiler may rewrite it to @('assertError' line)@.
+
 -- 	SLPJ: in 5.04 etc 'assert' is in GHC.Prim,
 --	but from Template Haskell onwards it's simply
 --	defined here in Base.lhs
 assert :: Bool -> a -> a
 assert pred r = r
  
--- constant function
+-- | Constant function.
 const			:: a -> b -> a
 const x _		=  x
 
--- function composition
+-- | Function composition.
 {-# INLINE (.) #-}
 (.)	  :: (b -> c) -> (a -> b) -> a -> c
 (.) f g	x = f (g x)
 
--- flip f  takes its (first) two arguments in the reverse order of f.
+-- | @'flip' f@ takes its (first) two arguments in the reverse order of @f@.
 flip			:: (a -> b -> c) -> b -> a -> c
 flip f x y		=  f y x
 
--- right-associating infix application operator (useful in continuation-
--- passing style)
+-- | Application operator.  This operator is redundant, since ordinary
+-- application @(f x)@ means the same as @(f '$' x)@. However, '$' has
+-- low, right-associative binding precedence, so it sometimes allows
+-- parentheses to be omitted; for example:
+--
+-- >     f $ g $ h x  =  f (g (h x))
+--
+-- It is also useful in higher-order situations, such as @'map' ('$' 0) xs@,
+-- or @'Data.List.zipWith' ('$') fs xs@.
 {-# INLINE ($) #-}
 ($)			:: (a -> b) -> a -> b
 f $ x			=  f x
 
--- until p f  yields the result of applying f until p holds.
+-- | @'until' p f@ yields the result of applying @f@ until @p@ holds.
 until			:: (a -> Bool) -> (a -> a) -> a -> a
 until p f x | p x	=  x
 	    | otherwise =  until p f (f x)
 
--- asTypeOf is a type-restricted version of const.  It is usually used
--- as an infix operator, and its typing forces its first argument
+-- | 'asTypeOf' is a type-restricted version of 'const'.  It is usually
+-- used as an infix operator, and its typing forces its first argument
 -- (which is usually overloaded) to have the same type as the second.
 asTypeOf		:: a -> a -> a
 asTypeOf		=  const
@@ -661,25 +702,6 @@ asTypeOf		=  const
 
 %*********************************************************
 %*							*
-\subsection{CCallable instances}
-%*							*
-%*********************************************************
-
-Defined here to avoid orphans
-
-\begin{code}
-instance CCallable Char
-instance CReturnable Char
-
-instance CCallable   Int
-instance CReturnable Int
-
-instance CReturnable () -- Why, exactly?
-\end{code}
-
-
-%*********************************************************
-%*							*
 \subsection{Generics}
 %*							*
 %*********************************************************
@@ -965,3 +987,12 @@ unpackNBytes#  addr len# = unpack [] (len# -# 1#)
 
   #-}
 \end{code}
+
+#ifdef __HADDOCK__
+\begin{code}
+-- | A special argument for the 'Control.Monad.ST.ST' type constructor,
+-- indexing a state embedded in the 'Prelude.IO' monad by
+-- 'Control.Monad.ST.stToIO'.
+data RealWorld
+\end{code}
+#endif