[commit: ghc] master: Add doctest examples for Data.Functor. (6825558)

[git at git.haskell.org]

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

On branch  : master
Link       : http://ghc.haskell.org/trac/ghc/changeset/68255588f89462e542c502f6f92548712808032f/ghc

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

commit 68255588f89462e542c502f6f92548712808032f
Author: Michael Orlitzky <michael at orlitzky.com>
Date:   Tue Oct 21 15:02:11 2014 -0500

    Add doctest examples for Data.Functor.
    
    Summary:
    Add doctest examples for the three standalone functions defined in
    Data.Functor:
    
      * Data.Functor.$>
      * Data.Functor.<$>
      * Data.Functor.void
    
    This is part of a larger plan to add examples for the functions in
    base, and to eventually enable automatic testing of them.
    
    Reviewers: austin, hvr, ekmett
    
    Reviewed By: austin
    
    Subscribers: hvr, ekmett, thomie, carter, ezyang, simonmar
    
    Differential Revision: https://phabricator.haskell.org/D352


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

68255588f89462e542c502f6f92548712808032f
 libraries/base/Data/Functor.hs | 105 +++++++++++++++++++++++++++++++++++++++--
 1 file changed, 102 insertions(+), 3 deletions(-)

diff --git a/libraries/base/Data/Functor.hs b/libraries/base/Data/Functor.hs
index 878445f..010ab50 100644
--- a/libraries/base/Data/Functor.hs
+++ b/libraries/base/Data/Functor.hs
@@ -25,9 +25,42 @@ module Data.Functor
 
 import GHC.Base ( Functor(..), const, flip )
 
+-- $setup
+-- Allow the use of Prelude in doctests.
+-- >>> import Prelude
+
 infixl 4 <$>
 
 -- | An infix synonym for 'fmap'.
+--
+--   __Examples__:
+--
+--   Convert from a 'Maybe' 'Int' to a 'Maybe' 'String' using 'show':
+--
+--   >>> show <$> Nothing
+--   Nothing
+--   >>> show <$> Just 3
+--   Just "3"
+--
+--   Convert from an 'Either' 'Int' 'Int' to an 'Either' 'Int'
+--   'String' using 'show':
+--
+--   >>> show <$> Left 17
+--   Left 17
+--   >>> show <$> Right 17
+--   Right "17"
+--
+--   Double each element of a list:
+--
+--   >>> (*2) <$> [1,2,3]
+--   [2,4,6]
+--
+--   Apply 'even' to the second element of a pair:
+--
+--   >>> even <$> (2,2)
+--   (2,True)
+--
+--
 (<$>) :: Functor f => (a -> b) -> f a -> f b
 (<$>) = fmap
 
@@ -35,11 +68,77 @@ infixl 4 $>
 
 -- | Flipped version of '<$'.
 --
--- /Since: 4.7.0.0/
+--   /Since: 4.7.0.0/
+--
+--   __Examples__:
+--
+--   Replace the contents of a 'Maybe' 'Int' with a constant 'String':
+--
+--   >>> Nothing $> "foo"
+--   Nothing
+--   >>> Just 90210 $> "foo"
+--   Just "foo"
+--
+--   Replace the contents of an 'Either' 'Int' 'Int' with a constant
+--   'String', resulting in an 'Either' 'Int' 'String':
+--
+--   >>> Left 8675309 $> "foo"
+--   Left 8675309
+--   >>> Right 8675309 $> "foo"
+--   Right "foo"
+--
+--   Replace each element of a list with a constant 'String':
+--
+--   >>> [1,2,3] $> "foo"
+--   ["foo","foo","foo"]
+--
+--   Replace the second element of a pair with a constant 'String':
+--
+--   >>> (1,2) $> "foo"
+--   (1,"foo")
+--
 ($>) :: Functor f => f a -> b -> f b
 ($>) = flip (<$)
 
--- | @'void' value@ discards or ignores the result of evaluation, such as the
--- return value of an 'IO' action.
+-- | @'void' value@ discards or ignores the result of evaluation, such
+--   as the return value of an 'IO' action.
+--
+--   __Examples__:
+--
+--   Replace the contents of a 'Maybe' 'Int' with unit:
+--
+--   >>> void Nothing
+--   Nothing
+--   >>> void (Just 3)
+--   Just ()
+--
+--    Replace the contents of an 'Either' 'Int' 'Int' with unit,
+--    resulting in an 'Either' 'Int' '()':
+--
+--    >>> void (Left 8675309)
+--    Left 8675309
+--    >>> void (Right 8675309)
+--    Right ()
+--
+--    Replace every element of a list with unit:
+--
+--    >>> void [1,2,3]
+--    [(),(),()]
+--
+--    Replace the second element of a pair with unit:
+--
+--    >>> void (1,2)
+--    (1,())
+--
+--    Discard the result of an 'IO' action:
+--
+--    >>> mapM print [1,2]
+--    1
+--    2
+--    [(),()]
+--    >>> void $ mapM print [1,2]
+--    1
+--    2
+--
 void :: Functor f => f a -> f ()
 void = fmap (const ())