Add laws to MonadReader

Author: Lysxia

Control/Monad/Reader/Class.hs

@@ -69,14 +69,38 @@ import Data.Monoid
 -- class MonadReader
 --  asks for the internal (non-mutable) state.
 
--- | See examples in "Control.Monad.Reader".
+-- | Monads with a notion of readable environment.
+--
+-- See examples in "Control.Monad.Reader".
 -- Note, the partially applied function type @(->) r@ is a simple reader monad.
 -- See the @instance@ declaration below.
+--
+-- === Laws
+--
+-- @
+-- m '<*>' 'ask'   =   'ask' 'Control.Applicative.<**>' m
+--
+-- 'ask' '>>' 'pure' x   =   'pure' x
+-- 'ask' '>>=' \\s1 -> 'ask' '>>=' \\s2 -> k s1 s2   =   'ask' '>>=' \\s -> k s s
+--
+-- 'local' f 'ask'       = f '<$>' 'ask'
+-- 'local' g '.' 'local' f = 'local' (g '.' f)
+--
+-- -- 'local' is a monad morphism from 'm' to 'm'
+-- 'local' f ('pure' x)  = 'pure' x
+-- 'local' f (a '>>=' k) = 'local' f a '>>=' \\x -> 'local' f (k x)
+--
+-- 'ask' = 'reader' 'id'
+-- @
+--
+-- An equivalent requirement to the first two laws is that 'reader' (as given
+-- by the default implementation) must be a monad morphism from @'Reader' r@
+-- to 'm'.
 class Monad m => MonadReader r m | m -> r where
 #if __GLASGOW_HASKELL__ >= 707
     {-# MINIMAL (ask | reader), local #-}
 #endif
-    -- | Retrieves the monad environment.
+    -- | Retrieves the environment.
     ask   :: m r
     ask = reader id