Loads of doc(test)s

1 files changed, 23 insertions, 2 deletions

diff --git a/libraries/base/Data/Function.hs b/libraries/base/Data/Function.hs
index c5ded4cda5..ccc58c74ac 100644
--- a/libraries/base/Data/Function.hs
+++ b/libraries/base/Data/Function.hs
@@ -32,13 +32,28 @@ infixl 1 &
 
 -- | @'fix' f@ is the least fixed point of the function @f@,
 -- i.e. the least defined @x@ such that @f x = x@.
+--
+-- For example, we can write the factorial function using direct recursion as
+--
+-- >>> let fac n = if n <= 1 then 1 else n * fac (n-1) in fac 5
+-- 120
+--
+-- This uses the fact that Haskell’s @let@ introduces recursive bindings. We can
+-- rewrite this definition using 'fix',
+--
+-- >>> fix (\rec n -> if n <= 1 then 1 else n * rec (n-1)) 5
+-- 120
+--
+-- Instead of making a recursive call, we introduce a dummy parameter @rec@;
+-- when used within 'fix', this parameter then refers to 'fix'' argument, hence
+-- the recursion is reintroduced.
 fix :: (a -> a) -> a
 fix f = let x = f x in x
 
--- | @(*) \`on\` f = \\x y -> f x * f y@.
+-- | @((==) \`on\` f) x y = f x == f y@
 --
 -- Typical usage: @'Data.List.sortBy' ('compare' \`on\` 'fst')@.
---
+
 -- Algebraic properties:
 --
 -- * @(*) \`on\` 'id' = (*)@ (if @(*) &#x2209; {&#x22a5;, 'const' &#x22a5;}@)
@@ -95,6 +110,12 @@ on :: (b -> b -> c) -> (a -> b) -> a -> a -> c
 -- convenience.  Its precedence is one higher than that of the forward
 -- application operator '$', which allows '&' to be nested in '$'.
 --
+-- >>> 5 & (+1) & show
+-- "6"
+--
 -- @since 4.8.0.0
 (&) :: a -> (a -> b) -> b
 x & f = f x
+
+-- $setup
+-- >>> import Prelude