base: Add examples to Bifunctor documentation

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@.
 --
 -- 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)