Loads of doc(test)s

2 files changed, 68 insertions, 54 deletions

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)