comments for Applicative and Traversable

diff --git a/Control/Applicative.hs b/Control/Applicative.hs
index fa78371..2149b7a 100644 (file)
--- a/Control/Applicative.hs
+++ b/Control/Applicative.hs
@@ -59,6 +59,12 @@ infixl 4 <*>, <*, *>, <**>
 -- [/interchange/]
 --     @u '<*>' 'pure' y = 'pure' ('$' y) '<*>' u@
 --
+-- The 'Functor' instance should satisfy
+--
+-- @
+--     'fmap' f x = 'pure' f '<*>' x
+-- @
+--
 -- If @f@ is also a 'Monad', define @'pure' = 'return'@ and @('<*>') = 'ap'@.
 
 class Functor f => Applicative f where

diff --git a/Data/Traversable.hs b/Data/Traversable.hs
index f8fca1b..1c7d83b 100644 (file)
--- a/Data/Traversable.hs
+++ b/Data/Traversable.hs
@@ -10,9 +10,16 @@
 --
 -- Class of data structures that can be traversed from left to right.
 --
--- See also /Applicative Programming with Effects/,
--- by Conor McBride and Ross Paterson, online at
--- <http://www.soi.city.ac.uk/~ross/papers/Applicative.html>.
+-- See also
+--
+--  * /Applicative Programming with Effects/,
+--    by Conor McBride and Ross Paterson, online at
+--    <http://www.soi.city.ac.uk/~ross/papers/Applicative.html>.
+--
+--  * /The Essence of the Iterator Pattern/,
+--    by Jeremy Gibbons and Bruno Oliveira,
+--    in /Mathematically-Structured Functional Programming/, 2006, and online at
+--    <http://web.comlab.ox.ac.uk/oucl/work/jeremy.gibbons/publications/#iterator>.
 
 module Data.Traversable (
        Traversable(..),
@@ -46,6 +53,15 @@ import Data.Array
 -- This is suitable even for abstract types, as the laws for '<*>'
 -- imply a form of associativity.
 --
+-- The superclass instances should satisfy the following:
+--
+--  * In the 'Functor' instance, 'fmap' should be equivalent to traversal
+--    with the identity applicative functor ('fmapDefault').
+--
+--  * In the 'Foldable' instance, 'Data.Foldable.foldMap' should be
+--    equivalent to traversal with a constant applicative functor
+--    ('foldMapDefault').
+--
 class (Functor t, Foldable t) => Traversable t where
        -- | Map each element of a structure to an action, evaluate
        -- these actions from left to right, and collect the results.