Add doctest examples for Data.Functor.
authorMichael Orlitzky <michael@orlitzky.com>
Tue, 21 Oct 2014 20:02:11 +0000 (15:02 -0500)
committerAustin Seipp <austin@well-typed.com>
Tue, 21 Oct 2014 20:02:12 +0000 (15:02 -0500)
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

libraries/base/Data/Functor.hs

index 878445f..010ab50 100644 (file)
@@ -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 ())