From 263380d225508c7f3d4afc74fed427a08d2e132d Mon Sep 17 00:00:00 2001
From: simonmar <unknown>
Date: Tue, 28 May 2002 16:33:02 +0000
Subject: [PATCH] [project @ 2002-05-28 16:32:45 by simonmar] Documentation

---
 Data/PackedString.hs |   34 ++++++++++++++++++++++++++--------
 Data/Unique.hs       |   12 +++++++++++-
 2 files changed, 37 insertions(+), 9 deletions(-)

diff --git a/Data/PackedString.hs b/Data/PackedString.hs
index d2998bd..f276d14 100644
--- a/Data/PackedString.hs
+++ b/Data/PackedString.hs
@@ -8,23 +8,26 @@
 -- Stability   :  experimental
 -- Portability :  portable
 --
--- The PackedString type, and associated operations.
+-- An efficient implementation of strings.
 --
+-----------------------------------------------------------------------------
+
 -- Original GHC implementation by Bryan O\'Sullivan, 
 -- rewritten to use UArray by Simon Marlow.
---
------------------------------------------------------------------------------
 
 module Data.PackedString (
+	-- * The @PackedString@ type
         PackedString,      -- abstract, instances: Eq, Ord, Show, Typeable
 
-         -- Creating the beasts
-	packString,  -- :: [Char] -> PackedString
-	unpackPS,    -- :: PackedString -> [Char]
+         -- * Converting to and from @PackedString@s
+	packString,  -- :: String -> PackedString
+	unpackPS,    -- :: PackedString -> String
 
+	-- * I\/O with @PackedString@s	
 	hPutPS,      -- :: Handle -> PackedString -> IO ()
 	hGetPS,      -- :: Handle -> Int -> IO PackedString
 
+	-- * List-like manipulation functions
 	nilPS,       -- :: PackedString
 	consPS,      -- :: Char -> PackedString -> PackedString
 	headPS,      -- :: PackedString -> Char
@@ -71,6 +74,8 @@ import System.IO
 -- -----------------------------------------------------------------------------
 -- PackedString type declaration
 
+-- | A space-efficient representation of a 'String', which supports various
+-- efficient operations.  A 'PackedString' contains full Unicode 'Char's.
 newtype PackedString = PS (UArray Int Char)
 
 instance Eq PackedString where
@@ -96,7 +101,8 @@ nilPS = PS (array (0,-1) [])
 consPS :: Char -> PackedString -> PackedString
 consPS c cs = packString (c : (unpackPS cs)) -- ToDo:better
 
-packString :: [Char] -> PackedString
+-- | Convert a 'String' into a 'PackedString'
+packString :: String -> PackedString
 packString str = packNChars (length str) str
 
 packNChars :: Int -> [Char] -> PackedString
@@ -105,7 +111,8 @@ packNChars len str = PS (array (0,len-1) (zip [0..] str))
 -- -----------------------------------------------------------------------------
 -- Destructor functions (taking PackedStrings apart)
 
-unpackPS :: PackedString -> [Char]
+-- | Convert a 'PackedString' into a 'String'
+unpackPS :: PackedString -> String
 unpackPS (PS ps) = elems ps
 
 -- -----------------------------------------------------------------------------
@@ -253,6 +260,11 @@ substrPS (PS ps) begin end = packString [ ps ! i | i <- [begin..end] ]
 -- -----------------------------------------------------------------------------
 -- hPutPS
 
+-- | Outputs a 'PackedString' to the specified 'Handle'.  
+--
+-- NOTE: the representation of the 'PackedString' in the file is assumed to
+-- be in the ISO-8859-1 encoding.  In other words, only the least signficant
+-- byte is taken from each character in the 'PackedString'.
 hPutPS :: Handle -> PackedString -> IO ()
 hPutPS h (PS ps) = do
   let l = lengthPS (PS ps)
@@ -263,6 +275,12 @@ hPutPS h (PS ps) = do
 -- -----------------------------------------------------------------------------
 -- hGetPS
 
+-- | Read a 'PackedString' directly from the specified 'Handle'.  This
+-- is far more efficient than reading the characters into a 'String'
+-- and then using 'packString'.  
+--
+-- NOTE: as with 'hPutPS', the string representation in the file is 
+-- assumed to be ISO-8859-1.
 hGetPS :: Handle -> Int -> IO PackedString
 hGetPS h i = do
   arr <- newArray_ (0, i-1)
diff --git a/Data/Unique.hs b/Data/Unique.hs
index 81fe6d8..a5a96f6 100644
--- 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
-- 
1.7.10.4