[commit: ghc] master: base: improve Functor documentation (ce47a9c)

[git at git.haskell.org]

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

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

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

commit ce47a9c16f47511575925a6958d167241c4b6c89
Author: Tobias Pflug <tobias.pflug at holidaycheck.com>
Date:   Fri Aug 3 21:17:51 2018 +0200

    base: improve Functor documentation
    
    - Rewrite module documentation
    - Rewrite class documentation


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

ce47a9c16f47511575925a6958d167241c4b6c89
 libraries/base/Data/Functor.hs | 27 +++++++++++++++++++++++++--
 libraries/base/GHC/Base.hs     | 12 +++++-------
 2 files changed, 30 insertions(+), 9 deletions(-)

diff --git a/libraries/base/Data/Functor.hs b/libraries/base/Data/Functor.hs
index 2c0fbc3..4cbfcfc 100644
--- a/libraries/base/Data/Functor.hs
+++ b/libraries/base/Data/Functor.hs
@@ -11,8 +11,31 @@
 -- Stability   :  provisional
 -- Portability :  portable
 --
--- Functors: uniform action over a parameterized type, generalizing the
--- 'Data.List.map' function on lists.
+--
+-- A type @f@ is a Functor if it provides a function @fmap@ which, given any types @a@ and @b@,
+-- lets you apply any function of type @(a -> b)@ to turn an @f a@ into an @f b@, preserving the
+-- structure of @f at .
+--
+-- ==== __Examples__
+--
+--  >>> fmap show (Just 1)  --  (a   -> b)      -> f a       -> f b
+--  Just "1"                --  (Int -> String) -> Maybe Int -> Maybe String
+--
+--  >>> fmap show Nothing   --  (a   -> b)      -> f a       -> f b
+--  Nothing                 --  (Int -> String) -> Maybe Int -> Maybe String
+--
+--  >>> fmap show [1,2,3]   --  (a   -> b)      -> f a       -> f b
+--  ["1", "2", "3"]         --  (Int -> String) -> [Int]     -> [String]
+--
+--  >>> fmap show []        --  (a   -> b)      -> f a       -> f b
+--  []                      --  (Int -> String) -> [Int]     -> [String]
+--
+-- The 'fmap' function is also available as the infix operator '<$>':
+--
+--  >>> fmap show (Just 1) --  (Int -> String) -> Maybe Int -> Maybe String
+--  Just "1"
+--  >>> show <$> (Just 1)  --  (Int -> String) -> Maybe Int -> Maybe String
+--  Just "1"
 
 module Data.Functor
     (
diff --git a/libraries/base/GHC/Base.hs b/libraries/base/GHC/Base.hs
index 4953a7d..efa8d46 100644
--- a/libraries/base/GHC/Base.hs
+++ b/libraries/base/GHC/Base.hs
@@ -444,14 +444,12 @@ instance Semigroup a => Semigroup (IO a) where
 instance Monoid a => Monoid (IO a) where
     mempty = pure mempty
 
-{- | The 'Functor' class is used for types that can be mapped over.
-Instances of 'Functor' should satisfy the following laws:
+{- | A type @f@ is a Functor if it provides a function @fmap@ which, given any types @a@ and @b@
+lets you apply any function from @(a -> b)@ to turn an @f a@ into an @f b@, preserving the
+structure of @f at . Furthermore @f@ needs to adhere to the following laws:
 
-> fmap id  ==  id
-> fmap (f . g)  ==  fmap f . fmap g
-
-The instances of 'Functor' for lists, 'Data.Maybe.Maybe' and 'System.IO.IO'
-satisfy these laws.
+> fmap id == id
+> fmap (f . g) == fmap f . fmap g
 -}
 
 class  Functor f  where