[project @ 2002-05-28 16:32:45 by simonmar]

[ghc-base.git] / Data / Unique.hs

diff --git a/Data/Unique.hs b/Data/Unique.hs
index 81fe6d8..a5a96f6 100644 (file)
--- a/Data/Unique.hs
+++ b/Data/Unique.hs
@@ -8,11 +8,12 @@
 -- Stability   :  experimental
 -- Portability :  non-portable
 --
--- An infinite supply of unique objects, supporting ordering and equality.
+-- An abstract interface to a unique symbol generator.
 --
 -----------------------------------------------------------------------------
 
 module Data.Unique (
+   -- * Unique objects
    Unique,             -- instance (Eq, Ord)
    newUnique,          -- :: IO Unique
    hashUnique          -- :: Unique -> Int
@@ -28,12 +29,18 @@ import GHC.Base
 import GHC.Num         ( Integer(..) )
 #endif
 
+-- | An abstract unique object.  Objects of type 'Unique' may be
+-- compared for equality and ordering and hashed into 'Int'.
 newtype Unique = Unique Integer deriving (Eq,Ord)
 
 uniqSource :: MVar Integer
 uniqSource = unsafePerformIO (newMVar 0)
 {-# NOINLINE uniqSource #-}
 
+-- | Creates a new object of type 'Unique'.  The value returned will
+-- not compare equal to any other value of type 'Unique' returned by
+-- previous calls to 'newUnique'.  There is no limit on the number of
+-- times 'newUnique' may be called.
 newUnique :: IO Unique
 newUnique = do
    val <- takeMVar uniqSource
@@ -41,6 +48,9 @@ newUnique = do
    putMVar uniqSource next
    return (Unique next)
 
+-- | Hashes a 'Unique' into an 'Int'.  Two 'Unique's may hash to the
+-- same value, although in practice this is unlikely.  The 'Int'
+-- returned makes a good hash key.
 hashUnique :: Unique -> Int
 #ifdef __GLASGOW_HASKELL__ 
 hashUnique (Unique (S# i))   = I# i