[commit: ghc] master: base: Add examples to Bifunctor documentation (275ac8e)

[git at git.haskell.org]

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

On branch  : master
Link       : http://ghc.haskell.org/trac/ghc/changeset/275ac8ef0a0081f16abbfb8934e10cf271573768/ghc

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

commit 275ac8ef0a0081f16abbfb8934e10cf271573768
Author: Julie Moronuki <jdog74 at gmail.com>
Date:   Tue Oct 31 23:28:46 2017 -0400

    base: Add examples to Bifunctor documentation


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

275ac8ef0a0081f16abbfb8934e10cf271573768
 libraries/base/Data/Bifunctor.hs | 37 ++++++++++++++++++++++++++++++++++++-
 1 file changed, 36 insertions(+), 1 deletion(-)

diff --git a/libraries/base/Data/Bifunctor.hs b/libraries/base/Data/Bifunctor.hs
index 5441605..04de5ad 100644
--- a/libraries/base/Data/Bifunctor.hs
+++ b/libraries/base/Data/Bifunctor.hs
@@ -20,7 +20,15 @@ module Data.Bifunctor
 import Control.Applicative  ( Const(..) )
 import GHC.Generics ( K1(..) )
 
--- | Formally, the class 'Bifunctor' represents a bifunctor
+-- | A bifunctor is a type constructor that takes
+-- two type arguments and is a functor in /both/ arguments. That
+-- is, unlike with 'Functor', a type constructor such as 'Either'
+-- does not need to be partially applied for a 'Bifunctor'
+-- instance, and the methods in this class permit mapping
+-- functions over the 'Left' value or the 'Right' value,
+-- or both at the same time.
+--
+-- Formally, the class 'Bifunctor' represents a bifunctor
 -- from @Hask@ -> @Hask at .
 --
 -- Intuitively it is a bifunctor where both the first and second
@@ -59,22 +67,49 @@ class Bifunctor p where
     -- | Map over both arguments at the same time.
     --
     -- @'bimap' f g ≡ 'first' f '.' 'second' g@
+    --
+    -- ==== __Examples__
+    -- >>> bimap toUpper (+1) ('j', 3)
+    -- ('J',4)
+    --
+    -- >>> bimap toUpper (+1) (Left 'j')
+    -- Left 'J'
+    --
+    -- >>> bimap toUpper (+1) (Right 3)
+    -- Right 4
     bimap :: (a -> b) -> (c -> d) -> p a c -> p b d
     bimap f g = first f . second g
 
+
     -- | Map covariantly over the first argument.
     --
     -- @'first' f ≡ 'bimap' f 'id'@
+    --
+    -- ==== __Examples__
+    -- >>> first toUpper ('j', 3)
+    -- ('J',3)
+    --
+    -- >>> first toUpper (Left 'j')
+    -- Left 'J'
     first :: (a -> b) -> p a c -> p b c
     first f = bimap f id
 
+
     -- | Map covariantly over the second argument.
     --
     -- @'second' ≡ 'bimap' 'id'@
+    --
+    -- ==== __Examples__
+    -- >>> second (+1) ('j', 3)
+    -- ('j',4)
+    --
+    -- >>> second (+1) (Right 3)
+    -- Right 4
     second :: (b -> c) -> p a b -> p a c
     second = bimap id
 
 
+
 -- | @since 4.8.0.0
 instance Bifunctor (,) where
     bimap f g ~(a, b) = (f a, g b)