From: Max Bolingbroke <batterseapower@hotmail.com>
Date: Thu, 31 Jul 2008 01:23:34 +0000 (+0000)
Subject: Document UniqSupply
X-Git-Tag: 2008-09-12~313
X-Git-Url: http://git.megacz.com/?p=ghc-hetmet.git;a=commitdiff_plain;h=9d93bcd09efd26fc15c34c5c55dc2862886ca407

Document UniqSupply
---

diff --git a/compiler/basicTypes/UniqSupply.lhs b/compiler/basicTypes/UniqSupply.lhs
index 3db9ddd..774d2d2 100644
--- a/compiler/basicTypes/UniqSupply.lhs
+++ b/compiler/basicTypes/UniqSupply.lhs
@@ -5,21 +5,23 @@
 
 \begin{code}
 module UniqSupply (
-
+        -- * Main data type
         UniqSupply, -- Abstractly
 
+        -- ** Operations on supplies 
         uniqFromSupply, uniqsFromSupply, -- basic ops
+        
+        mkSplitUniqSupply,
+        splitUniqSupply, listSplitUniqSupply,
 
-        UniqSM, -- type: unique supply monad
+        -- * Unique supply monad and its abstraction
+        UniqSM, MonadUnique(..),
+        
+        -- ** Operations on the monad
         initUs, initUs_,
         lazyThenUs, lazyMapUs,
-        mapAndUnzipM,
-        MonadUnique(..),
-
-        mkSplitUniqSupply,
-        splitUniqSupply, listSplitUniqSupply,
 
-        -- Deprecated:
+        -- ** Deprecated operations on 'UniqSM'
         getUniqueUs, getUs, returnUs, thenUs, mapUs
   ) where
 
@@ -39,19 +41,17 @@ unsafeDupableInterleaveIO = unsafeInterleaveIO
 
 \end{code}
 
-
 %************************************************************************
 %*                                                                      *
 \subsection{Splittable Unique supply: @UniqSupply@}
 %*                                                                      *
 %************************************************************************
 
-A value of type @UniqSupply@ is unique, and it can
-supply {\em one} distinct @Unique@.  Also, from the supply, one can
-also manufacture an arbitrary number of further @UniqueSupplies@,
-which will be distinct from the first and from all others.
-
 \begin{code}
+-- | A value of type 'UniqSupply' is unique, and it can
+-- supply /one/ distinct 'Unique'.  Also, from the supply, one can
+-- also manufacture an arbitrary number of further 'UniqueSupply' values,
+-- which will be distinct from the first and from all others.
 data UniqSupply
   = MkSplitUniqSupply FastInt   -- make the Unique with this
                    UniqSupply UniqSupply
@@ -60,11 +60,19 @@ data UniqSupply
 
 \begin{code}
 mkSplitUniqSupply :: Char -> IO UniqSupply
+-- ^ Create a unique supply out of thin air. The character given must
+-- be distinct from those of all calls to this function in the compiler
+-- for the values generated to be truly unique.
 
 splitUniqSupply :: UniqSupply -> (UniqSupply, UniqSupply)
-listSplitUniqSupply :: UniqSupply -> [UniqSupply] -- Infinite
+-- ^ Build two 'UniqSupply' from a single one, each of which
+-- can supply its own 'Unique'.
+listSplitUniqSupply :: UniqSupply -> [UniqSupply]
+-- ^ Create an infinite list of 'UniqSupply' from a single one
 uniqFromSupply  :: UniqSupply -> Unique
+-- ^ Obtain the 'Unique' from this particular 'UniqSupply'
 uniqsFromSupply :: UniqSupply -> [Unique] -- Infinite
+-- ^ Obtain an infinite list of 'Unique' that can be generated by constant splitting of the supply
 \end{code}
 
 \begin{code}
@@ -102,6 +110,7 @@ uniqsFromSupply (MkSplitUniqSupply n _ s2) = mkUniqueGrimily (iBox n) : uniqsFro
 %************************************************************************
 
 \begin{code}
+-- | A monad which just gives the ability to obtain 'Unique's
 newtype UniqSM result = USM { unUSM :: UniqSupply -> (result, UniqSupply) }
 
 instance Monad UniqSM where
@@ -119,10 +128,11 @@ instance Applicative UniqSM where
                             (ff, us')  -> case x us' of
                               (xx, us'') -> (ff xx, us'')
 
--- the initUs function also returns the final UniqSupply; initUs_ drops it
-initUs :: UniqSupply -> UniqSM a -> (a,UniqSupply)
+-- | Run the 'UniqSM' action, returning the final 'UniqSupply'
+initUs :: UniqSupply -> UniqSM a -> (a, UniqSupply)
 initUs init_us m = case unUSM m init_us of { (r,us) -> (r,us) }
 
+-- | Run the 'UniqSM' action, discarding the final 'UniqSupply'
 initUs_ :: UniqSupply -> UniqSM a -> a
 initUs_ init_us m = case unUSM m init_us of { (r, _) -> r }