Improve ByteArray# documentation regarding alignment

3 files changed, 14 insertions, 3 deletions

diff --git a/compiler/GHC/Builtin/primops.txt.pp b/compiler/GHC/Builtin/primops.txt.pp
index 454c2e3a9e..afadce5a77 100644
--- a/compiler/GHC/Builtin/primops.txt.pp
+++ b/compiler/GHC/Builtin/primops.txt.pp
@@ -1631,13 +1631,14 @@ primop  NewByteArrayOp_Char "newByteArray#" GenPrimOp
 
 primop  NewPinnedByteArrayOp_Char "newPinnedByteArray#" GenPrimOp
    Int# -> State# s -> (# State# s, MutableByteArray# s #)
-   {Create a mutable byte array that the GC guarantees not to move.}
+   {Like 'newByteArray#' but GC guarantees not to move it.}
    with out_of_line = True
         has_side_effects = True
 
 primop  NewAlignedPinnedByteArrayOp_Char "newAlignedPinnedByteArray#" GenPrimOp
    Int# -> Int# -> State# s -> (# State# s, MutableByteArray# s #)
-   {Create a mutable byte array, aligned by the specified amount, that the GC guarantees not to move.}
+   {Like 'newPinnedByteArray#' but allow specifying an arbitrary
+    alignment, which must be a power of two.}
    with out_of_line = True
         has_side_effects = True
 
diff --git a/libraries/base/Foreign/Marshal/Alloc.hs b/libraries/base/Foreign/Marshal/Alloc.hs
index b46b67dd2b..6bdf4feadf 100644
--- a/libraries/base/Foreign/Marshal/Alloc.hs
+++ b/libraries/base/Foreign/Marshal/Alloc.hs
@@ -133,6 +133,14 @@ allocaBytes (I# size) action = IO $ \ s0 ->
      keepAlive# barr# s2 action'
   }}}
 
+-- |@'allocaBytesAligned' size align f@ executes the computation @f@,
+-- passing as argument a pointer to a temporarily allocated block of memory
+-- of @size@ bytes and aligned to @align@ bytes. The value of @align@ must
+-- be a power of two.
+--
+-- The memory is freed when @f@ terminates (either normally or via an
+-- exception), so the pointer passed to @f@ must /not/ be used after this.
+--
 allocaBytesAligned :: Int -> Int -> (Ptr a -> IO b) -> IO b
 allocaBytesAligned (I# size) (I# align) action = IO $ \ s0 ->
      case newAlignedPinnedByteArray# size align s0 of { (# s1, mbarr# #) ->
diff --git a/libraries/base/Foreign/Storable.hs b/libraries/base/Foreign/Storable.hs
index a58e0db069..844ec7a494 100644
--- a/libraries/base/Foreign/Storable.hs
+++ b/libraries/base/Foreign/Storable.hs
@@ -84,7 +84,9 @@ class Storable a where
    alignment   :: a -> Int
    -- ^ Computes the alignment constraint of the argument.  An
    -- alignment constraint @x@ is fulfilled by any address divisible
-   -- by @x@.  The value of the argument is not used.
+   -- by @x@. The alignment must be a power of two if this instance
+   -- is to be used with 'alloca' or 'allocaArray'.  The value of
+   -- the argument is not used.
 
    peekElemOff :: Ptr a -> Int      -> IO a
    -- ^       Read a value from a memory area regarded as an array