From f444698bf6b09b2da6a1fec8aecc1eaf37847980 Mon Sep 17 00:00:00 2001
From: ross <unknown>
Date: Wed, 5 Nov 2003 15:05:12 +0000
Subject: [PATCH] [project @ 2003-11-05 15:05:12 by ross] doc updates for
 mallocForeignPtr and friends

---
 Foreign/ForeignPtr.hs |   14 +++++++++++++-
 GHC/ForeignPtr.hs     |   16 ++++++++--------
 2 files changed, 21 insertions(+), 9 deletions(-)

diff --git a/Foreign/ForeignPtr.hs b/Foreign/ForeignPtr.hs
index 8f8f64b..515c0d8 100644
--- a/Foreign/ForeignPtr.hs
+++ b/Foreign/ForeignPtr.hs
@@ -23,6 +23,7 @@ module Foreign.ForeignPtr
 #ifdef __HUGS__
 	, FinalizerEnvPtr
 #endif
+	-- ** Basic operations
         , newForeignPtr
         , newForeignPtr_
         , addForeignPtrFinalizer
@@ -31,10 +32,13 @@ module Foreign.ForeignPtr
 	, addForeignPtrFinalizerEnv
 #endif
 	, withForeignPtr
+
+	-- ** Low-level operations
 	, unsafeForeignPtrToPtr
 	, touchForeignPtr
 	, castForeignPtr
 
+	-- ** Allocating managed memory
 	, mallocForeignPtr
 	, mallocForeignPtrBytes
 	, mallocForeignPtrArray
@@ -157,13 +161,21 @@ mallocForeignPtrBytes :: Int -> IO (ForeignPtr a)
 mallocForeignPtrBytes n = do
   r <- mallocBytes n
   newForeignPtr finalizerFree r
-#endif /* __HUGS__ || __NHC__ */
+#endif /* !__GLASGOW_HASKELL__ */
 
+-- | This function is similar to 'Foreign.Marshal.Array.mallocArray',
+-- but yields a memory area that has a finalizer attached that releases
+-- the memory area.  As with 'mallocForeignPtr', it is not guaranteed that
+-- the block of memory was allocated by 'Foreign.Marshal.Alloc.malloc'.
 mallocForeignPtrArray :: Storable a => Int -> IO (ForeignPtr a)
 mallocForeignPtrArray  = doMalloc undefined
   where
     doMalloc            :: Storable a => a -> Int -> IO (ForeignPtr a)
     doMalloc dummy size  = mallocForeignPtrBytes (size * sizeOf dummy)
 
+-- | This function is similar to 'Foreign.Marshal.Array.mallocArray0',
+-- but yields a memory area that has a finalizer attached that releases
+-- the memory area.  As with 'mallocForeignPtr', it is not guaranteed that
+-- the block of memory was allocated by 'Foreign.Marshal.Alloc.malloc'.
 mallocForeignPtrArray0      :: Storable a => Int -> IO (ForeignPtr a)
 mallocForeignPtrArray0 size  = mallocForeignPtrArray (size + 1)
diff --git a/GHC/ForeignPtr.hs b/GHC/ForeignPtr.hs
index 0069de2..216f578 100644
--- a/GHC/ForeignPtr.hs
+++ b/GHC/ForeignPtr.hs
@@ -97,16 +97,16 @@ newConcForeignPtr p finalizer
        return fObj
 
 mallocForeignPtr :: Storable a => IO (ForeignPtr a)
--- ^ allocates some memory and returns a ForeignPtr to it.  The memory
--- will be released automatically when the ForeignPtr is discarded.
+-- ^ Allocate some memory and return a 'ForeignPtr' to it.  The memory
+-- will be released automatically when the 'ForeignPtr' is discarded.
 --
--- @mallocForeignPtr@ is equivalent to
+-- 'mallocForeignPtr' is equivalent to
 --
--- >    do { p <- malloc; newForeignPtr p free }
+-- >    do { p <- malloc; newForeignPtr finalizerFree p }
 -- 
--- although it may be implemented differently internally.  You may not
+-- although it may be implemented differently internally: you may not
 -- assume that the memory returned by 'mallocForeignPtr' has been
--- allocated with C's @malloc()@.
+-- allocated with 'Foreign.Marshal.Alloc.malloc'.
 mallocForeignPtr = doMalloc undefined
   where doMalloc :: Storable a => a -> IO (ForeignPtr a)
         doMalloc a = do
@@ -117,8 +117,8 @@ mallocForeignPtr = doMalloc undefined
             }
 	    where (I# size) = sizeOf a
 
--- | similar to 'mallocForeignPtr', except that the size of the memory required
--- is given explicitly as a number of bytes.
+-- | This function is similar to 'mallocForeignPtr', except that the
+-- size of the memory required is given explicitly as a number of bytes.
 mallocForeignPtrBytes :: Int -> IO (ForeignPtr a)
 mallocForeignPtrBytes (I# size) = do 
   r <- newIORef []
-- 
1.7.10.4