X-Git-Url: http://git.megacz.com/?a=blobdiff_plain;f=GHC%2FBase.lhs;h=5b6a6768e0260e63a788d9d00808aa206b17f857;hb=9ecf132d64d35e5997c12286f509b2f8d7f2a7ef;hp=71bac07a8cfbc2b911580da8df319a0bab7725c6;hpb=c39743fe545c5e3b0af5e8e8ba5208d30f463e22;p=ghc-base.git

diff --git a/GHC/Base.lhs b/GHC/Base.lhs
index 71bac07..5b6a676 100644
--- a/GHC/Base.lhs
+++ b/GHC/Base.lhs
@@ -64,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
@@ -81,6 +81,7 @@ Other Prelude modules are much easier with fewer complex dependencies.
 
 #include "MachDeps.h"
 
+-- #hide
 module GHC.Base
 	(
 	module GHC.Base,
@@ -208,14 +209,22 @@ Instances of 'Functor' should satisfy the following laws:
 > fmap id  ==  id
 > fmap (f . g)  ==  fmap f . fmap g
 
-The instances of 'Functor' for lists, 'Maybe' and 'IO' defined in the "Prelude"
-satisfy these laws.
+The instances of 'Functor' for lists, 'Data.Maybe.Maybe' and 'System.IO.IO'
+defined in the "Prelude" satisfy these laws.
 -}
 
 class  Functor f  where
     fmap        :: (a -> b) -> f a -> f b
 
-{- | The 'Monad' class defines the basic operations over a /monad/.
+{- | The 'Monad' class defines the basic operations over a /monad/,
+a concept from a branch of mathematics known as /category theory/.
+From the perspective of a Haskell programmer, however, it is best to
+think of a monad as an /abstract datatype/ of actions.
+Haskell's @do@ expressions provide a convenient syntax for writing
+monadic expressions.
+
+Minimal complete definition: '>>=' and 'return'.
+
 Instances of 'Monad' should satisfy the following laws:
 
 > return a >>= k  ==  k a
@@ -226,16 +235,26 @@ Instances of both 'Monad' and 'Functor' should additionally satisfy the law:
 
 > fmap f xs  ==  xs >>= return . f
 
-The instances of 'Monad' for lists, 'Maybe' and 'IO' defined in the "Prelude"
-satisfy these laws.
+The instances of 'Monad' for lists, 'Data.Maybe.Maybe' and 'System.IO.IO'
+defined in the "Prelude" satisfy these laws.
 -}
 
 class  Monad m  where
+    -- | Sequentially compose two actions, passing any value produced
+    -- by the first as an argument to the second.
     (>>=)       :: forall a b. m a -> (a -> m b) -> m b
+    -- | Sequentially compose two actions, discarding any value produced
+    -- by the first, like sequencing operators (such as the semicolon)
+    -- in imperative languages.
     (>>)        :: forall a b. m a -> m b -> m b
 	-- Explicit for-alls so that we know what order to
 	-- give type arguments when desugaring
+
+    -- | Inject a value into the monadic type.
     return      :: a -> m a
+    -- | Fail with a message.  This operation is not part of the
+    -- mathematical definition of a monad, but is invoked on pattern-match
+    -- failure in a @do@ expression.
     fail	:: String -> m a
 
     m >> k      = m >>= \_ -> k
@@ -303,6 +322,15 @@ foldr k z xs = go xs
 	       go []     = z
 	       go (y:ys) = y `k` go ys
 
+-- | A list producer that can be fused with 'foldr'.
+-- This function is merely
+--
+-- >	build g = g (:) []
+--
+-- but GHC's simplifier will transform an expression of the form
+-- @'foldr' k z ('build' g)@, which may arise after inlining, to @g k z@,
+-- which avoids producing an intermediate list.
+
 build 	:: forall a. (forall b. (a -> b -> b) -> b -> b) -> [a]
 {-# INLINE [1] build #-}
 	-- The INLINE is important, even though build is tiny,
@@ -314,6 +342,15 @@ build 	:: forall a. (forall b. (a -> b -> b) -> b -> b) -> [a]
 
 build g = g (:) []
 
+-- | A list producer that can be fused with 'foldr'.
+-- This function is merely
+--
+-- >	augment g xs = g (:) xs
+--
+-- but GHC's simplifier will transform an expression of the form
+-- @'foldr' k z ('augment' g xs)@, which may arise after inlining, to
+-- @g k ('foldr' k z xs)@, which avoids producing an intermediate list.
+
 augment :: forall a. (forall b. (a->b->b) -> b -> b) -> [a] -> [a]
 {-# INLINE [1] augment #-}
 augment g xs = g (:) xs
@@ -641,7 +678,7 @@ compareInt# x# y#
 %*********************************************************
 
 \begin{code}
--- identity function
+-- | Identity function.
 id			:: a -> a
 id x			=  x
 
@@ -653,40 +690,59 @@ 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)@.
+
+-- | If the first argument evaluates to 'True', then the result is the
+-- second argument.  Otherwise an 'AssertionFailed' exception is raised,
+-- containing a 'String' with the source file and line number of the
+-- call to 'assert'.
+--
+-- Assertions can normally be turned on or off with a compiler flag
+-- (for GHC, assertions are normally on unless the @-fignore-asserts@
+-- option is given).  When assertions are turned off, the first
+-- argument to 'assert' is ignored, and the second argument is
+-- returned as the result.
+
 -- 	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
@@ -857,22 +913,33 @@ gtInt, geInt, eqInt, neInt, ltInt, leInt :: Int -> Int -> Bool
 -- Note that these wrappers still produce undefined results when the
 -- second argument (the shift amount) is negative.
 
-shiftL#, shiftRL# :: Word# -> Int# -> Word#
-
+-- | Shift the argument left by the specified number of bits
+-- (which must be non-negative).
+shiftL# :: Word# -> Int# -> Word#
 a `shiftL#` b   | b >=# WORD_SIZE_IN_BITS# = int2Word# 0#
 	        | otherwise                = a `uncheckedShiftL#` b
 
+-- | Shift the argument right by the specified number of bits
+-- (which must be non-negative).
+shiftRL# :: Word# -> Int# -> Word#
 a `shiftRL#` b  | b >=# WORD_SIZE_IN_BITS# = int2Word# 0#
 	        | otherwise                = a `uncheckedShiftRL#` b
 
-iShiftL#, iShiftRA#, iShiftRL# :: Int# -> Int# -> Int#
-
+-- | Shift the argument left by the specified number of bits
+-- (which must be non-negative).
+iShiftL# :: Int# -> Int# -> Int#
 a `iShiftL#` b  | b >=# WORD_SIZE_IN_BITS# = 0#
 	        | otherwise                = a `uncheckedIShiftL#` b
 
+-- | Shift the argument right (signed) by the specified number of bits
+-- (which must be non-negative).
+iShiftRA# :: Int# -> Int# -> Int#
 a `iShiftRA#` b | b >=# WORD_SIZE_IN_BITS# = if a <# 0# then (-1#) else 0#
 	        | otherwise                = a `uncheckedIShiftRA#` b
 
+-- | Shift the argument right (unsigned) by the specified number of bits
+-- (which must be non-negative).
+iShiftRL# :: Int# -> Int# -> Int#
 a `iShiftRL#` b | b >=# WORD_SIZE_IN_BITS# = 0#
 	        | otherwise                = a `uncheckedIShiftRL#` b