From fd14d1940233a4563d14a89fc195587c95750300 Mon Sep 17 00:00:00 2001
From: ross <unknown>
Date: Mon, 26 Jul 2004 17:22:43 +0000
Subject: [PATCH] [project @ 2004-07-26 17:22:41 by ross] a few odd docs

---
 Data/Tuple.hs |    6 ++++--
 GHC/Base.lhs  |   30 +++++++++++++++++++-----------
 GHC/Err.lhs   |    5 +++--
 Prelude.hs    |    8 ++++++++
 4 files changed, 34 insertions(+), 15 deletions(-)

diff --git a/Data/Tuple.hs b/Data/Tuple.hs
index ea7191a..3fb4074 100644
--- a/Data/Tuple.hs
+++ b/Data/Tuple.hs
@@ -258,17 +258,19 @@ data (,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,
 -- Standard functions over tuples
 
 #if !defined(__HUGS__) && !defined(__NHC__)
+-- | Extract the first component of a pair.
 fst			:: (a,b) -> a
 fst (x,_)		=  x
 
+-- | Extract the second component of a pair.
 snd			:: (a,b) -> b
 snd (_,y)		=  y
 
--- curry converts an uncurried function to a curried function;
--- uncurry converts a curried function to a function on pairs.
+-- | 'curry' converts an uncurried function to a curried function.
 curry                   :: ((a, b) -> c) -> a -> b -> c
 curry f x y             =  f (x, y)
 
+-- | 'uncurry' converts a curried function to a function on pairs.
 uncurry                 :: (a -> b -> c) -> ((a, b) -> c)
 uncurry f p             =  f (fst p) (snd p)
 #endif  /* neither __HUGS__ nor __NHC__ */
diff --git a/GHC/Base.lhs b/GHC/Base.lhs
index 71bac07..d3dcd46 100644
--- 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
diff --git a/GHC/Err.lhs b/GHC/Err.lhs
index a44e1a5..803fdf0 100644
--- a/GHC/Err.lhs
+++ b/GHC/Err.lhs
@@ -52,12 +52,13 @@ import GHC.Exception
 %*********************************************************
 
 \begin{code}
--- error stops execution and displays an error message
+-- | 'error' stops execution and displays an error message.
 error :: String -> a
 error s = throw (ErrorCall s)
 
+-- | A special case of 'error'.
 -- It is expected that compilers will recognize this and insert error
--- messages which are more appropriate to the context in which undefined 
+-- messages which are more appropriate to the context in which 'undefined'
 -- appears. 
 
 undefined :: a
diff --git a/Prelude.hs b/Prelude.hs
index 9de927d..ddf3a93 100644
--- a/Prelude.hs
+++ b/Prelude.hs
@@ -179,7 +179,15 @@ infixr 0 $!
 -- -----------------------------------------------------------------------------
 -- Miscellaneous functions
 
+-- | Strict (call-by-value) application, defined in terms of 'seq'.
 ($!)    :: (a -> b) -> a -> b
 f $! x  = x `seq` f x
 #endif
 
+#ifdef __HADDOCK__
+-- | The value of @'seq' a b@ is bottom if @a@ is bottom, and otherwise
+-- equal to @b@.  'seq' is usually introduced to improve performance by
+-- avoiding unneeded laziness.
+seq :: a -> b -> b
+seq _ y = y
+#endif
-- 
1.7.10.4