X-Git-Url: http://git.megacz.com/?a=blobdiff_plain;f=GHC%2FBase.lhs;h=bf37476875f76631525f465e367f0e0377f000d8;hb=0425e42d530ad34fbef2529a20ba326dbd4109b7;hp=71bac07a8cfbc2b911580da8df319a0bab7725c6;hpb=c39743fe545c5e3b0af5e8e8ba5208d30f463e22;p=haskell-directory.git

diff --git a/GHC/Base.lhs b/GHC/Base.lhs
index 71bac07..bf37476 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,
@@ -303,6 +304,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 +324,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 +660,7 @@ compareInt# x# y#
 %*********************************************************
 
 \begin{code}
--- identity function
+-- | Identity function.
 id			:: a -> a
 id x			=  x
 
@@ -653,40 +672,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
@@ -857,22 +884,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