From: ross <unknown>
Date: Fri, 10 Sep 2004 20:38:53 +0000 (+0000)
Subject: [project @ 2004-09-10 20:38:53 by ross]
X-Git-Tag: nhc98-1-18-release~251
X-Git-Url: http://git.megacz.com/?a=commitdiff_plain;h=f158833ab231d7532328591acf57c590091f79f1;p=ghc-base.git

[project @ 2004-09-10 20:38:53 by ross]
docs
---

diff --git a/Control/Monad/Fix.hs b/Control/Monad/Fix.hs
index dad6264..b66a6ce 100644
--- a/Control/Monad/Fix.hs
+++ b/Control/Monad/Fix.hs
@@ -8,13 +8,10 @@
 -- Stability   :  experimental
 -- Portability :  portable
 --
--- The Fix monad.
+-- Monadic fixpoints.
 --
---	  Inspired by the paper
---	  /Functional Programming with Overloading and
---	      Higher-Order Polymorphism/, 
---	    Mark P Jones (<http://www.cse.ogi.edu/~mpj/>)
---		  Advanced School of Functional Programming, 1995.
+-- For more details, see Levent Erkok's thesis,
+-- /Value Recursion in Monadic Computations/, 2002.
 --
 -----------------------------------------------------------------------------
 
@@ -28,10 +25,33 @@ module Control.Monad.Fix (
 import Prelude
 import System.IO
 
+-- | @'fix' f@ is the least fixed point of the function @f@.
 fix :: (a -> a) -> a
 fix f = let x = f x in x
 
+-- | Monads having fixed points with a \`knot-tying\' semantics.
+-- Instances of 'MonadFix' should satisfy the laws
+--
+-- [purity]
+--	@'mfix' ('return' . h)  =  'return' ('fix' h)@
+--
+-- [left shrinking (or tightening)]
+--	@'mfix' (\x -> a >>= \y -> f x y)  =  \y -> 'mfix' (\x -> f x y)@
+--
+-- [sliding]
+--	@'mfix' ('Control.Monad.liftM' h . f)  =  'Control.Monad.liftM' h ('mfix' (f . h))@,
+--	for strict @h@.
+--
+-- [nesting]
+--	@'mfix' (\x -> 'mfix' (\y -> f x y))  =  'mfix' (\x -> f x x)@
+--
+-- This class is used in the translation of the recursive @do@ notation
+-- supported by GHC and Hugs.
 class (Monad m) => MonadFix m where
+	-- | The fixed point of a monadic computation.
+	-- @'mfix' f@ executes the action 'f' only once, with the eventual
+	-- output fed back as the input.  Hence @f@ should not be strict,
+	-- for then @'mfix' f@ would diverge.
 	mfix :: (a -> m a) -> m a
 
 -- Instances of MonadFix for Prelude monads