Loads of doc(test)s

14 files changed, 272 insertions, 110 deletions

diff --git a/libraries/base/Control/Monad.hs b/libraries/base/Control/Monad.hs
index 6a474037c0..a3eaa720c6 100644
--- a/libraries/base/Control/Monad.hs
+++ b/libraries/base/Control/Monad.hs
@@ -146,15 +146,15 @@ the list arguments. This could be an issue where @('>>')@ and the `folded
 function' are not commutative.
 
 
->       foldM f a1 [x1, x2, ..., xm]
-
-==
-
->       do
->         a2 <- f a1 x1
->         a3 <- f a2 x2
->         ...
->         f am xm
+> foldM f a1 [x1, x2, ..., xm]
+>
+> ==
+>
+> do
+>   a2 <- f a1 x1
+>   a3 <- f a2 x2
+>   ...
+>   f am xm
 
 If right-to-left evaluation is required, the input list should be reversed.
 
@@ -264,19 +264,19 @@ The functions in this library use the following naming conventions:
   The monad type constructor @m@ is added to function results
   (modulo currying) and nowhere else.  So, for example,
 
->  filter  ::              (a ->   Bool) -> [a] ->   [a]
->  filterM :: (Monad m) => (a -> m Bool) -> [a] -> m [a]
+> filter  ::              (a ->   Bool) -> [a] ->   [a]
+> filterM :: (Monad m) => (a -> m Bool) -> [a] -> m [a]
 
 * A postfix \'@_@\' changes the result type from @(m a)@ to @(m ())@.
   Thus, for example:
 
->  sequence  :: Monad m => [m a] -> m [a]
->  sequence_ :: Monad m => [m a] -> m ()
+> sequence  :: Monad m => [m a] -> m [a]
+> sequence_ :: Monad m => [m a] -> m ()
 
 * A prefix \'@m@\' generalizes an existing function to a monadic form.
   Thus, for example:
 
->  sum  :: Num a       => [a]   -> a
->  msum :: MonadPlus m => [m a] -> m a
+> sum  :: Num a       => [a]   -> a
+> msum :: MonadPlus m => [m a] -> m a
 
 -}
diff --git a/libraries/base/Data/Foldable.hs b/libraries/base/Data/Foldable.hs
index 1d9fc92ca5..e33d45efcf 100644
--- a/libraries/base/Data/Foldable.hs
+++ b/libraries/base/Data/Foldable.hs
@@ -506,6 +506,9 @@ sequence_ :: (Foldable t, Monad m) => t (m a) -> m ()
 sequence_ = foldr (>>) (return ())
 
 -- | The sum of a collection of actions, generalizing 'concat'.
+--
+-- asum [Just "Hello", Nothing, Just "World"]
+-- Just "Hello"
 asum :: (Foldable t, Alternative f) => t (f a) -> f a
 {-# INLINE asum #-}
 asum = foldr (<|>) empty
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
diff --git a/libraries/base/Data/Proxy.hs b/libraries/base/Data/Proxy.hs
index d6f03548f3..1ebf56c9a5 100644
--- a/libraries/base/Data/Proxy.hs
+++ b/libraries/base/Data/Proxy.hs
@@ -28,7 +28,31 @@ import GHC.Read
 import GHC.Enum
 import GHC.Arr
 
--- | A concrete, poly-kinded proxy type
+-- $setup
+-- >>> import Data.Void
+-- >>> import Prelude
+
+-- | 'Proxy' is a type that holds no data, but has a phantom parameter of
+-- arbitrary type (or even kind). Its use is to provide type information, even
+-- though there is no value available of that type (or it may be too costly to
+-- create one).
+--
+-- Historically, @'Proxy' :: 'Proxy' a@ is a safer alternative to the
+-- @'undefined :: a'@ idiom.
+--
+-- >>> Proxy :: Proxy (Void, Int -> Int)
+-- Proxy
+--
+-- Proxy can even hold types of higher kinds,
+--
+-- >>> Proxy :: Proxy Either
+-- Proxy
+--
+-- >>> Proxy :: Proxy Functor
+-- Proxy
+--
+-- >>> Proxy :: Proxy complicatedStructure
+-- Proxy
 data Proxy t = Proxy deriving Bounded
 
 -- | A concrete, promotable proxy type, for use at the kind level
@@ -113,6 +137,19 @@ instance MonadPlus Proxy
 -- 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 tag
 -- of the second.
+--
+-- >>> import Data.Word
+-- >>> :type asProxyTypeOf 123 (Proxy :: Proxy Word8)
+-- asProxyTypeOf 123 (Proxy :: Proxy Word8) :: Word8
+--
+-- Note the lower-case @proxy@ in the definition. This allows any type
+-- constructor with just one argument to be passed to the function, for example
+-- we could also write
+--
+-- >>> import Data.Word
+-- >>> :type asProxyTypeOf 123 (Just (undefined :: Word8))
+-- asProxyTypeOf 123 (Just (undefined :: Word8)) :: Word8
 asProxyTypeOf :: a -> proxy a -> a
 asProxyTypeOf = const
 {-# INLINE asProxyTypeOf #-}
+
diff --git a/libraries/base/Data/STRef.hs b/libraries/base/Data/STRef.hs
index 60bccf50cb..46ca08361b 100644
--- a/libraries/base/Data/STRef.hs
+++ b/libraries/base/Data/STRef.hs
@@ -5,7 +5,7 @@
 -- Module      :  Data.STRef
 -- Copyright   :  (c) The University of Glasgow 2001
 -- License     :  BSD-style (see the file libraries/base/LICENSE)
--- 
+--
 -- Maintainer  :  libraries@haskell.org
 -- Stability   :  experimental
 -- Portability :  non-portable (uses Control.Monad.ST)
@@ -29,16 +29,30 @@ import GHC.STRef
 
 -- | Mutate the contents of an 'STRef'.
 --
+-- >>> :{
+-- runST (do
+--     ref <- newSTRef ""
+--     modifySTRef ref (const "world")
+--     modifySTRef ref (++ "!")
+--     modifySTRef ref ("Hello, " ++)
+--     readSTRef ref )
+-- :}
+-- "Hello, world!"
+--
 -- Be warned that 'modifySTRef' does not apply the function strictly.  This
 -- means if the program calls 'modifySTRef' many times, but seldomly uses the
 -- value, thunks will pile up in memory resulting in a space leak.  This is a
 -- common mistake made when using an STRef as a counter.  For example, the
--- following will leak memory and likely produce a stack overflow:
+-- following will leak memory and may produce a stack overflow:
 --
--- >print $ runST $ do
--- >    ref <- newSTRef 0
--- >    replicateM_ 1000000 $ modifySTRef ref (+1)
--- >    readSTRef ref
+-- >>> import Control.Monad (replicateM_)
+-- >>> :{
+-- print (runST (do
+--     ref <- newSTRef 0
+--     replicateM_ 1000 $ modifySTRef ref (+1)
+--     readSTRef ref ))
+-- :}
+-- 1000
 --
 -- To avoid this problem, use 'modifySTRef'' instead.
 modifySTRef :: STRef s a -> (a -> a) -> ST s ()
diff --git a/libraries/base/Data/Unique.hs b/libraries/base/Data/Unique.hs
index 2db9247572..eef6256395 100644
--- a/libraries/base/Data/Unique.hs
+++ b/libraries/base/Data/Unique.hs
@@ -6,7 +6,7 @@
 -- Module      :  Data.Unique
 -- Copyright   :  (c) The University of Glasgow 2001
 -- License     :  BSD-style (see the file libraries/base/LICENSE)
--- 
+--
 -- Maintainer  :  libraries@haskell.org
 -- Stability   :  experimental
 -- Portability :  non-portable
@@ -30,6 +30,15 @@ import Data.IORef
 
 -- | An abstract unique object.  Objects of type 'Unique' may be
 -- compared for equality and ordering and hashed into 'Int'.
+--
+-- >>> :{
+-- do x <- newUnique
+--    print (x == x)
+--    y <- newUnique
+--    print (x == y)
+-- :}
+-- True
+-- False
 newtype Unique = Unique Integer deriving (Eq,Ord)
 
 uniqSource :: IORef Integer
diff --git a/libraries/base/Debug/Trace.hs b/libraries/base/Debug/Trace.hs
index 40475d32f9..3d49dd22ba 100644
--- a/libraries/base/Debug/Trace.hs
+++ b/libraries/base/Debug/Trace.hs
@@ -55,6 +55,9 @@ import GHC.Show
 import GHC.Stack
 import Data.List
 
+-- $setup
+-- >>> import Prelude
+
 -- $tracing
 --
 -- The 'trace', 'traceShow' and 'traceIO' functions print messages to an output
@@ -104,7 +107,10 @@ before returning the second argument as its result.
 
 For example, this returns the value of @f x@ but first outputs the message.
 
-> trace ("calling f with x = " ++ show x) (f x)
+>>> let x = 123; f = show
+>>> trace ("calling f with x = " ++ show x) (f x)
+"calling f with x = 123
+123"
 
 The 'trace' function should /only/ be used for debugging, or for monitoring
 execution. The function is not referentially transparent: its type indicates
@@ -119,6 +125,10 @@ trace string expr = unsafePerformIO $ do
 {-|
 Like 'trace' but returns the message instead of a third value.
 
+>>> traceId "hello"
+"hello
+hello"
+
 @since 4.7.0.0
 -}
 traceId :: String -> String
@@ -129,23 +139,26 @@ Like 'trace', but uses 'show' on the argument to convert it to a 'String'.
 
 This makes it convenient for printing the values of interesting variables or
 expressions inside a function. For example here we print the value of the
-variables @x@ and @z@:
+variables @x@ and @y@:
+
+>>> let f x y = traceShow (x,y) (x + y) in f (1+2) 5
+(3,5)
+8
 
-> f x y =
->     traceShow (x, z) $ result
->   where
->     z = ...
->     ...
 -}
-traceShow :: (Show a) => a -> b -> b
+traceShow :: Show a => a -> b -> b
 traceShow = trace . show
 
 {-|
 Like 'traceShow' but returns the shown value instead of a third value.
 
+>>> traceShowId (1+2+3, "hello" ++ "world")
+(6,"helloworld")
+(6,"helloworld")
+
 @since 4.7.0.0
 -}
-traceShowId :: (Show a) => a -> a
+traceShowId :: Show a => a -> a
 traceShowId a = trace (show a) a
 
 {-|
@@ -159,25 +172,37 @@ the @do@-block is executed, @traceM "not crashed"@ would only be reduced once,
 and the message would only be printed once.  If your monad is in 'MonadIO',
 @liftIO . traceIO@ may be a better option.
 
-> ... = do
->   x <- ...
->   traceM $ "x: " ++ show x
->   y <- ...
->   traceM $ "y: " ++ show y
+>>> :{
+do
+    x <- Just 3
+    traceM ("x: " ++ show x)
+    y <- pure 12
+    traceM ("y: " ++ show y)
+    pure (x*2 + y)
+:}
+x: 3
+y: 12
+Just 18
 
 @since 4.7.0.0
 -}
-traceM :: (Applicative f) => String -> f ()
+traceM :: Applicative f => String -> f ()
 traceM string = trace string $ pure ()
 
 {-|
 Like 'traceM', but uses 'show' on the argument to convert it to a 'String'.
 
-> ... = do
->   x <- ...
->   traceShowM $ x
->   y <- ...
->   traceShowM $ x + y
+>>> :{
+do
+    x <- Just 3
+    traceShowM x
+    y <- pure 12
+    traceShowM y
+    pure (x*2 + y)
+:}
+3
+12
+Just 18
 
 @since 4.7.0.0
 -}
diff --git a/libraries/base/GHC/Base.hs b/libraries/base/GHC/Base.hs
index e62ac922cc..b880ccb12f 100644
--- a/libraries/base/GHC/Base.hs
+++ b/libraries/base/GHC/Base.hs
@@ -428,6 +428,8 @@ class  Functor f  where
 --
 --   * @('<*>') = 'ap'@
 --
+--   * @('*>') = ('>>')@
+--
 -- (which implies that 'pure' and '<*>' satisfy the applicative functor laws).
 
 class Functor f => Applicative f where
@@ -630,8 +632,8 @@ liftM f m1              = do { x1 <- m1; return (f x1) }
 -- | Promote a function to a monad, scanning the monadic arguments from
 -- left to right.  For example,
 --
--- >    liftM2 (+) [0,1] [0,2] = [0,2,1,3]
--- >    liftM2 (+) (Just 1) Nothing = Nothing
+-- > liftM2 (+) [0,1] [0,2] = [0,2,1,3]
+-- > liftM2 (+) (Just 1) Nothing = Nothing
 --
 liftM2  :: (Monad m) => (a1 -> a2 -> r) -> m a1 -> m a2 -> m r
 liftM2 f m1 m2          = do { x1 <- m1; x2 <- m2; return (f x1 x2) }
@@ -672,11 +674,11 @@ liftM5 f m1 m2 m3 m4 m5 = do { x1 <- m1; x2 <- m2; x3 <- m3; x4 <- m4; x5 <- m5;
 {- | In many situations, the 'liftM' operations can be replaced by uses of
 'ap', which promotes function application.
 
->       return f `ap` x1 `ap` ... `ap` xn
+> return f `ap` x1 `ap` ... `ap` xn
 
 is equivalent to
 
->       liftMn f x1 x2 ... xn
+> liftMn f x1 x2 ... xn
 
 -}
 
@@ -745,9 +747,9 @@ infixl 3 <|>
 -- If defined, 'some' and 'many' should be the least solutions
 -- of the equations:
 --
--- * @some v = (:) '<$>' v '<*>' many v@
+-- * @'some' v = (:) '<$>' v '<*>' 'many' v@
 --
--- * @many v = some v '<|>' 'pure' []@
+-- * @'many' v = 'some' v '<|>' 'pure' []@
 class Applicative f => Alternative f where
     -- | The identity of '<|>'
     empty :: f a
@@ -1083,6 +1085,8 @@ maxInt  = I# 0x7FFFFFFFFFFFFFFF#
 ----------------------------------------------
 
 -- | Identity function.
+--
+-- > id x = x
 id                      :: a -> a
 id x                    =  x
 
@@ -1116,7 +1120,8 @@ breakpointCond _ r = r
 data Opaque = forall a. O a
 -- | @const x@ is a unary function which evaluates to @x@ for all inputs.
 --
--- For instance,
+-- >>> const 42 "hello"
+-- 42
 --
 -- >>> map (const 42) [0..3]
 -- [42,42,42,42]
@@ -1131,6 +1136,9 @@ const x _               =  x
 (.) f g = \x -> f (g x)
 
 -- | @'flip' f@ takes its (first) two arguments in the reverse order of @f@.
+--
+-- >>> flip (++) "hello" "world"
+-- "worldhello"
 flip                    :: (a -> b -> c) -> b -> a -> c
 flip f x y              =  f y x
 
@@ -1139,7 +1147,7 @@ flip f x y              =  f y x
 -- low, right-associative binding precedence, so it sometimes allows
 -- parentheses to be omitted; for example:
 --
--- >     f $ g $ h x  =  f (g (h x))
+-- > 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@.
diff --git a/libraries/base/GHC/Natural.hs b/libraries/base/GHC/Natural.hs
index 13560850af..99cfb8f396 100644
--- a/libraries/base/GHC/Natural.hs
+++ b/libraries/base/GHC/Natural.hs
@@ -86,8 +86,13 @@ underflowError = raise# underflowException
 
 -- | Type representing arbitrary-precision non-negative integers.
 --
--- Operations whose result would be negative
--- @'throw' ('Underflow' :: 'ArithException')@.
+-- >>> 2^20 :: Natural
+-- 1267650600228229401496703205376
+--
+-- Operations whose result would be negative @'throw' ('Underflow' :: 'ArithException')@,
+--
+-- >>> -1 :: Natural
+-- *** Exception: arithmetic underflow
 --
 -- @since 4.8.0.0
 data Natural = NatS#                 GmpLimb# -- ^ in @[0, maxBound::Word]@
diff --git a/libraries/base/GHC/STRef.hs b/libraries/base/GHC/STRef.hs
index a6e4292ddb..6ee9e7bab7 100644
--- a/libraries/base/GHC/STRef.hs
+++ b/libraries/base/GHC/STRef.hs
@@ -24,9 +24,21 @@ module GHC.STRef (
 import GHC.ST
 import GHC.Base
 
+-- $setup
+-- import Prelude
+
 data STRef s a = STRef (MutVar# s a)
 -- ^ a value of type @STRef s a@ is a mutable variable in state thread @s@,
 -- containing a value of type @a@
+--
+-- >>> :{
+-- runST (do
+--     ref <- newSTRef "hello"
+--     x <- readSTRef ref
+--     writeSTRef ref (x ++ "world")
+--     readSTRef ref )
+-- :}
+-- "helloworld"
 
 -- |Build a new 'STRef' in the current state thread
 newSTRef :: a -> ST s (STRef s a)
diff --git a/libraries/base/Numeric.hs b/libraries/base/Numeric.hs
index e8b0b91eed..e040c455d6 100644
--- a/libraries/base/Numeric.hs
+++ b/libraries/base/Numeric.hs
@@ -81,15 +81,24 @@ readInt :: Num a
 readInt base isDigit valDigit = readP_to_S (L.readIntP base isDigit valDigit)
 
 -- | Read an unsigned number in octal notation.
+--
+-- >>> readOct "0644"
+-- [(420,"")]
 readOct :: (Eq a, Num a) => ReadS a
 readOct = readP_to_S L.readOctP
 
 -- | Read an unsigned number in decimal notation.
+--
+-- >>> readDec "0644"
+-- [(644,"")]
 readDec :: (Eq a, Num a) => ReadS a
 readDec = readP_to_S L.readDecP
 
 -- | Read an unsigned number in hexadecimal notation.
 -- Both upper or lower case letters are allowed.
+--
+-- >>> readHex "deadbeef"
+-- [(3735928559,"")]
 readHex :: (Eq a, Num a) => ReadS a
 readHex = readP_to_S L.readHexP
 
diff --git a/libraries/base/System/Timeout.hs b/libraries/base/System/Timeout.hs
index d34082e64f..06d6e5f8fb 100644
--- a/libraries/base/System/Timeout.hs
+++ b/libraries/base/System/Timeout.hs
@@ -53,6 +53,12 @@ instance Exception Timeout where
 -- timeout interval means \"wait indefinitely\". When specifying long timeouts,
 -- be careful not to exceed @maxBound :: Int@.
 --
+-- >>> timeout 1000000 (threadDelay 1000 *> pure "finished on time")
+-- Just "finished on time"
+--
+-- >>> timeout 10000 (threadDelay 100000 *> pure "finished on time")
+-- Nothing
+--
 -- The design of this combinator was guided by the objective that @timeout n f@
 -- should behave exactly the same as @f@ as long as @f@ doesn't time out. This
 -- means that @f@ has the same 'myThreadId' it would have without the timeout
@@ -75,7 +81,6 @@ instance Exception Timeout where
 -- because the runtime system uses scheduling mechanisms like @select(2)@ to
 -- perform asynchronous I\/O, so it is possible to interrupt standard socket
 -- I\/O or file I\/O using this combinator.
-
 timeout :: Int -> IO a -> IO (Maybe a)
 timeout n f
     | n <  0    = fmap Just f
diff --git a/libraries/base/Text/Printf.hs b/libraries/base/Text/Printf.hs
index 0914aa7b5c..177e8f2230 100644
--- a/libraries/base/Text/Printf.hs
+++ b/libraries/base/Text/Printf.hs
@@ -102,6 +102,10 @@ import System.IO
 -------------------
 
 -- | Format a variable number of arguments with the C-style formatting string.
+--
+-- >>> printf "%s, %d, %.4f" "hello" 123 pi
+-- hello, 123, 3.1416
+--
 -- The return value is either 'String' or @('IO' a)@ (which
 -- should be @('IO' '()')@, but Haskell's type system
 -- makes this hard).
@@ -133,11 +137,11 @@ import System.IO
 -- A conversion specification begins with the
 -- character @%@, followed by zero or more of the following flags:
 --
--- >    -      left adjust (default is right adjust)
--- >    +      always use a sign (+ or -) for signed conversions
--- >    space  leading space for positive numbers in signed conversions
--- >    0      pad with zeros rather than spaces
--- >    #      use an \"alternate form\": see below
+-- > -      left adjust (default is right adjust)
+-- > +      always use a sign (+ or -) for signed conversions
+-- > space  leading space for positive numbers in signed conversions
+-- > 0      pad with zeros rather than spaces
+-- > #      use an \"alternate form\": see below
 --
 -- When both flags are given, @-@ overrides @0@ and @+@ overrides space.
 -- A negative width specifier in a @*@ conversion is treated as
@@ -146,32 +150,32 @@ import System.IO
 -- The \"alternate form\" for unsigned radix conversions is
 -- as in C @printf(3)@:
 --
--- >    %o           prefix with a leading 0 if needed
--- >    %x           prefix with a leading 0x if nonzero
--- >    %X           prefix with a leading 0X if nonzero
--- >    %b           prefix with a leading 0b if nonzero
--- >    %[eEfFgG]    ensure that the number contains a decimal point
+-- > %o           prefix with a leading 0 if needed
+-- > %x           prefix with a leading 0x if nonzero
+-- > %X           prefix with a leading 0X if nonzero
+-- > %b           prefix with a leading 0b if nonzero
+-- > %[eEfFgG]    ensure that the number contains a decimal point
 --
 -- Any flags are followed optionally by a field width:
 --
--- >    num    field width
--- >    *      as num, but taken from argument list
+-- > num    field width
+-- > *      as num, but taken from argument list
 --
 -- The field width is a minimum, not a maximum: it will be
 -- expanded as needed to avoid mutilating a value.
 --
 -- Any field width is followed optionally by a precision:
 --
--- >    .num   precision
--- >    .      same as .0
--- >    .*     as num, but taken from argument list
+-- > .num   precision
+-- > .      same as .0
+-- > .*     as num, but taken from argument list
 --
 -- Negative precision is taken as 0. The meaning of the
 -- precision depends on the conversion type.
 --
--- >    Integral    minimum number of digits to show
--- >    RealFloat   number of digits after the decimal point
--- >    String      maximum number of characters
+-- > Integral    minimum number of digits to show
+-- > RealFloat   number of digits after the decimal point
+-- > String      maximum number of characters
 --
 -- The precision for Integral types is accomplished by zero-padding.
 -- If both precision and zero-pad are given for an Integral field,
@@ -182,29 +186,29 @@ import System.IO
 -- to set the implicit size of the operand for conversion of
 -- a negative operand to unsigned:
 --
--- >    hh     Int8
--- >    h      Int16
--- >    l      Int32
--- >    ll     Int64
--- >    L      Int64
+-- > hh     Int8
+-- > h      Int16
+-- > l      Int32
+-- > ll     Int64
+-- > L      Int64
 --
 -- The specification ends with a format character:
 --
--- >    c      character               Integral
--- >    d      decimal                 Integral
--- >    o      octal                   Integral
--- >    x      hexadecimal             Integral
--- >    X      hexadecimal             Integral
--- >    b      binary                  Integral
--- >    u      unsigned decimal        Integral
--- >    f      floating point          RealFloat
--- >    F      floating point          RealFloat
--- >    g      general format float    RealFloat
--- >    G      general format float    RealFloat
--- >    e      exponent format float   RealFloat
--- >    E      exponent format float   RealFloat
--- >    s      string                  String
--- >    v      default format          any type
+-- > c      character               Integral
+-- > d      decimal                 Integral
+-- > o      octal                   Integral
+-- > x      hexadecimal             Integral
+-- > X      hexadecimal             Integral
+-- > b      binary                  Integral
+-- > u      unsigned decimal        Integral
+-- > f      floating point          RealFloat
+-- > F      floating point          RealFloat
+-- > g      general format float    RealFloat
+-- > G      general format float    RealFloat
+-- > e      exponent format float   RealFloat
+-- > E      exponent format float   RealFloat
+-- > s      string                  String
+-- > v      default format          any type
 --
 -- The \"%v\" specifier is provided for all built-in types,
 -- and should be provided for user-defined type formatters
@@ -212,11 +216,11 @@ import System.IO
 -- type. For the built-in types the \"%v\" specifier is
 -- converted as follows:
 --
--- >    c      Char
--- >    u      other unsigned Integral
--- >    d      other signed Integral
--- >    g      RealFloat
--- >    s      String
+-- > c      Char
+-- > u      other unsigned Integral
+-- > d      other signed Integral
+-- > g      RealFloat
+-- > s      String
 --
 -- Mismatch between the argument types and the format
 -- string, as well as any other syntactic or semantic errors
@@ -246,16 +250,6 @@ import System.IO
 --
 -- * Haskell 'printf' will place a zero after a decimal point when
 --   possible.
---
--- ==== __Examples__
---
--- >   > printf "%d\n" (23::Int)
--- >   23
--- >   > printf "%s %s\n" "Hello" "World"
--- >   Hello World
--- >   > printf "%.2f\n" pi
--- >   3.14
---
 printf :: (PrintfType r) => String -> r
 printf fmts = spr fmts []
 
diff --git a/libraries/base/Text/Read.hs b/libraries/base/Text/Read.hs
index 2479eb529a..c79b7c15b2 100644
--- a/libraries/base/Text/Read.hs
+++ b/libraries/base/Text/Read.hs
@@ -62,6 +62,12 @@ reads = readsPrec minPrec
 -- Succeeds if there is exactly one valid result.
 -- A 'Left' value indicates a parse error.
 --
+-- >>> readEither "123" :: Either String Int
+-- Right 123
+--
+-- >>> readEither "hello" :: Either String Int
+-- Left "Prelude.read: no parse"
+--
 -- @since 4.6.0.0
 readEither :: Read a => String -> Either String a
 readEither s =
@@ -78,6 +84,12 @@ readEither s =
 -- | Parse a string using the 'Read' instance.
 -- Succeeds if there is exactly one valid result.
 --
+-- >>> readMaybe "123" :: Maybe Int
+-- Just 123
+--
+-- >>> readMaybe "hello" :: Maybe Int
+-- Nothing
+--
 -- @since 4.6.0.0
 readMaybe :: Read a => String -> Maybe a
 readMaybe s = case readEither s of
@@ -85,6 +97,14 @@ readMaybe s = case readEither s of
                 Right a -> Just a
 
 -- | The 'read' function reads input from a string, which must be
--- completely consumed by the input process.
+-- completely consumed by the input process. 'read' fails with an 'error' if the
+-- parse is unsuccessful, and it is therefore discouraged from being used in
+-- real applications. Use 'readMaybe' or 'readEither' for safe alternatives.
+--
+-- >>> read "123" :: Int
+-- 123
+--
+-- >>> read "hello" :: Int
+-- *** Exception: Prelude.read: no parse
 read :: Read a => String -> a
 read s = either errorWithoutStackTrace id (readEither s)