[commit: ghc] master: Add doctest examples for Data.Bool. (9c464f8)

[git at git.haskell.org]

Repository : ssh://git@git.haskell.org/ghc

On branch  : master
Link       : http://ghc.haskell.org/trac/ghc/changeset/9c464f89b90a6b3fb353341e48b3eecb2381d00e/ghc

>---------------------------------------------------------------

commit 9c464f89b90a6b3fb353341e48b3eecb2381d00e
Author: Michael Orlitzky <michael at orlitzky.com>
Date:   Tue Oct 21 15:02:29 2014 -0500

    Add doctest examples for Data.Bool.
    
    Summary:
    Add examples for `Data.Bool`, and rework the existing documentation of
    the `bool` function slightly: the `a`,`b` in its explanation were changed
    to `x`,`y` to avoid ambiguity with the type variable 'a'.
    
    The examples have been tested, and two trailing spaces were removed.
    
    Reviewers: austin
    
    Reviewed By: austin
    
    Subscribers: thomie, carter, ezyang, simonmar
    
    Differential Revision: https://phabricator.haskell.org/D360


>---------------------------------------------------------------

9c464f89b90a6b3fb353341e48b3eecb2381d00e
 libraries/base/Data/Bool.hs | 31 +++++++++++++++++++++++++++----
 1 file changed, 27 insertions(+), 4 deletions(-)

diff --git a/libraries/base/Data/Bool.hs b/libraries/base/Data/Bool.hs
index deeac80..ace5acf 100644
--- a/libraries/base/Data/Bool.hs
+++ b/libraries/base/Data/Bool.hs
@@ -28,11 +28,34 @@ module Data.Bool (
 
 import GHC.Base
 
--- | Case analysis for the 'Bool' type.
--- @bool a b p@ evaluates to @a@ when @p@ is @False@, and evaluates to @b@
--- when @p@ is @True at .
+-- | Case analysis for the 'Bool' type. @bool x y p@ evaluates to @x@
+--   when @p@ is @False@, and evaluates to @y@ when @p@ is @True at .
+--
+--   This is equivalent to @if p then y else x@; that is, one can
+--   think of it as an if-then-else construct with its arguments
+--   reordered.
+--
+--   /Since: 4.7.0.0/
+--
+--   __Examples__:
+--
+--   Basic usage:
+--
+--   >>> bool "foo" "bar" True
+--   "bar"
+--   >>> bool "foo" "bar" False
+--   "foo"
+--
+--   Confirm that @bool x y p@ and @if p then y else x@ are
+--   equivalent:
+--
+--   >>> let p = True; x = "bar"; y = "foo"
+--   >>> bool x y p == if p then y else x
+--   True
+--   >>> let p = False
+--   >>> bool x y p == if p then y else x
+--   True
 --
--- /Since: 4.7.0.0/
 bool :: a -> a -> Bool -> a
 bool f _ False = f
 bool _ t True  = t