[project @ 2004-07-26 17:22:41 by ross]

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

diff --git a/GHC/Base.lhs b/GHC/Base.lhs
index 71bac07..d3dcd46 100644 (file)
--- a/GHC/Base.lhs
+++ b/GHC/Base.lhs
@@ -641,7 +641,7 @@ compareInt# x# y#
 %*********************************************************
 
 \begin{code}
--- identity function
+-- | Identity function.
 id                     :: a -> a
 id x                   =  x
 
@@ -653,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