diff --git a/vector/src/Data/Vector/Generic/Mutable.hs b/vector/src/Data/Vector/Generic/Mutable.hs
index 9a6b221f..ba728c3d 100644
--- a/vector/src/Data/Vector/Generic/Mutable.hs
+++ b/vector/src/Data/Vector/Generic/Mutable.hs
@@ -13,8 +13,7 @@
 -- Stability   : experimental
 -- Portability : non-portable
 --
--- Generic interface to mutable vectors
---
+-- Generic interface to mutable vectors.
 
 module Data.Vector.Generic.Mutable (
   -- * Class of mutable vector types
@@ -96,7 +95,7 @@ import Prelude hiding ( length, null, replicate, reverse, map, read,
 {-
 type family Immutable (v :: * -> * -> *) :: * -> *
 
--- | Class of mutable vectors parametrised with a primitive state token.
+-- | Class of mutable vectors parameterised with a primitive state token.
 --
 class MBundle.Pointer u a => MVector v a where
   -- | Length of the mutable vector. This method should not be
@@ -258,14 +257,14 @@ unsafePrepend1 v i x
 
 mstream :: (PrimMonad m, MVector v a) => v (PrimState m) a -> Stream m a
 {-# INLINE mstream #-}
-mstream v = v `seq` n `seq` (Stream.unfoldrM get 0)
+mstream v = v `seq` n `seq` Stream.unfoldrM get 0
   where
     n = length v
 
     {-# INLINE_INNER get #-}
     get i | i < n     = do x <- unsafeRead v i
                            return $ Just (x, i+1)
-          | otherwise = return $ Nothing
+          | otherwise = return Nothing
 
 fill :: (PrimMonad m, MVector v a)
      => v (PrimState m) a -> Stream m a -> m (v (PrimState m) a)
@@ -287,7 +286,7 @@ transform f v = fill v (f (mstream v))
 
 mstreamR :: (PrimMonad m, MVector v a) => v (PrimState m) a -> Stream m a
 {-# INLINE mstreamR #-}
-mstreamR v = v `seq` n `seq` (Stream.unfoldrM get n)
+mstreamR v = v `seq` n `seq` Stream.unfoldrM get n
   where
     n = length v
 
@@ -378,11 +377,6 @@ munstreamUnknown s
                     return (v',i+1)
 
 
-
-
-
-
-
 -- | Create a new mutable vector and fill it with elements from the 'Bundle'.
 -- The vector will grow exponentially if the maximum size of the 'Bundle' is
 -- unknown.
@@ -449,8 +443,6 @@ vmunstreamUnknown s
           return (v',j)
 
 
-
-
 -- | Create a new mutable vector and fill it with elements from the 'Bundle'
 -- from right to left. The vector will grow exponentially if the maximum size
 -- of the 'Bundle' is unknown.
@@ -507,7 +499,7 @@ length :: MVector v a => v s a -> Int
 {-# INLINE length #-}
 length = basicLength
 
--- | Check whether the vector is empty
+-- | Check whether the vector is empty.
 null :: MVector v a => v s a -> Bool
 {-# INLINE null #-}
 null v = length v == 0
@@ -525,16 +517,16 @@ slice :: (HasCallStack, MVector v a)
 {-# INLINE slice #-}
 slice i n v = checkSlice Bounds i n (length v) $ unsafeSlice i n v
 
--- | Take @n@ first elements of the mutable vector without making a
--- copy. For negative @n@ empty vector is returned. If @n@ is larger
--- than vector's length empty vector is returned,
+-- | Take the @n@ first elements of the mutable vector without making a
+-- copy. For negative @n@, the empty vector is returned. If @n@ is larger
+-- than the vector's length, the vector is returned unchanged.
 take :: MVector v a => Int -> v s a -> v s a
 {-# INLINE take #-}
 take n v = unsafeSlice 0 (min (max n 0) (length v)) v
 
--- | Drop @n@ first element of the mutable vector without making a
--- copy. For negative @n@ vector is returned unchanged and if @n@ is
--- larger than vector's length empty vector is returned.
+-- | Drop the @n@ first element of the mutable vector without making a
+-- copy. For negative @n@, the vector is returned unchanged. If @n@ is
+-- larger than the vector's length, the empty vector is returned.
 drop :: MVector v a => Int -> v s a -> v s a
 {-# INLINE drop #-}
 drop n v = unsafeSlice (min m n') (max 0 (m - n')) v
@@ -542,8 +534,13 @@ drop n v = unsafeSlice (min m n') (max 0 (m - n')) v
     n' = max n 0
     m  = length v
 
-{-# INLINE splitAt #-}
+-- | /O(1)/ Split the mutable vector into the first @n@ elements
+-- and the remainder, without copying.
+--
+-- Note that @'splitAt' n v@ is equivalent to @('take' n v, 'drop' n v)@,
+-- but slightly more efficient.
 splitAt :: MVector v a => Int -> v s a -> (v s a, v s a)
+{-# INLINE splitAt #-}
 splitAt n v = ( unsafeSlice 0 m v
               , unsafeSlice m (max 0 (len - n')) v
               )
@@ -552,14 +549,14 @@ splitAt n v = ( unsafeSlice 0 m v
       n'  = max n 0
       len = length v
 
--- | Drop last element of the mutable vector without making a copy. If
--- vector is empty exception is thrown.
+-- | Drop the last element of the mutable vector without making a copy.
+-- If the vector is empty, an exception is thrown.
 init :: MVector v a => v s a -> v s a
 {-# INLINE init #-}
 init v = slice 0 (length v - 1) v
 
--- | Drop first element of the mutable vector without making a copy. If
--- vector is empty exception is thrown.
+-- | Drop the first element of the mutable vector without making a copy.
+-- If the vector is empty, an exception is thrown.
 tail :: MVector v a => v s a -> v s a
 {-# INLINE tail #-}
 tail v = slice 1 (length v - 1) v
@@ -574,24 +571,24 @@ unsafeSlice :: MVector v a => Int  -- ^ starting index
 unsafeSlice i n v = checkSlice Unsafe i n (length v)
                   $ basicUnsafeSlice i n v
 
--- | Same as 'init' but doesn't do range checks.
+-- | Same as 'init', but doesn't do range checks.
 unsafeInit :: MVector v a => v s a -> v s a
 {-# INLINE unsafeInit #-}
 unsafeInit v = unsafeSlice 0 (length v - 1) v
 
--- | Same as 'tail' but doesn't do range checks.
+-- | Same as 'tail', but doesn't do range checks.
 unsafeTail :: MVector v a => v s a -> v s a
 {-# INLINE unsafeTail #-}
 unsafeTail v = unsafeSlice 1 (length v - 1) v
 
--- | Unsafe variant of 'take'. If called with out of range @n@ it will
--- simply create invalid slice that likely violate memory safety
+-- | Unsafe variant of 'take'. If @n@ is out of range, it will
+-- simply create an invalid slice that likely violate memory safety.
 unsafeTake :: MVector v a => Int -> v s a -> v s a
 {-# INLINE unsafeTake #-}
 unsafeTake n v = unsafeSlice 0 n v
 
--- | Unsafe variant of 'drop'. If called with out of range @n@ it will
--- simply create invalid slice that likely violate memory safety
+-- | Unsafe variant of 'drop'. If @n@ is out of range, it will
+-- simply create an invalid slice that likely violate memory safety.
 unsafeDrop :: MVector v a => Int -> v s a -> v s a
 {-# INLINE unsafeDrop #-}
 unsafeDrop n v = unsafeSlice n (length v - n) v
@@ -614,11 +611,11 @@ new n = checkLength Bounds n $ stToPrim
       $ unsafeNew n >>= \v -> basicInitialize v >> return v
 
 -- | Create a mutable vector of the given length. The vector content
---   should be presumed uninitialized. However exact semantics depends
---   on vector implementation. For example unboxed and storable
---   vectors will create vector filled with whatever underlying memory
---   buffer happens to contain, while boxed vector's elements are
---   initialized to bottoms which will throw exception when evaluated.
+-- should be assumed to be uninitialized. However, the exact semantics depend
+-- on the vector implementation. For example, unboxed and storable
+-- vectors will create a vector filled with whatever the underlying memory
+-- buffer happens to contain, while boxed vector's elements are
+-- initialized to bottoms which will throw exception when evaluated.
 --
 -- @since 0.4
 unsafeNew :: (PrimMonad m, MVector v a) => Int -> m (v (PrimState m) a)
@@ -639,6 +636,7 @@ replicateM n m = munstream (MBundle.replicateM n m)
 
 -- | /O(n)/ Create a mutable vector of the given length (0 if the length is negative)
 -- and fill it with the results of applying the function to each index.
+-- Iteration starts at index 0.
 --
 -- @since 0.12.3.0
 generate :: (PrimMonad m, MVector v a) => Int -> (Int -> a) -> m (v (PrimState m) a)
@@ -673,19 +671,19 @@ clone v = do
 -- -------
 
 -- | Grow a vector by the given number of elements. The number must not be
--- negative otherwise error is thrown. Semantics of this function is exactly the
--- same as `unsafeGrow`, except that it will initialize the newly
+-- negative, otherwise an exception is thrown. The semantics of this function
+-- are exactly the same as of 'unsafeGrow', except that it will initialize the newly
 -- allocated memory first.
 --
 -- It is important to note that mutating the returned vector will not affect the
--- vector that was used as a source. In other words it does not, nor will it
+-- vector that was used as a source. In other words, it does not, nor will it
 -- ever have the semantics of @realloc@ from C.
 --
 -- > grow mv 0 === clone mv
 --
 -- @since 0.4.0
 grow :: (HasCallStack, PrimMonad m, MVector v a)
-                => v (PrimState m) a -> Int -> m (v (PrimState m) a)
+     => v (PrimState m) a -> Int -> m (v (PrimState m) a)
 {-# INLINE grow #-}
 grow v by = checkLength Bounds by
           $ stToPrim
@@ -693,12 +691,12 @@ grow v by = checkLength Bounds by
                basicInitialize $ basicUnsafeSlice (length v) by vnew
                return vnew
 
--- | Same as `grow`, except that it copies data towards the end of the newly
--- allocated vector making extra space available at the beginning.
+-- | Same as 'grow', except that it copies data towards the end of the newly
+-- allocated vector, making extra space available at the beginning.
 --
 -- @since 0.11.0.0
 growFront :: (HasCallStack, PrimMonad m, MVector v a)
-                => v (PrimState m) a -> Int -> m (v (PrimState m) a)
+          => v (PrimState m) a -> Int -> m (v (PrimState m) a)
 {-# INLINE growFront #-}
 growFront v by = checkLength Bounds by
                $ stToPrim
@@ -709,9 +707,9 @@ growFront v by = checkLength Bounds by
 enlarge_delta :: MVector v a => v s a -> Int
 enlarge_delta v = max (length v) 1
 
--- | Grow a vector logarithmically
+-- | Grow a vector logarithmically.
 enlarge :: (PrimMonad m, MVector v a)
-                => v (PrimState m) a -> m (v (PrimState m) a)
+        => v (PrimState m) a -> m (v (PrimState m) a)
 {-# INLINE enlarge #-}
 enlarge v = stToPrim $ do
   vnew <- unsafeGrow v by
@@ -721,7 +719,7 @@ enlarge v = stToPrim $ do
     by = enlarge_delta v
 
 enlargeFront :: (PrimMonad m, MVector v a)
-                => v (PrimState m) a -> m (v (PrimState m) a, Int)
+             => v (PrimState m) a -> m (v (PrimState m) a, Int)
 {-# INLINE enlargeFront #-}
 enlargeFront v = stToPrim $ do
                    v' <- unsafeGrowFront v by
@@ -731,41 +729,41 @@ enlargeFront v = stToPrim $ do
     by = enlarge_delta v
 
 -- | Grow a vector by allocating a new mutable vector of the same size plus the
--- the given number of elements and copying all the data over to the new vector
+-- the given number of elements and copying all the data over to the new vector,
 -- starting at its beginning. The newly allocated memory is not initialized and
--- the extra space at the end will likely contain garbage data or uninitialzed
--- error. Use `unsafeGrowFront` to make the extra space available in the front
+-- the extra space at the end will likely contain garbage data or bottoms.
+-- Use 'unsafeGrowFront' to make the extra space available in the front
 -- of the new vector.
 --
 -- It is important to note that mutating the returned vector will not affect
--- elements of the vector that was used as a source. In other words it does not,
+-- elements of the vector that was used as a source. In other words, it does not,
 -- nor will it ever have the semantics of @realloc@ from C. Keep in mind,
 -- however, that values themselves can be of a mutable type
--- (eg. `Foreign.Ptr.Ptr`), in which case it would be possible to affect values
+-- (eg. 'Foreign.Ptr.Ptr'), in which case it would be possible to affect values
 -- stored in both vectors.
 --
 -- > unsafeGrow mv 0 === clone mv
 --
 -- @since 0.4.0
-unsafeGrow ::
-     (PrimMonad m, MVector v a)
+unsafeGrow
+  :: (PrimMonad m, MVector v a)
   => v (PrimState m) a
-  -- ^ A mutable vector to copy the data from.
+  -- ^ mutable vector to copy from
   -> Int
-  -- ^ Number of elements to grow the vector by. It must be non-negative but
-  -- this is not checked.
+  -- ^ number of elements to grow the vector by (must be non-negative, but
+  -- this is not checked)
   -> m (v (PrimState m) a)
 {-# INLINE unsafeGrow #-}
 unsafeGrow v n = checkLength Unsafe n
                $ stToPrim
                $ basicUnsafeGrow v n
 
--- | Same as `unsafeGrow`, except that it copies data towards the end of the
--- newly allocated vector making extra space available at the beginning.
+-- | Same as 'unsafeGrow', except that it copies data towards the end of the
+-- newly allocated vector, making extra space available at the beginning.
 --
 -- @since 0.11.0.0
 unsafeGrowFront :: (PrimMonad m, MVector v a)
-                        => v (PrimState m) a -> Int -> m (v (PrimState m) a)
+                => v (PrimState m) a -> Int -> m (v (PrimState m) a)
 {-# INLINE unsafeGrowFront #-}
 unsafeGrowFront v by = checkLength Unsafe by $ stToPrim $ do
                          let n = length v
@@ -831,8 +829,7 @@ unsafeRead v i = checkIndex Unsafe i (length v)
                $ basicUnsafeRead v i
 
 -- | Replace the element at the given position. No bounds checks are performed.
-unsafeWrite :: (PrimMonad m, MVector v a)
-                                => v (PrimState m) a -> Int -> a -> m ()
+unsafeWrite :: (PrimMonad m, MVector v a) => v (PrimState m) a -> Int -> a -> m ()
 {-# INLINE unsafeWrite #-}
 unsafeWrite v i x = checkIndex Unsafe i (length v)
                   $ stToPrim
@@ -856,8 +853,7 @@ unsafeModifyM v f i = checkIndex Unsafe i (length v)
                     $ stToPrim . basicUnsafeWrite v i =<< f =<< stToPrim (basicUnsafeRead v i)
 
 -- | Swap the elements at the given positions. No bounds checks are performed.
-unsafeSwap :: (PrimMonad m, MVector v a)
-                => v (PrimState m) a -> Int -> Int -> m ()
+unsafeSwap :: (PrimMonad m, MVector v a) => v (PrimState m) a -> Int -> Int -> m ()
 {-# INLINE unsafeSwap #-}
 unsafeSwap v i j = checkIndex Unsafe i (length v)
                  $ checkIndex Unsafe j (length v)
@@ -869,8 +865,7 @@ unsafeSwap v i j = checkIndex Unsafe i (length v)
 
 -- | Replace the element at the given position and return the old element. No
 -- bounds checks are performed.
-unsafeExchange :: (PrimMonad m, MVector v a)
-                                => v (PrimState m) a -> Int -> a -> m a
+unsafeExchange :: (PrimMonad m, MVector v a) => v (PrimState m) a -> Int -> a -> m a
 {-# INLINE unsafeExchange #-}
 unsafeExchange v i x = checkIndex Unsafe i (length v) $ stToPrim $ do
                          y <- unsafeRead v i
@@ -903,7 +898,7 @@ imapM_ :: (PrimMonad m, MVector v a) => (Int -> a -> m b) -> v (PrimState m) a -
 imapM_ f v = forI_ v $ \i -> f i =<< unsafeRead v i
 
 -- | /O(n)/ Apply the monadic action to every element of the vector,
--- discarding the results. It's same as the @flip mapM_@.
+-- discarding the results. It's the same as @flip mapM_@.
 --
 -- @since 0.12.3.0
 forM_ :: (PrimMonad m, MVector v a) => v (PrimState m) a -> (a -> m b) -> m ()
@@ -911,7 +906,7 @@ forM_ :: (PrimMonad m, MVector v a) => v (PrimState m) a -> (a -> m b) -> m ()
 forM_ = flip mapM_
 
 -- | /O(n)/ Apply the monadic action to every element of the vector
--- and its index, discarding the results. It's same as the @flip imapM_@.
+-- and its index, discarding the results. It's the same as @flip imapM_@.
 --
 -- @since 0.12.3.0
 iforM_ :: (PrimMonad m, MVector v a) => v (PrimState m) a -> (Int -> a -> m b) -> m ()
@@ -932,14 +927,14 @@ foldl' :: (PrimMonad m, MVector v a) => (b -> a -> b) -> b -> v (PrimState m) a
 {-# INLINE foldl' #-}
 foldl' f = ifoldl' (\b _ -> f b)
 
--- | /O(n)/ Pure left fold (function applied to each element and its index).
+-- | /O(n)/ Pure left fold using a function applied to each element and its index.
 --
 -- @since 0.12.3.0
 ifoldl :: (PrimMonad m, MVector v a) => (b -> Int -> a -> b) -> b -> v (PrimState m) a -> m b
 {-# INLINE ifoldl #-}
 ifoldl f b0 v = stToPrim $ ifoldM (\b i a -> return $ f b i a) b0 v
 
--- | /O(n)/ Pure left fold with strict accumulator (function applied to each element and its index).
+-- | /O(n)/ Pure left fold with strict accumulator using a function applied to each element and its index.
 --
 -- @since 0.12.3.0
 ifoldl' :: (PrimMonad m, MVector v a) => (b -> Int -> a -> b) -> b -> v (PrimState m) a -> m b
@@ -960,15 +955,15 @@ foldr' :: (PrimMonad m, MVector v a) => (a -> b -> b) -> b -> v (PrimState m) a
 {-# INLINE foldr' #-}
 foldr' f = ifoldr' (const f)
 
--- | /O(n)/ Pure right fold (function applied to each element and its index).
+-- | /O(n)/ Pure right fold using a function applied to each element and its index.
 --
 -- @since 0.12.3.0
 ifoldr :: (PrimMonad m, MVector v a) => (Int -> a -> b -> b) -> b -> v (PrimState m) a -> m b
 {-# INLINE ifoldr #-}
 ifoldr f b0 v = stToPrim $ ifoldrM (\i a b -> return $ f i a b) b0 v
 
--- | /O(n)/ Pure right fold with strict accumulator (function applied
--- to each element and its index).
+-- | /O(n)/ Pure right fold with strict accumulator using a function applied
+-- to each element and its index.
 --
 -- @since 0.12.3.0
 ifoldr' :: (PrimMonad m, MVector v a) => (Int -> a -> b -> b) -> b -> v (PrimState m) a -> m b
@@ -989,7 +984,7 @@ foldM' :: (PrimMonad m, MVector v a) => (b -> a -> m b) -> b -> v (PrimState m)
 {-# INLINE foldM' #-}
 foldM' f = ifoldM' (\x _ -> f x)
 
--- | /O(n)/ Monadic fold (action applied to each element and its index).
+-- | /O(n)/ Monadic fold using a function applied to each element and its index.
 --
 -- @since 0.12.3.0
 ifoldM :: (PrimMonad m, MVector v a) => (b -> Int -> a -> m b) -> b -> v (PrimState m) a -> m b
@@ -1001,7 +996,7 @@ ifoldM f b0 v = loop 0 b0
                               loop (i + 1) =<< f b i a
     n = length v
 
--- | /O(n)/ Monadic fold with strict accumulator (action applied to each element and its index).
+-- | /O(n)/ Monadic fold with strict accumulator using a function applied to each element and its index.
 --
 -- @since 0.12.3.0
 ifoldM' :: (PrimMonad m, MVector v a) => (b -> Int -> a -> m b) -> b -> v (PrimState m) a -> m b
@@ -1027,7 +1022,7 @@ foldrM' :: (PrimMonad m, MVector v a) => (a -> b -> m b) -> b -> v (PrimState m)
 {-# INLINE foldrM' #-}
 foldrM' f = ifoldrM' (const f)
 
--- | /O(n)/ Monadic right fold (action applied to each element and its index).
+-- | /O(n)/ Monadic right fold using a function applied to each element and its index.
 --
 -- @since 0.12.3.0
 ifoldrM :: (PrimMonad m, MVector v a) => (Int -> a -> b -> m b) -> b -> v (PrimState m) a -> m b
@@ -1039,8 +1034,8 @@ ifoldrM f b0 v = loop (n-1) b0
                               loop (i - 1) =<< f i a b
     n = length v
 
--- | /O(n)/ Monadic right fold with strict accumulator (action applied
--- to each element and its index).
+-- | /O(n)/ Monadic right fold with strict accumulator using a function applied
+-- to each element and its index.
 --
 -- @since 0.12.3.0
 ifoldrM' :: (PrimMonad m, MVector v a) => (Int -> a -> b -> m b) -> b -> v (PrimState m) a -> m b
@@ -1052,20 +1047,20 @@ ifoldrM' f b0 v = loop (n-1) b0
                                loop (i - 1) =<< f i a b
     n = length v
 
-
 -- Filling and copying
 -- -------------------
 
 -- | Set all elements of the vector to the given value.
 set :: (PrimMonad m, MVector v a) => v (PrimState m) a -> a -> m ()
 {-# INLINE set #-}
-set v = stToPrim . basicSet v 
+set v = stToPrim . basicSet v
 
 -- | Copy a vector. The two vectors must have the same length and may not
 -- overlap.
-copy :: (HasCallStack, PrimMonad m, MVector v a) => v (PrimState m) a   -- ^ target
-                                   -> v (PrimState m) a   -- ^ source
-                                   -> m ()
+copy :: (HasCallStack, PrimMonad m, MVector v a)
+     => v (PrimState m) a   -- ^ target
+     -> v (PrimState m) a   -- ^ source
+     -> m ()
 {-# INLINE copy #-}
 copy dst src = check Bounds "overlapping vectors" (not (dst `overlaps` src))
              $ check Bounds "length mismatch" (length dst == length src)
@@ -1087,14 +1082,15 @@ move dst src = check Bounds "length mismatch" (length dst == length src)
              $ unsafeMove dst src
 
 -- | Copy a vector. The two vectors must have the same length and may not
--- overlap. This is not checked.
-unsafeCopy :: (PrimMonad m, MVector v a) => v (PrimState m) a   -- ^ target
-                                         -> v (PrimState m) a   -- ^ source
-                                         -> m ()
+-- overlap, but this is not checked.
+unsafeCopy :: (PrimMonad m, MVector v a)
+           => v (PrimState m) a   -- ^ target
+           -> v (PrimState m) a   -- ^ source
+           -> m ()
 {-# INLINE unsafeCopy #-}
 unsafeCopy dst src = check Unsafe "length mismatch" (length dst == length src)
                    $ check Unsafe "overlapping vectors" (not (dst `overlaps` src))
-                   $ (dst `seq` src `seq` stToPrim (basicUnsafeCopy dst src))
+                   $ dst `seq` src `seq` stToPrim (basicUnsafeCopy dst src)
 
 -- | Move the contents of a vector. The two vectors must have the same
 -- length, but this is not checked.
@@ -1103,15 +1099,14 @@ unsafeCopy dst src = check Unsafe "length mismatch" (length dst == length src)
 -- Otherwise, the copying is performed as if the source vector were
 -- copied to a temporary vector and then the temporary vector was copied
 -- to the target vector.
-unsafeMove :: (PrimMonad m, MVector v a) => v (PrimState m) a   -- ^ target
-                                         -> v (PrimState m) a   -- ^ source
-                                         -> m ()
+unsafeMove :: (PrimMonad m, MVector v a)
+           => v (PrimState m) a   -- ^ target
+           -> v (PrimState m) a   -- ^ source
+           -> m ()
 {-# INLINE unsafeMove #-}
 unsafeMove dst src = check Unsafe "length mismatch" (length dst == length src)
-                   $ (dst `seq` src `seq` stToPrim (basicUnsafeMove dst src))
+                   $ dst `seq` src `seq` stToPrim (basicUnsafeMove dst src)
 
--- Permutations
--- ------------
 
 accum :: forall m v a b u. (HasCallStack, PrimMonad m, MVector v a)
       => (a -> b -> a) -> v (PrimState m) a -> Bundle u (Int, b) -> m ()
@@ -1334,6 +1329,9 @@ partitionWithUnknown f s
         v2' <- unsafeAppend1 v2 i2 c
         return (v1, i1, v2', i2+1)
 
+-- Modifying vectors
+-- -----------------
+
 {-
 http://en.wikipedia.org/wiki/Permutation#Algorithms_to_generate_permutations
 
@@ -1347,8 +1345,8 @@ a given permutation. It changes the given permutation in-place.
 4. Reverse the sequence from a[k + 1] up to and including the final element a[n]
 -}
 
--- | Compute the next (lexicographically) permutation of given vector in-place.
---   Returns False when input is the last permutation
+-- | Compute the (lexicographically) next permutation of the given vector in-place.
+-- Returns False when the input is the last permutation.
 nextPermutation :: (PrimMonad m,Ord e,MVector v e) => v (PrimState m) e -> m Bool
 nextPermutation v
     | dim < 2 = return False
diff --git a/vector/src/Data/Vector/Generic/Mutable/Base.hs b/vector/src/Data/Vector/Generic/Mutable/Base.hs
index e2d44b0c..c42f5074 100644
--- a/vector/src/Data/Vector/Generic/Mutable/Base.hs
+++ b/vector/src/Data/Vector/Generic/Mutable/Base.hs
@@ -11,8 +11,7 @@
 -- Stability   : experimental
 -- Portability : non-portable
 --
--- Class of mutable vectors
---
+-- Class of mutable vectors.
 
 module Data.Vector.Generic.Mutable.Base (
   MVector(..)
@@ -24,8 +23,7 @@ import Control.Monad.ST
 #define NOT_VECTOR_MODULE
 #include "vector.h"
 
--- | Class of mutable vectors parametrised with a primitive state token.
---
+-- | Class of mutable vectors parameterised with a primitive state token.
 class MVector v a where
   -- | Length of the mutable vector. This method should not be
   -- called directly, use 'length' instead.
diff --git a/vector/src/Data/Vector/Mutable.hs b/vector/src/Data/Vector/Mutable.hs
index 5ac83635..fa1219f8 100644
--- a/vector/src/Data/Vector/Mutable.hs
+++ b/vector/src/Data/Vector/Mutable.hs
@@ -15,7 +15,6 @@
 -- Portability : non-portable
 --
 -- Mutable boxed vectors.
---
 
 module Data.Vector.Mutable (
   -- * Mutable boxed vectors
@@ -220,7 +219,7 @@ length :: MVector s a -> Int
 {-# INLINE length #-}
 length = G.length
 
--- | Check whether the vector is empty
+-- | Check whether the vector is empty.
 null :: MVector s a -> Bool
 {-# INLINE null #-}
 null = G.null
@@ -237,32 +236,37 @@ slice :: Int  -- ^ @i@ starting index
 {-# INLINE slice #-}
 slice = G.slice
 
--- | Take @n@ first elements of the mutable vector without making a
--- copy. For negative @n@ empty vector is returned. If @n@ is larger
--- than vector's length empty vector is returned,
+-- | Take the @n@ first elements of the mutable vector without making a
+-- copy. For negative @n@, the empty vector is returned. If @n@ is larger
+-- than the vector's length, the vector is returned unchanged.
 take :: Int -> MVector s a -> MVector s a
 {-# INLINE take #-}
 take = G.take
 
--- | Drop @n@ first element of the mutable vector without making a
--- copy. For negative @n@ vector is returned unchanged and if @n@ is
--- larger than vector's length empty vector is returned.
+-- | Drop the @n@ first element of the mutable vector without making a
+-- copy. For negative @n@, the vector is returned unchanged. If @n@ is
+-- larger than the vector's length, the empty vector is returned.
 drop :: Int -> MVector s a -> MVector s a
 {-# INLINE drop #-}
 drop = G.drop
 
-{-# INLINE splitAt #-}
+-- | /O(1)/ Split the mutable vector into the first @n@ elements
+-- and the remainder, without copying.
+--
+-- Note that @'splitAt' n v@ is equivalent to @('take' n v, 'drop' n v)@,
+-- but slightly more efficient.
 splitAt :: Int -> MVector s a -> (MVector s a, MVector s a)
+{-# INLINE splitAt #-}
 splitAt = G.splitAt
 
--- | Drop last element of the mutable vector without making a copy. If
--- vector is empty exception is thrown.
+-- | Drop the last element of the mutable vector without making a copy.
+-- If the vector is empty, an exception is thrown.
 init :: MVector s a -> MVector s a
 {-# INLINE init #-}
 init = G.init
 
--- | Drop first element of the mutable vector without making a copy. If
--- vector is empty exception is thrown.
+-- | Drop the first element of the mutable vector without making a copy.
+-- If the vector is empty, an exception is thrown.
 tail :: MVector s a -> MVector s a
 {-# INLINE tail #-}
 tail = G.tail
@@ -276,24 +280,24 @@ unsafeSlice :: Int  -- ^ starting index
 {-# INLINE unsafeSlice #-}
 unsafeSlice = G.unsafeSlice
 
--- | Unsafe variant of 'take'. If called with out of range @n@ it will
--- simply create invalid slice that likely violate memory safety
+-- | Unsafe variant of 'take'. If @n@ is out of range, it will
+-- simply create an invalid slice that likely violate memory safety.
 unsafeTake :: Int -> MVector s a -> MVector s a
 {-# INLINE unsafeTake #-}
 unsafeTake = G.unsafeTake
 
--- | Unsafe variant of 'drop'. If called with out of range @n@ it will
--- simply create invalid slice that likely violate memory safety
+-- | Unsafe variant of 'drop'. If @n@ is out of range, it will
+-- simply create an invalid slice that likely violate memory safety.
 unsafeDrop :: Int -> MVector s a -> MVector s a
 {-# INLINE unsafeDrop #-}
 unsafeDrop = G.unsafeDrop
 
--- | Same as 'init' but doesn't do range checks.
+-- | Same as 'init', but doesn't do range checks.
 unsafeInit :: MVector s a -> MVector s a
 {-# INLINE unsafeInit #-}
 unsafeInit = G.unsafeInit
 
--- | Same as 'tail' but doesn't do range checks.
+-- | Same as 'tail', but doesn't do range checks.
 unsafeTail :: MVector s a -> MVector s a
 {-# INLINE unsafeTail #-}
 unsafeTail = G.unsafeTail
@@ -315,7 +319,7 @@ new :: PrimMonad m => Int -> m (MVector (PrimState m) a)
 new = G.new
 
 -- | Create a mutable vector of the given length. The vector elements
---   are set to bottom so accessing them will cause an exception.
+-- are set to bottom, so accessing them will cause an exception.
 --
 -- @since 0.5
 unsafeNew :: PrimMonad m => Int -> m (MVector (PrimState m) a)
@@ -336,6 +340,7 @@ replicateM = G.replicateM
 
 -- | /O(n)/ Create a mutable vector of the given length (0 if the length is negative)
 -- and fill it with the results of applying the function to each index.
+-- Iteration starts at index 0.
 --
 -- @since 0.12.3.0
 generate :: (PrimMonad m) => Int -> (Int -> a) -> m (MVector (PrimState m) a)
@@ -360,14 +365,14 @@ clone = G.clone
 -- -------
 
 -- | Grow a boxed vector by the given number of elements. The number must be
--- non-negative. Same semantics as in `G.grow` for generic vector. It differs
+-- non-negative. This has the same semantics as 'G.grow' for generic vectors. It differs
 -- from @grow@ functions for unpacked vectors, however, in that only pointers to
--- values are copied over, therefore values themselves will be shared between
+-- values are copied over, therefore the values themselves will be shared between the
 -- two vectors. This is an important distinction to know about during memory
--- usage analysis and in case when values themselves are of a mutable type, eg.
--- `Data.IORef.IORef` or another mutable vector.
+-- usage analysis and in case the values themselves are of a mutable type, e.g.
+-- 'Data.IORef.IORef' or another mutable vector.
 --
--- ====__Examples__
+-- ==== __Examples__
 --
 -- >>> import qualified Data.Vector as V
 -- >>> import qualified Data.Vector.Mutable as MV
@@ -394,16 +399,16 @@ clone = G.clone
 --
 -- @since 0.5
 grow :: PrimMonad m
-              => MVector (PrimState m) a -> Int -> m (MVector (PrimState m) a)
+     => MVector (PrimState m) a -> Int -> m (MVector (PrimState m) a)
 {-# INLINE grow #-}
 grow = G.grow
 
--- | Grow a vector by the given number of elements. The number must be non-negative but
--- this is not checked. Same semantics as in `G.unsafeGrow` for generic vector.
+-- | Grow a vector by the given number of elements. The number must be non-negative, but
+-- this is not checked. This has the same semantics as 'G.unsafeGrow' for generic vectors.
 --
 -- @since 0.5
 unsafeGrow :: PrimMonad m
-               => MVector (PrimState m) a -> Int -> m (MVector (PrimState m) a)
+           => MVector (PrimState m) a -> Int -> m (MVector (PrimState m) a)
 {-# INLINE unsafeGrow #-}
 unsafeGrow = G.unsafeGrow
 
@@ -411,7 +416,7 @@ unsafeGrow = G.unsafeGrow
 -- ------------------------
 
 -- | Reset all elements of the vector to some undefined value, clearing all
--- references to external objects. This is usually a noop for unboxed vectors.
+-- references to external objects.
 clear :: PrimMonad m => MVector (PrimState m) a -> m ()
 {-# INLINE clear #-}
 clear = G.clear
@@ -502,7 +507,7 @@ copy :: PrimMonad m => MVector (PrimState m) a   -- ^ target
 copy = G.copy
 
 -- | Copy a vector. The two vectors must have the same length and may not
--- overlap. This is not checked.
+-- overlap, but this is not checked.
 unsafeCopy :: PrimMonad m => MVector (PrimState m) a   -- ^ target
                           -> MVector (PrimState m) a   -- ^ source
                           -> m ()
@@ -535,13 +540,15 @@ unsafeMove :: PrimMonad m => MVector (PrimState m) a   -- ^ target
 {-# INLINE unsafeMove #-}
 unsafeMove = G.unsafeMove
 
--- | Compute the next (lexicographically) permutation of given vector in-place.
---   Returns False when input is the last permutation
-nextPermutation :: (PrimMonad m,Ord e) => MVector (PrimState m) e -> m Bool
+-- Modifying vectors
+-- -----------------
+
+-- | Compute the (lexicographically) next permutation of the given vector in-place.
+-- Returns False when the input is the last permutation.
+nextPermutation :: (PrimMonad m, Ord e) => MVector (PrimState m) e -> m Bool
 {-# INLINE nextPermutation #-}
 nextPermutation = G.nextPermutation
 
-
 -- Folds
 -- -----
 
@@ -560,7 +567,7 @@ imapM_ :: (PrimMonad m) => (Int -> a -> m b) -> MVector (PrimState m) a -> m ()
 imapM_ = G.imapM_
 
 -- | /O(n)/ Apply the monadic action to every element of the vector,
--- discarding the results. It's same as the @flip mapM_@.
+-- discarding the results. It's the same as @flip mapM_@.
 --
 -- @since 0.12.3.0
 forM_ :: (PrimMonad m) => MVector (PrimState m) a -> (a -> m b) -> m ()
@@ -568,7 +575,7 @@ forM_ :: (PrimMonad m) => MVector (PrimState m) a -> (a -> m b) -> m ()
 forM_ = G.forM_
 
 -- | /O(n)/ Apply the monadic action to every element of the vector
--- and its index, discarding the results. It's same as the @flip imapM_@.
+-- and its index, discarding the results. It's the same as @flip imapM_@.
 --
 -- @since 0.12.3.0
 iforM_ :: (PrimMonad m) => MVector (PrimState m) a -> (Int -> a -> m b) -> m ()
@@ -589,14 +596,14 @@ foldl' :: (PrimMonad m) => (b -> a -> b) -> b -> MVector (PrimState m) a -> m b
 {-# INLINE foldl' #-}
 foldl' = G.foldl'
 
--- | /O(n)/ Pure left fold (function applied to each element and its index).
+-- | /O(n)/ Pure left fold using a function applied to each element and its index.
 --
 -- @since 0.12.3.0
 ifoldl :: (PrimMonad m) => (b -> Int -> a -> b) -> b -> MVector (PrimState m) a -> m b
 {-# INLINE ifoldl #-}
 ifoldl = G.ifoldl
 
--- | /O(n)/ Pure left fold with strict accumulator (function applied to each element and its index).
+-- | /O(n)/ Pure left fold with strict accumulator using a function applied to each element and its index.
 --
 -- @since 0.12.3.0
 ifoldl' :: (PrimMonad m) => (b -> Int -> a -> b) -> b -> MVector (PrimState m) a -> m b
@@ -617,15 +624,15 @@ foldr' :: (PrimMonad m) => (a -> b -> b) -> b -> MVector (PrimState m) a -> m b
 {-# INLINE foldr' #-}
 foldr' = G.foldr'
 
--- | /O(n)/ Pure right fold (function applied to each element and its index).
+-- | /O(n)/ Pure right fold using a function applied to each element and its index.
 --
 -- @since 0.12.3.0
 ifoldr :: (PrimMonad m) => (Int -> a -> b -> b) -> b -> MVector (PrimState m) a -> m b
 {-# INLINE ifoldr #-}
 ifoldr = G.ifoldr
 
--- | /O(n)/ Pure right fold with strict accumulator (function applied
--- to each element and its index).
+-- | /O(n)/ Pure right fold with strict accumulator using a function applied
+-- to each element and its index.
 --
 -- @since 0.12.3.0
 ifoldr' :: (PrimMonad m) => (Int -> a -> b -> b) -> b -> MVector (PrimState m) a -> m b
@@ -646,14 +653,14 @@ foldM' :: (PrimMonad m) => (b -> a -> m b) -> b -> MVector (PrimState m) a -> m
 {-# INLINE foldM' #-}
 foldM' = G.foldM'
 
--- | /O(n)/ Monadic fold (action applied to each element and its index).
+-- | /O(n)/ Monadic fold using a function applied to each element and its index.
 --
 -- @since 0.12.3.0
 ifoldM :: (PrimMonad m) => (b -> Int -> a -> m b) -> b -> MVector (PrimState m) a -> m b
 {-# INLINE ifoldM #-}
 ifoldM = G.ifoldM
 
--- | /O(n)/ Monadic fold with strict accumulator (action applied to each element and its index).
+-- | /O(n)/ Monadic fold with strict accumulator using a function applied to each element and its index.
 --
 -- @since 0.12.3.0
 ifoldM' :: (PrimMonad m) => (b -> Int -> a -> m b) -> b -> MVector (PrimState m) a -> m b
@@ -674,15 +681,15 @@ foldrM' :: (PrimMonad m) => (a -> b -> m b) -> b -> MVector (PrimState m) a -> m
 {-# INLINE foldrM' #-}
 foldrM' = G.foldrM'
 
--- | /O(n)/ Monadic right fold (action applied to each element and its index).
+-- | /O(n)/ Monadic right fold using a function applied to each element and its index.
 --
 -- @since 0.12.3.0
 ifoldrM :: (PrimMonad m) => (Int -> a -> b -> m b) -> b -> MVector (PrimState m) a -> m b
 {-# INLINE ifoldrM #-}
 ifoldrM = G.ifoldrM
 
--- | /O(n)/ Monadic right fold with strict accumulator (action applied
--- to each element and its index).
+-- | /O(n)/ Monadic right fold with strict accumulator using a function applied
+-- to each element and its index.
 --
 -- @since 0.12.3.0
 ifoldrM' :: (PrimMonad m) => (Int -> a -> b -> m b) -> b -> MVector (PrimState m) a -> m b
@@ -699,7 +706,7 @@ fromMutableArray :: PrimMonad m => MutableArray (PrimState m) a -> m (MVector (P
 {-# INLINE fromMutableArray #-}
 fromMutableArray marr =
   let size = sizeofMutableArray marr
-   in MVector 0 size `liftM` cloneMutableArray marr 0 size
+  in MVector 0 size `liftM` cloneMutableArray marr 0 size
 
 -- | /O(n)/ Make a copy of a mutable vector into a new mutable array.
 --
diff --git a/vector/src/Data/Vector/Primitive.hs b/vector/src/Data/Vector/Primitive.hs
index cc45cd43..13d4320d 100644
--- a/vector/src/Data/Vector/Primitive.hs
+++ b/vector/src/Data/Vector/Primitive.hs
@@ -202,13 +202,9 @@ type role Vector nominal
 -- underlying pointer and does not modify the elements.
 --
 -- This is marginally safer than 'unsafeCast', since this function imposes an
--- extra 'Coercible' constraint. This function is still not safe, however,
--- since it cannot guarantee that the two types have memory-compatible
--- 'Prim' instances.
---
--- Note that this function is unsafe. The @Coercible@ constraint guarantees
--- that the element types are representationally equal. It however cannot
--- guarantee that their respective 'Prim' are compatible.
+-- extra 'Coercible' constraint. The constraint guarantees that the element types
+-- are representationally equal. It however cannot guarantee
+-- that their respective 'Prim' instances are compatible.
 unsafeCoerceVector :: Coercible a b => Vector a -> Vector b
 unsafeCoerceVector = unsafeCoerce
 
diff --git a/vector/src/Data/Vector/Primitive/Mutable.hs b/vector/src/Data/Vector/Primitive/Mutable.hs
index b8587b9e..87534032 100644
--- a/vector/src/Data/Vector/Primitive/Mutable.hs
+++ b/vector/src/Data/Vector/Primitive/Mutable.hs
@@ -14,7 +14,6 @@
 -- Portability : non-portable
 --
 -- Mutable primitive vectors.
---
 
 module Data.Vector.Primitive.Mutable (
   -- * Mutable vectors of primitive types
@@ -97,17 +96,16 @@ type role MVector nominal nominal
 -- representationally equal type. The operation just changes the type of the
 -- underlying pointer and does not modify the elements.
 --
--- Note that function is unsafe. @Coercible@ constraint guarantee that
--- types @a@ and @b@ are represented identically. It however cannot
--- guarantee that their respective 'Prim' instances may have different
--- representations in memory.
+-- Note that this function is unsafe. The @Coercible@ constraint guarantees
+-- that the element types are representationally equal. It however cannot
+-- guarantee that their respective 'Prim' instances are compatible.
 unsafeCoerceMVector :: Coercible a b => MVector s a -> MVector s b
 unsafeCoerceMVector = unsafeCoerce
 
 -- | Mutable vectors of primitive types.
-data MVector s a = MVector {-# UNPACK #-} !Int
-                           {-# UNPACK #-} !Int
-                           {-# UNPACK #-} !(MutableByteArray s) -- ^ offset, length, underlying mutable byte array
+data MVector s a = MVector {-# UNPACK #-} !Int                  -- ^ offset
+                           {-# UNPACK #-} !Int                  -- ^ length
+                           {-# UNPACK #-} !(MutableByteArray s) -- ^ underlying mutable byte array
         deriving ( Typeable )
 
 type IOVector = MVector RealWorld
@@ -178,7 +176,7 @@ length :: Prim a => MVector s a -> Int
 {-# INLINE length #-}
 length = G.length
 
--- | Check whether the vector is empty
+-- | Check whether the vector is empty.
 null :: Prim a => MVector s a -> Bool
 {-# INLINE null #-}
 null = G.null
@@ -196,32 +194,37 @@ slice :: Prim a
 {-# INLINE slice #-}
 slice = G.slice
 
--- | Take @n@ first elements of the mutable vector without making a
--- copy. For negative @n@ empty vector is returned. If @n@ is larger
--- than vector's length empty vector is returned,
+-- | Take the @n@ first elements of the mutable vector without making a
+-- copy. For negative @n@, the empty vector is returned. If @n@ is larger
+-- than the vector's length, the vector is returned unchanged.
 take :: Prim a => Int -> MVector s a -> MVector s a
 {-# INLINE take #-}
 take = G.take
 
--- | Drop @n@ first element of the mutable vector without making a
--- copy. For negative @n@ vector is returned unchanged and if @n@ is
--- larger than vector's length empty vector is returned.
+-- | Drop the @n@ first element of the mutable vector without making a
+-- copy. For negative @n@, the vector is returned unchanged. If @n@ is
+-- larger than the vector's length, the empty vector is returned.
 drop :: Prim a => Int -> MVector s a -> MVector s a
 {-# INLINE drop #-}
 drop = G.drop
 
+-- | /O(1)/ Split the mutable vector into the first @n@ elements
+-- and the remainder, without copying.
+--
+-- Note that @'splitAt' n v@ is equivalent to @('take' n v, 'drop' n v)@,
+-- but slightly more efficient.
 splitAt :: Prim a => Int -> MVector s a -> (MVector s a, MVector s a)
 {-# INLINE splitAt #-}
 splitAt = G.splitAt
 
--- | Drop last element of the mutable vector without making a copy. If
--- vector is empty exception is thrown.
+-- | Drop the last element of the mutable vector without making a copy.
+-- If the vector is empty, an exception is thrown.
 init :: Prim a => MVector s a -> MVector s a
 {-# INLINE init #-}
 init = G.init
 
--- | Drop first element of the mutable vector without making a copy. If
--- vector is empty exception is thrown.
+-- | Drop the first element of the mutable vector without making a copy.
+-- If the vector is empty, an exception is thrown.
 tail :: Prim a => MVector s a -> MVector s a
 {-# INLINE tail #-}
 tail = G.tail
@@ -236,24 +239,24 @@ unsafeSlice :: Prim a
 {-# INLINE unsafeSlice #-}
 unsafeSlice = G.unsafeSlice
 
--- | Unsafe variant of 'take'. If called with out of range @n@ it will
--- simply create invalid slice that likely violate memory safety
+-- | Unsafe variant of 'take'. If @n@ is out of range, it will
+-- simply create an invalid slice that likely violate memory safety.
 unsafeTake :: Prim a => Int -> MVector s a -> MVector s a
 {-# INLINE unsafeTake #-}
 unsafeTake = G.unsafeTake
 
--- | Unsafe variant of 'drop'. If called with out of range @n@ it will
--- simply create invalid slice that likely violate memory safety
+-- | Unsafe variant of 'drop'. If @n@ is out of range, it will
+-- simply create an invalid slice that likely violate memory safety.
 unsafeDrop :: Prim a => Int -> MVector s a -> MVector s a
 {-# INLINE unsafeDrop #-}
 unsafeDrop = G.unsafeDrop
 
--- | Same as 'init' but doesn't do range checks.
+-- | Same as 'init', but doesn't do range checks.
 unsafeInit :: Prim a => MVector s a -> MVector s a
 {-# INLINE unsafeInit #-}
 unsafeInit = G.unsafeInit
 
--- | Same as 'tail' but doesn't do range checks.
+-- | Same as 'tail', but doesn't do range checks.
 unsafeTail :: Prim a => MVector s a -> MVector s a
 {-# INLINE unsafeTail #-}
 unsafeTail = G.unsafeTail
@@ -275,8 +278,8 @@ new :: (PrimMonad m, Prim a) => Int -> m (MVector (PrimState m) a)
 new = G.new
 
 -- | Create a mutable vector of the given length. The vector content
---   is uninitialized, which means it is filled with whatever underlying memory
---   buffer happens to contain.
+-- is uninitialized, which means it is filled with whatever the
+-- underlying memory buffer happens to contain.
 --
 -- @since 0.5
 unsafeNew :: (PrimMonad m, Prim a) => Int -> m (MVector (PrimState m) a)
@@ -297,6 +300,7 @@ replicateM = G.replicateM
 
 -- | /O(n)/ Create a mutable vector of the given length (0 if the length is negative)
 -- and fill it with the results of applying the function to each index.
+-- Iteration starts at index 0.
 --
 -- @since 0.12.3.0
 generate :: (PrimMonad m, Prim a) => Int -> (Int -> a) -> m (MVector (PrimState m) a)
@@ -322,9 +326,9 @@ clone = G.clone
 -- -------
 
 -- | Grow a primitive vector by the given number of elements. The number must be
--- non-negative. Same semantics as in `G.grow` for generic vector.
+-- non-negative. This has the same semantics as 'G.grow' for generic vectors.
 --
--- ====__Examples__
+-- ==== __Examples__
 --
 -- >>> import qualified Data.Vector.Primitive as VP
 -- >>> import qualified Data.Vector.Primitive.Mutable as MVP
@@ -332,10 +336,10 @@ clone = G.clone
 -- >>> mv' <- MVP.grow mv 2
 --
 -- Extra memory at the end of the newly allocated vector is initialized to 0
--- bytes, which for `Prim` instance will usually correspond to some default
--- value for a particular type, eg. @0@ for @Int@, @\NUL@ for @Char@,
--- etc. However, if `unsafeGrow` was used instead this would not have been
--- guaranteed and some garbage would be there instead:
+-- bytes, which for 'Prim' instances will usually correspond to some default
+-- value for a particular type, e.g. @0@ for @Int@, @\NUL@ for @Char@,
+-- etc. However, if 'unsafeGrow' was used instead, this would not have been
+-- guaranteed and some garbage would be there instead.
 --
 -- >>> VP.freeze mv'
 -- [10,20,30,0,0]
@@ -357,16 +361,16 @@ clone = G.clone
 --
 -- @since 0.5
 grow :: (PrimMonad m, Prim a)
-              => MVector (PrimState m) a -> Int -> m (MVector (PrimState m) a)
+     => MVector (PrimState m) a -> Int -> m (MVector (PrimState m) a)
 {-# INLINE grow #-}
 grow = G.grow
 
--- | Grow a vector by the given number of elements. The number must be non-negative but
--- this is not checked. Same semantics as in `G.unsafeGrow` for generic vector.
+-- | Grow a vector by the given number of elements. The number must be non-negative, but
+-- this is not checked. This has the same semantics as 'G.unsafeGrow' for generic vectors.
 --
 -- @since 0.5
 unsafeGrow :: (PrimMonad m, Prim a)
-               => MVector (PrimState m) a -> Int -> m (MVector (PrimState m) a)
+           => MVector (PrimState m) a -> Int -> m (MVector (PrimState m) a)
 {-# INLINE unsafeGrow #-}
 unsafeGrow = G.unsafeGrow
 
@@ -374,7 +378,7 @@ unsafeGrow = G.unsafeGrow
 -- ------------------------
 
 -- | Reset all elements of the vector to some undefined value, clearing all
--- references to external objects. This is usually a noop for unboxed vectors.
+-- references to external objects. This is a noop.
 clear :: (PrimMonad m, Prim a) => MVector (PrimState m) a -> m ()
 {-# INLINE clear #-}
 clear = G.clear
@@ -420,8 +424,7 @@ unsafeRead :: (PrimMonad m, Prim a) => MVector (PrimState m) a -> Int -> m a
 unsafeRead = G.unsafeRead
 
 -- | Replace the element at the given position. No bounds checks are performed.
-unsafeWrite
-    :: (PrimMonad m, Prim a) =>  MVector (PrimState m) a -> Int -> a -> m ()
+unsafeWrite :: (PrimMonad m, Prim a) =>  MVector (PrimState m) a -> Int -> a -> m ()
 {-# INLINE unsafeWrite #-}
 unsafeWrite = G.unsafeWrite
 
@@ -439,8 +442,7 @@ unsafeModifyM :: (PrimMonad m, Prim a) => MVector (PrimState m) a -> (a -> m a)
 unsafeModifyM = G.unsafeModifyM
 
 -- | Swap the elements at the given positions. No bounds checks are performed.
-unsafeSwap
-    :: (PrimMonad m, Prim a) => MVector (PrimState m) a -> Int -> Int -> m ()
+unsafeSwap :: (PrimMonad m, Prim a) => MVector (PrimState m) a -> Int -> Int -> m ()
 {-# INLINE unsafeSwap #-}
 unsafeSwap = G.unsafeSwap
 
@@ -468,7 +470,7 @@ copy :: (PrimMonad m, Prim a)
 copy = G.copy
 
 -- | Copy a vector. The two vectors must have the same length and may not
--- overlap. This is not checked.
+-- overlap, but this is not checked.
 unsafeCopy :: (PrimMonad m, Prim a)
            => MVector (PrimState m) a   -- ^ target
            -> MVector (PrimState m) a   -- ^ source
@@ -504,13 +506,15 @@ unsafeMove :: (PrimMonad m, Prim a)
 {-# INLINE unsafeMove #-}
 unsafeMove = G.unsafeMove
 
--- | Compute the next (lexicographically) permutation of given vector in-place.
---   Returns False when input is the last permutation
+-- Modifying vectors
+-- -----------------
+
+-- | Compute the (lexicographically) next permutation of the given vector in-place.
+-- Returns False when the input is the last permutation.
 nextPermutation :: (PrimMonad m,Ord e,Prim e) => MVector (PrimState m) e -> m Bool
 {-# INLINE nextPermutation #-}
 nextPermutation = G.nextPermutation
 
-
 -- Folds
 -- -----
 
@@ -529,7 +533,7 @@ imapM_ :: (PrimMonad m, Prim a) => (Int -> a -> m b) -> MVector (PrimState m) a
 imapM_ = G.imapM_
 
 -- | /O(n)/ Apply the monadic action to every element of the vector,
--- discarding the results. It's same as the @flip mapM_@.
+-- discarding the results. It's the same as @flip mapM_@.
 --
 -- @since 0.12.3.0
 forM_ :: (PrimMonad m, Prim a) => MVector (PrimState m) a -> (a -> m b) -> m ()
@@ -537,7 +541,7 @@ forM_ :: (PrimMonad m, Prim a) => MVector (PrimState m) a -> (a -> m b) -> m ()
 forM_ = G.forM_
 
 -- | /O(n)/ Apply the monadic action to every element of the vector
--- and its index, discarding the results. It's same as the @flip imapM_@.
+-- and its index, discarding the results. It's the same as @flip imapM_@.
 --
 -- @since 0.12.3.0
 iforM_ :: (PrimMonad m, Prim a) => MVector (PrimState m) a -> (Int -> a -> m b) -> m ()
@@ -558,14 +562,14 @@ foldl' :: (PrimMonad m, Prim a) => (b -> a -> b) -> b -> MVector (PrimState m) a
 {-# INLINE foldl' #-}
 foldl' = G.foldl'
 
--- | /O(n)/ Pure left fold (function applied to each element and its index).
+-- | /O(n)/ Pure left fold using a function applied to each element and its index.
 --
 -- @since 0.12.3.0
 ifoldl :: (PrimMonad m, Prim a) => (b -> Int -> a -> b) -> b -> MVector (PrimState m) a -> m b
 {-# INLINE ifoldl #-}
 ifoldl = G.ifoldl
 
--- | /O(n)/ Pure left fold with strict accumulator (function applied to each element and its index).
+-- | /O(n)/ Pure left fold with strict accumulator using a function applied to each element and its index.
 --
 -- @since 0.12.3.0
 ifoldl' :: (PrimMonad m, Prim a) => (b -> Int -> a -> b) -> b -> MVector (PrimState m) a -> m b
@@ -586,15 +590,15 @@ foldr' :: (PrimMonad m, Prim a) => (a -> b -> b) -> b -> MVector (PrimState m) a
 {-# INLINE foldr' #-}
 foldr' = G.foldr'
 
--- | /O(n)/ Pure right fold (function applied to each element and its index).
+-- | /O(n)/ Pure right fold using a function applied to each element and its index.
 --
 -- @since 0.12.3.0
 ifoldr :: (PrimMonad m, Prim a) => (Int -> a -> b -> b) -> b -> MVector (PrimState m) a -> m b
 {-# INLINE ifoldr #-}
 ifoldr = G.ifoldr
 
--- | /O(n)/ Pure right fold with strict accumulator (function applied
--- to each element and its index).
+-- | /O(n)/ Pure right fold with strict accumulator using a function applied
+-- to each element and its index.
 --
 -- @since 0.12.3.0
 ifoldr' :: (PrimMonad m, Prim a) => (Int -> a -> b -> b) -> b -> MVector (PrimState m) a -> m b
@@ -615,14 +619,14 @@ foldM' :: (PrimMonad m, Prim a) => (b -> a -> m b) -> b -> MVector (PrimState m)
 {-# INLINE foldM' #-}
 foldM' = G.foldM'
 
--- | /O(n)/ Monadic fold (action applied to each element and its index).
+-- | /O(n)/ Monadic fold using a function applied to each element and its index.
 --
 -- @since 0.12.3.0
 ifoldM :: (PrimMonad m, Prim a) => (b -> Int -> a -> m b) -> b -> MVector (PrimState m) a -> m b
 {-# INLINE ifoldM #-}
 ifoldM = G.ifoldM
 
--- | /O(n)/ Monadic fold with strict accumulator (action applied to each element and its index).
+-- | /O(n)/ Monadic fold with strict accumulator using a function applied to each element and its index.
 --
 -- @since 0.12.3.0
 ifoldM' :: (PrimMonad m, Prim a) => (b -> Int -> a -> m b) -> b -> MVector (PrimState m) a -> m b
@@ -643,22 +647,21 @@ foldrM' :: (PrimMonad m, Prim a) => (a -> b -> m b) -> b -> MVector (PrimState m
 {-# INLINE foldrM' #-}
 foldrM' = G.foldrM'
 
--- | /O(n)/ Monadic right fold (action applied to each element and its index).
+-- | /O(n)/ Monadic right fold using a function applied to each element and its index.
 --
 -- @since 0.12.3.0
 ifoldrM :: (PrimMonad m, Prim a) => (Int -> a -> b -> m b) -> b -> MVector (PrimState m) a -> m b
 {-# INLINE ifoldrM #-}
 ifoldrM = G.ifoldrM
 
--- | /O(n)/ Monadic right fold with strict accumulator (action applied
--- to each element and its index).
+-- | /O(n)/ Monadic right fold with strict accumulator using a function applied
+-- to each element and its index.
 --
 -- @since 0.12.3.0
 ifoldrM' :: (PrimMonad m, Prim a) => (Int -> a -> b -> m b) -> b -> MVector (PrimState m) a -> m b
 {-# INLINE ifoldrM' #-}
 ifoldrM' = G.ifoldrM'
 
-
 -- Unsafe conversions
 -- ------------------
 
diff --git a/vector/src/Data/Vector/Storable/Mutable.hs b/vector/src/Data/Vector/Storable/Mutable.hs
index 7362bc29..730eaf85 100644
--- a/vector/src/Data/Vector/Storable/Mutable.hs
+++ b/vector/src/Data/Vector/Storable/Mutable.hs
@@ -15,7 +15,6 @@
 -- Portability : non-portable
 --
 -- Mutable vectors based on Storable.
---
 
 module Data.Vector.Storable.Mutable(
   -- * Mutable vectors of 'Storable' types
@@ -123,7 +122,7 @@ type role MVector nominal nominal
 unsafeCoerceMVector :: Coercible a b => MVector s a -> MVector s b
 unsafeCoerceMVector = unsafeCoerce
 
--- | Mutable 'Storable'-based vectors
+-- | Mutable 'Storable'-based vectors.
 data MVector s a = MVector {-# UNPACK #-} !Int
                            {-# UNPACK #-} !(ForeignPtr a)
         deriving ( Typeable )
@@ -235,14 +234,14 @@ storableSetAsPrim n fp x _y = unsafeWithForeignPtr fp $ \ ptr  -> do
      -- we dont equate storable and prim reps, so we need to write to a slot
      -- in storable
      -- then read it back as a prim
-    w<- peakPrimPtr_vector ((castPtr ptr) :: Ptr  b) 0
-    memsetPrimPtr_vector ((castPtr ptr) `plusPtr` sizeOf x ) (n-1)  w
+    w<- peakPrimPtr_vector (castPtr ptr :: Ptr  b) 0
+    memsetPrimPtr_vector (castPtr ptr `plusPtr` sizeOf x ) (n-1)  w
 
 
 
 {-
 AFTER primitive 0.7 is pretty old, move to using setPtr. which is really
-a confusing misnomer for whats often called memset (intialize )
+a confusing misnomer for whats often called memset (intialize)
 -}
 -- Fill a memory block with the given value. The length is in
 -- elements of type @a@ rather than in bytes.
@@ -274,7 +273,7 @@ length :: Storable a => MVector s a -> Int
 {-# INLINE length #-}
 length = G.length
 
--- | Check whether the vector is empty
+-- | Check whether the vector is empty.
 null :: Storable a => MVector s a -> Bool
 {-# INLINE null #-}
 null = G.null
@@ -292,32 +291,37 @@ slice :: Storable a
 {-# INLINE slice #-}
 slice = G.slice
 
--- | Take @n@ first elements of the mutable vector without making a
--- copy. For negative @n@ empty vector is returned. If @n@ is larger
--- than vector's length empty vector is returned,
+-- | Take the @n@ first elements of the mutable vector without making a
+-- copy. For negative @n@, the empty vector is returned. If @n@ is larger
+-- than the vector's length, the vector is returned unchanged.
 take :: Storable a => Int -> MVector s a -> MVector s a
 {-# INLINE take #-}
 take = G.take
 
--- | Drop @n@ first element of the mutable vector without making a
--- copy. For negative @n@ vector is returned unchanged and if @n@ is
--- larger than vector's length empty vector is returned.
+-- | Drop the @n@ first element of the mutable vector without making a
+-- copy. For negative @n@, the vector is returned unchanged. If @n@ is
+-- larger than the vector's length, the empty vector is returned.
 drop :: Storable a => Int -> MVector s a -> MVector s a
 {-# INLINE drop #-}
 drop = G.drop
 
+-- | /O(1)/ Split the mutable vector into the first @n@ elements
+-- and the remainder, without copying.
+--
+-- Note that @'splitAt' n v@ is equivalent to @('take' n v, 'drop' n v)@,
+-- but slightly more efficient.
 splitAt :: Storable a => Int -> MVector s a -> (MVector s a, MVector s a)
 {-# INLINE splitAt #-}
 splitAt = G.splitAt
 
--- | Drop last element of the mutable vector without making a copy. If
--- vector is empty exception is thrown.
+-- | Drop the last element of the mutable vector without making a copy.
+-- If the vector is empty, an exception is thrown.
 init :: Storable a => MVector s a -> MVector s a
 {-# INLINE init #-}
 init = G.init
 
--- | Drop first element of the mutable vector without making a copy. If
--- vector is empty exception is thrown.
+-- | Drop the first element of the mutable vector without making a copy.
+-- If the vector is empty, an exception is thrown.
 tail :: Storable a => MVector s a -> MVector s a
 {-# INLINE tail #-}
 tail = G.tail
@@ -332,24 +336,24 @@ unsafeSlice :: Storable a
 {-# INLINE unsafeSlice #-}
 unsafeSlice = G.unsafeSlice
 
--- | Unsafe variant of 'take'. If called with out of range @n@ it will
--- simply create invalid slice that likely violate memory safety
+-- | Unsafe variant of 'take'. If @n@ is out of range, it will
+-- simply create an invalid slice that likely violate memory safety.
 unsafeTake :: Storable a => Int -> MVector s a -> MVector s a
 {-# INLINE unsafeTake #-}
 unsafeTake = G.unsafeTake
 
--- | Unsafe variant of 'drop'. If called with out of range @n@ it will
--- simply create invalid slice that likely violate memory safety
+-- | Unsafe variant of 'drop'. If @n@ is out of range, it will
+-- simply create an invalid slice that likely violate memory safety.
 unsafeDrop :: Storable a => Int -> MVector s a -> MVector s a
 {-# INLINE unsafeDrop #-}
 unsafeDrop = G.unsafeDrop
 
--- | Same as 'init' but doesn't do range checks.
+-- | Same as 'init', but doesn't do range checks.
 unsafeInit :: Storable a => MVector s a -> MVector s a
 {-# INLINE unsafeInit #-}
 unsafeInit = G.unsafeInit
 
--- | Same as 'tail' but doesn't do range checks.
+-- | Same as 'tail', but doesn't do range checks.
 unsafeTail :: Storable a => MVector s a -> MVector s a
 {-# INLINE unsafeTail #-}
 unsafeTail = G.unsafeTail
@@ -371,8 +375,8 @@ new :: (PrimMonad m, Storable a) => Int -> m (MVector (PrimState m) a)
 new = G.new
 
 -- | Create a mutable vector of the given length. The vector content
---   is uninitialized, which means it is filled with whatever underlying memory
---   buffer happens to contain.
+-- is uninitialized, which means it is filled with whatever the
+-- underlying memory buffer happens to contain.
 --
 -- @since 0.5
 unsafeNew :: (PrimMonad m, Storable a) => Int -> m (MVector (PrimState m) a)
@@ -393,6 +397,7 @@ replicateM = G.replicateM
 
 -- | /O(n)/ Create a mutable vector of the given length (0 if the length is negative)
 -- and fill it with the results of applying the function to each index.
+-- Iteration starts at index 0.
 --
 -- @since 0.12.3.0
 generate :: (PrimMonad m, Storable a) => Int -> (Int -> a) -> m (MVector (PrimState m) a)
@@ -418,9 +423,9 @@ clone = G.clone
 -- -------
 
 -- | Grow a storable vector by the given number of elements. The number must be
--- non-negative. Same semantics as in `G.grow` for generic vector.
+-- non-negative. This has the same semantics as 'G.grow' for generic vectors.
 --
--- ====__Examples__
+-- ==== __Examples__
 --
 -- >>> import qualified Data.Vector.Storable as VS
 -- >>> import qualified Data.Vector.Storable.Mutable as MVS
@@ -428,10 +433,10 @@ clone = G.clone
 -- >>> mv' <- MVS.grow mv 2
 --
 -- Extra memory at the end of the newly allocated vector is initialized to 0
--- bytes, which for `Storable` instance will usually correspond to some default
--- value for a particular type, eg. @0@ for @Int@, @False@ for @Bool@,
--- etc. However, if `unsafeGrow` was used instead this would not have been
--- guaranteed and some garbage would be there instead:
+-- bytes, which for 'Storable' instances will usually correspond to some default
+-- value for a particular type, e.g. @0@ for @Int@, @False@ for @Bool@,
+-- etc. However, if 'unsafeGrow' was used instead, this would not have been
+-- guaranteed and some garbage would be there instead.
 --
 -- >>> VS.freeze mv'
 -- [10,20,30,0,0]
@@ -457,8 +462,8 @@ grow :: (PrimMonad m, Storable a)
 {-# INLINE grow #-}
 grow = G.grow
 
--- | Grow a vector by the given number of elements. The number must be non-negative but
--- this is not checked. Same semantics as in `G.unsafeGrow` for generic vector.
+-- | Grow a vector by the given number of elements. The number must be non-negative, but
+-- this is not checked. This has the same semantics as 'G.unsafeGrow' for generic vectors.
 --
 -- @since 0.5
 unsafeGrow :: (PrimMonad m, Storable a)
@@ -470,7 +475,7 @@ unsafeGrow = G.unsafeGrow
 -- ------------------------
 
 -- | Reset all elements of the vector to some undefined value, clearing all
--- references to external objects. This is usually a noop for unboxed vectors.
+-- references to external objects. This is a noop.
 clear :: (PrimMonad m, Storable a) => MVector (PrimState m) a -> m ()
 {-# INLINE clear #-}
 clear = G.clear
@@ -518,8 +523,7 @@ unsafeRead :: (PrimMonad m, Storable a) => MVector (PrimState m) a -> Int -> m a
 unsafeRead = G.unsafeRead
 
 -- | Replace the element at the given position. No bounds checks are performed.
-unsafeWrite
-    :: (PrimMonad m, Storable a) =>  MVector (PrimState m) a -> Int -> a -> m ()
+unsafeWrite :: (PrimMonad m, Storable a) =>  MVector (PrimState m) a -> Int -> a -> m ()
 {-# INLINE unsafeWrite #-}
 unsafeWrite = G.unsafeWrite
 
@@ -537,8 +541,7 @@ unsafeModifyM :: (PrimMonad m, Storable a) => MVector (PrimState m) a -> (a -> m
 unsafeModifyM = G.unsafeModifyM
 
 -- | Swap the elements at the given positions. No bounds checks are performed.
-unsafeSwap
-    :: (PrimMonad m, Storable a) => MVector (PrimState m) a -> Int -> Int -> m ()
+unsafeSwap :: (PrimMonad m, Storable a) => MVector (PrimState m) a -> Int -> Int -> m ()
 {-# INLINE unsafeSwap #-}
 unsafeSwap = G.unsafeSwap
 
@@ -566,7 +569,7 @@ copy :: (PrimMonad m, Storable a)
 copy = G.copy
 
 -- | Copy a vector. The two vectors must have the same length and may not
--- overlap. This is not checked.
+-- overlap, but this is not checked.
 unsafeCopy :: (PrimMonad m, Storable a)
            => MVector (PrimState m) a   -- ^ target
            -> MVector (PrimState m) a   -- ^ source
@@ -602,13 +605,15 @@ unsafeMove :: (PrimMonad m, Storable a)
 {-# INLINE unsafeMove #-}
 unsafeMove = G.unsafeMove
 
--- | Compute the next (lexicographically) permutation of given vector in-place.
---   Returns False when input is the last permutation
+-- Modifying vectors
+-- -----------------
+
+-- | Compute the (lexicographically) next permutation of the given vector in-place.
+-- Returns False when the input is the last permutation.
 nextPermutation :: (PrimMonad m, Storable e, Ord e) => MVector (PrimState m) e -> m Bool
 {-# INLINE nextPermutation #-}
 nextPermutation = G.nextPermutation
 
-
 -- Folds
 -- -----
 
@@ -627,7 +632,7 @@ imapM_ :: (PrimMonad m, Storable a) => (Int -> a -> m b) -> MVector (PrimState m
 imapM_ = G.imapM_
 
 -- | /O(n)/ Apply the monadic action to every element of the vector,
--- discarding the results. It's same as the @flip mapM_@.
+-- discarding the results. It's the same as @flip mapM_@.
 --
 -- @since 0.12.3.0
 forM_ :: (PrimMonad m, Storable a) => MVector (PrimState m) a -> (a -> m b) -> m ()
@@ -635,7 +640,7 @@ forM_ :: (PrimMonad m, Storable a) => MVector (PrimState m) a -> (a -> m b) -> m
 forM_ = G.forM_
 
 -- | /O(n)/ Apply the monadic action to every element of the vector
--- and its index, discarding the results. It's same as the @flip imapM_@.
+-- and its index, discarding the results. It's the same as @flip imapM_@.
 --
 -- @since 0.12.3.0
 iforM_ :: (PrimMonad m, Storable a) => MVector (PrimState m) a -> (Int -> a -> m b) -> m ()
@@ -656,14 +661,14 @@ foldl' :: (PrimMonad m, Storable a) => (b -> a -> b) -> b -> MVector (PrimState
 {-# INLINE foldl' #-}
 foldl' = G.foldl'
 
--- | /O(n)/ Pure left fold (function applied to each element and its index).
+-- | /O(n)/ Pure left fold using a function applied to each element and its index.
 --
 -- @since 0.12.3.0
 ifoldl :: (PrimMonad m, Storable a) => (b -> Int -> a -> b) -> b -> MVector (PrimState m) a -> m b
 {-# INLINE ifoldl #-}
 ifoldl = G.ifoldl
 
--- | /O(n)/ Pure left fold with strict accumulator (function applied to each element and its index).
+-- | /O(n)/ Pure left fold with strict accumulator using a function applied to each element and its index.
 --
 -- @since 0.12.3.0
 ifoldl' :: (PrimMonad m, Storable a) => (b -> Int -> a -> b) -> b -> MVector (PrimState m) a -> m b
@@ -684,15 +689,15 @@ foldr' :: (PrimMonad m, Storable a) => (a -> b -> b) -> b -> MVector (PrimState
 {-# INLINE foldr' #-}
 foldr' = G.foldr'
 
--- | /O(n)/ Pure right fold (function applied to each element and its index).
+-- | /O(n)/ Pure right fold using a function applied to each element and its index.
 --
 -- @since 0.12.3.0
 ifoldr :: (PrimMonad m, Storable a) => (Int -> a -> b -> b) -> b -> MVector (PrimState m) a -> m b
 {-# INLINE ifoldr #-}
 ifoldr = G.ifoldr
 
--- | /O(n)/ Pure right fold with strict accumulator (function applied
--- to each element and its index).
+-- | /O(n)/ Pure right fold with strict accumulator using a function applied
+-- to each element and its index.
 --
 -- @since 0.12.3.0
 ifoldr' :: (PrimMonad m, Storable a) => (Int -> a -> b -> b) -> b -> MVector (PrimState m) a -> m b
@@ -713,14 +718,14 @@ foldM' :: (PrimMonad m, Storable a) => (b -> a -> m b) -> b -> MVector (PrimStat
 {-# INLINE foldM' #-}
 foldM' = G.foldM'
 
--- | /O(n)/ Monadic fold (action applied to each element and its index).
+-- | /O(n)/ Monadic fold using a function applied to each element and its index.
 --
 -- @since 0.12.3.0
 ifoldM :: (PrimMonad m, Storable a) => (b -> Int -> a -> m b) -> b -> MVector (PrimState m) a -> m b
 {-# INLINE ifoldM #-}
 ifoldM = G.ifoldM
 
--- | /O(n)/ Monadic fold with strict accumulator (action applied to each element and its index).
+-- | /O(n)/ Monadic fold with strict accumulator using a function applied to each element and its index.
 --
 -- @since 0.12.3.0
 ifoldM' :: (PrimMonad m, Storable a) => (b -> Int -> a -> m b) -> b -> MVector (PrimState m) a -> m b
@@ -741,22 +746,21 @@ foldrM' :: (PrimMonad m, Storable a) => (a -> b -> m b) -> b -> MVector (PrimSta
 {-# INLINE foldrM' #-}
 foldrM' = G.foldrM'
 
--- | /O(n)/ Monadic right fold (action applied to each element and its index).
+-- | /O(n)/ Monadic right fold using a function applied to each element and its index.
 --
 -- @since 0.12.3.0
 ifoldrM :: (PrimMonad m, Storable a) => (Int -> a -> b -> m b) -> b -> MVector (PrimState m) a -> m b
 {-# INLINE ifoldrM #-}
 ifoldrM = G.ifoldrM
 
--- | /O(n)/ Monadic right fold with strict accumulator (action applied
--- to each element and its index).
+-- | /O(n)/ Monadic right fold with strict accumulator using a function applied
+-- to each element and its index.
 --
 -- @since 0.12.3.0
 ifoldrM' :: (PrimMonad m, Storable a) => (Int -> a -> b -> m b) -> b -> MVector (PrimState m) a -> m b
 {-# INLINE ifoldrM' #-}
 ifoldrM' = G.ifoldrM'
 
-
 -- Unsafe conversions
 -- ------------------
 
@@ -766,7 +770,6 @@ ifoldrM' = G.ifoldrM'
 --
 -- The resulting vector contains as many elements as can fit into the
 -- underlying memory block.
---
 unsafeCast :: forall a b s.
               (Storable a, Storable b) => MVector s a -> MVector s b
 {-# INLINE unsafeCast #-}
@@ -777,12 +780,12 @@ unsafeCast (MVector n fp)
 -- Raw pointers
 -- ------------
 
--- | Create a mutable vector from a 'ForeignPtr' with an offset and a length.
+-- | /O(1)/ Create a mutable vector from a 'ForeignPtr' with an offset and a length.
 --
 -- Modifying data through the 'ForeignPtr' afterwards is unsafe if the vector
 -- could have been frozen before the modification.
 --
---  If your offset is 0 it is more efficient to use 'unsafeFromForeignPtr0'.
+-- If your offset is 0, it is more efficient to use 'unsafeFromForeignPtr0'.
 unsafeFromForeignPtr :: Storable a
                      => ForeignPtr a    -- ^ pointer
                      -> Int             -- ^ offset
@@ -800,8 +803,8 @@ unsafeFromForeignPtr fp i n = unsafeFromForeignPtr0 fp' n
 
 -- | /O(1)/ Create a mutable vector from a 'ForeignPtr' and a length.
 --
--- It is assumed the pointer points directly to the data (no offset).
--- Use `unsafeFromForeignPtr` if you need to specify an offset.
+-- It is assumed that the pointer points directly to the data (no offset).
+-- Use 'unsafeFromForeignPtr' if you need to specify an offset.
 --
 -- Modifying data through the 'ForeignPtr' afterwards is unsafe if the vector
 -- could have been frozen before the modification.
@@ -811,19 +814,19 @@ unsafeFromForeignPtr0 :: ForeignPtr a    -- ^ pointer
 {-# INLINE unsafeFromForeignPtr0 #-}
 unsafeFromForeignPtr0 fp n = MVector n fp
 
--- | Yield the underlying 'ForeignPtr' together with the offset to the data
+-- | /O(1)/ Yield the underlying 'ForeignPtr' together with the offset to the data
 -- and its length. Modifying the data through the 'ForeignPtr' is
--- unsafe if the vector could have frozen before the modification.
+-- unsafe if the vector could have been frozen before the modification.
 unsafeToForeignPtr :: MVector s a -> (ForeignPtr a, Int, Int)
 {-# INLINE unsafeToForeignPtr #-}
 unsafeToForeignPtr (MVector n fp) = (fp, 0, n)
 
 -- | /O(1)/ Yield the underlying 'ForeignPtr' together with its length.
 --
--- You can assume the pointer points directly to the data (no offset).
+-- You can assume that the pointer points directly to the data (no offset).
 --
 -- Modifying the data through the 'ForeignPtr' is unsafe if the vector could
--- have frozen before the modification.
+-- have been frozen before the modification.
 unsafeToForeignPtr0 :: MVector s a -> (ForeignPtr a, Int)
 {-# INLINE unsafeToForeignPtr0 #-}
 unsafeToForeignPtr0 (MVector n fp) = (fp, n)
diff --git a/vector/src/Data/Vector/Unboxed/Mutable.hs b/vector/src/Data/Vector/Unboxed/Mutable.hs
index 208f4abf..961cbf5e 100644
--- a/vector/src/Data/Vector/Unboxed/Mutable.hs
+++ b/vector/src/Data/Vector/Unboxed/Mutable.hs
@@ -9,8 +9,7 @@
 -- Stability   : experimental
 -- Portability : non-portable
 --
--- Mutable adaptive unboxed vectors
---
+-- Mutable adaptive unboxed vectors.
 
 module Data.Vector.Unboxed.Mutable (
   -- * Mutable vectors of primitive types
@@ -84,7 +83,7 @@ length :: Unbox a => MVector s a -> Int
 {-# INLINE length #-}
 length = G.length
 
--- | Check whether the vector is empty
+-- | Check whether the vector is empty.
 null :: Unbox a => MVector s a -> Bool
 {-# INLINE null #-}
 null = G.null
@@ -102,32 +101,37 @@ slice :: Unbox a
 {-# INLINE slice #-}
 slice = G.slice
 
--- | Take @n@ first elements of the mutable vector without making a
--- copy. For negative @n@ empty vector is returned. If @n@ is larger
--- than vector's length empty vector is returned,
+-- | Take the @n@ first elements of the mutable vector without making a
+-- copy. For negative @n@, the empty vector is returned. If @n@ is larger
+-- than the vector's length, the vector is returned unchanged.
 take :: Unbox a => Int -> MVector s a -> MVector s a
 {-# INLINE take #-}
 take = G.take
 
--- | Drop @n@ first element of the mutable vector without making a
--- copy. For negative @n@ vector is returned unchanged and if @n@ is
--- larger than vector's length empty vector is returned.
+-- | Drop the @n@ first element of the mutable vector without making a
+-- copy. For negative @n@, the vector is returned unchanged. If @n@ is
+-- larger than the vector's length, the empty vector is returned.
 drop :: Unbox a => Int -> MVector s a -> MVector s a
 {-# INLINE drop #-}
 drop = G.drop
 
+-- | /O(1)/ Split the mutable vector into the first @n@ elements
+-- and the remainder, without copying.
+--
+-- Note that @'splitAt' n v@ is equivalent to @('take' n v, 'drop' n v)@,
+-- but slightly more efficient.
 splitAt :: Unbox a => Int -> MVector s a -> (MVector s a, MVector s a)
 {-# INLINE splitAt #-}
 splitAt = G.splitAt
 
--- | Drop last element of the mutable vector without making a copy. If
--- vector is empty exception is thrown.
+-- | Drop the last element of the mutable vector without making a copy.
+-- If the vector is empty, an exception is thrown.
 init :: Unbox a => MVector s a -> MVector s a
 {-# INLINE init #-}
 init = G.init
 
--- | Drop first element of the mutable vector without making a copy. If
--- vector is empty exception is thrown.
+-- | Drop the first element of the mutable vector without making a copy.
+-- If the vector is empty, an exception is thrown.
 tail :: Unbox a => MVector s a -> MVector s a
 {-# INLINE tail #-}
 tail = G.tail
@@ -142,24 +146,24 @@ unsafeSlice :: Unbox a
 {-# INLINE unsafeSlice #-}
 unsafeSlice = G.unsafeSlice
 
--- | Unsafe variant of 'take'. If called with out of range @n@ it will
--- simply create invalid slice that likely violate memory safety
+-- | Unsafe variant of 'take'. If @n@ is out of range, it will
+-- simply create an invalid slice that likely violate memory safety.
 unsafeTake :: Unbox a => Int -> MVector s a -> MVector s a
 {-# INLINE unsafeTake #-}
 unsafeTake = G.unsafeTake
 
--- | Unsafe variant of 'drop'. If called with out of range @n@ it will
--- simply create invalid slice that likely violate memory safety
+-- | Unsafe variant of 'drop'. If @n@ is out of range, it will
+-- simply create an invalid slice that likely violate memory safety.
 unsafeDrop :: Unbox a => Int -> MVector s a -> MVector s a
 {-# INLINE unsafeDrop #-}
 unsafeDrop = G.unsafeDrop
 
--- | Same as 'init' but doesn't do range checks.
+-- | Same as 'init', but doesn't do range checks.
 unsafeInit :: Unbox a => MVector s a -> MVector s a
 {-# INLINE unsafeInit #-}
 unsafeInit = G.unsafeInit
 
--- | Same as 'tail' but doesn't do range checks.
+-- | Same as 'tail', but doesn't do range checks.
 unsafeTail :: Unbox a => MVector s a -> MVector s a
 {-# INLINE unsafeTail #-}
 unsafeTail = G.unsafeTail
@@ -181,8 +185,8 @@ new :: (PrimMonad m, Unbox a) => Int -> m (MVector (PrimState m) a)
 new = G.new
 
 -- | Create a mutable vector of the given length. The vector content
---   is uninitialized, which means it is filled with whatever underlying memory
---   buffer happens to contain.
+-- is uninitialized, which means it is filled with whatever the
+-- underlying memory buffer happens to contain.
 --
 -- @since 0.5
 unsafeNew :: (PrimMonad m, Unbox a) => Int -> m (MVector (PrimState m) a)
@@ -203,6 +207,7 @@ replicateM = G.replicateM
 
 -- | /O(n)/ Create a mutable vector of the given length (0 if the length is negative)
 -- and fill it with the results of applying the function to each index.
+-- Iteration starts at index 0.
 --
 -- @since 0.12.3.0
 generate :: (PrimMonad m, Unbox a) => Int -> (Int -> a) -> m (MVector (PrimState m) a)
@@ -228,9 +233,9 @@ clone = G.clone
 -- -------
 
 -- | Grow an unboxed vector by the given number of elements. The number must be
--- non-negative. Same semantics as in `G.grow` for generic vector.
+-- non-negative. It has the same semantics as 'G.grow' for generic vectors.
 --
--- ====__Examples__
+-- ==== __Examples__
 --
 -- >>> import qualified Data.Vector.Unboxed as VU
 -- >>> import qualified Data.Vector.Unboxed.Mutable as MVU
@@ -238,10 +243,10 @@ clone = G.clone
 -- >>> mv' <- MVU.grow mv 2
 --
 -- Extra memory at the end of the newly allocated vector is initialized to 0
--- bytes, which for `Unbox` instance will usually correspond to some default
--- value for a particular type, eg. @0@ for @Int@, @False@ for @Bool@,
--- etc. However, if `unsafeGrow` was used instead this would not have been
--- guaranteed and some garbage would be there instead:
+-- bytes, which for 'Unbox' instance will usually correspond to some default
+-- value for a particular type, e.g. @0@ for @Int@, @False@ for @Bool@,
+-- etc. However, if 'unsafeGrow' was used instead, this would not have been
+-- guaranteed and some garbage would be there instead.
 --
 -- >>> VU.freeze mv'
 -- [('a',10),('b',20),('c',30),('\NUL',0),('\NUL',0)]
@@ -263,16 +268,16 @@ clone = G.clone
 --
 -- @since 0.5
 grow :: (PrimMonad m, Unbox a)
-              => MVector (PrimState m) a -> Int -> m (MVector (PrimState m) a)
+     => MVector (PrimState m) a -> Int -> m (MVector (PrimState m) a)
 {-# INLINE grow #-}
 grow = G.grow
 
--- | Grow a vector by the given number of elements. The number must be non-negative but
--- this is not checked. Same semantics as in `G.unsafeGrow` for generic vector.
+-- | Grow a vector by the given number of elements. The number must be non-negative, but
+-- this is not checked. This has the same semantics as 'G.unsafeGrow' for generic vectors.
 --
 -- @since 0.5
 unsafeGrow :: (PrimMonad m, Unbox a)
-               => MVector (PrimState m) a -> Int -> m (MVector (PrimState m) a)
+           => MVector (PrimState m) a -> Int -> m (MVector (PrimState m) a)
 {-# INLINE unsafeGrow #-}
 unsafeGrow = G.unsafeGrow
 
@@ -326,8 +331,7 @@ unsafeRead :: (PrimMonad m, Unbox a) => MVector (PrimState m) a -> Int -> m a
 unsafeRead = G.unsafeRead
 
 -- | Replace the element at the given position. No bounds checks are performed.
-unsafeWrite
-    :: (PrimMonad m, Unbox a) =>  MVector (PrimState m) a -> Int -> a -> m ()
+unsafeWrite :: (PrimMonad m, Unbox a) =>  MVector (PrimState m) a -> Int -> a -> m ()
 {-# INLINE unsafeWrite #-}
 unsafeWrite = G.unsafeWrite
 
@@ -345,8 +349,7 @@ unsafeModifyM :: (PrimMonad m, Unbox a) => MVector (PrimState m) a -> (a -> m a)
 unsafeModifyM = G.unsafeModifyM
 
 -- | Swap the elements at the given positions. No bounds checks are performed.
-unsafeSwap
-    :: (PrimMonad m, Unbox a) => MVector (PrimState m) a -> Int -> Int -> m ()
+unsafeSwap :: (PrimMonad m, Unbox a) => MVector (PrimState m) a -> Int -> Int -> m ()
 {-# INLINE unsafeSwap #-}
 unsafeSwap = G.unsafeSwap
 
@@ -374,7 +377,7 @@ copy :: (PrimMonad m, Unbox a)
 copy = G.copy
 
 -- | Copy a vector. The two vectors must have the same length and may not
--- overlap. This is not checked.
+-- overlap, but this is not checked.
 unsafeCopy :: (PrimMonad m, Unbox a)
            => MVector (PrimState m) a   -- ^ target
            -> MVector (PrimState m) a   -- ^ source
@@ -410,13 +413,15 @@ unsafeMove :: (PrimMonad m, Unbox a)
 {-# INLINE unsafeMove #-}
 unsafeMove = G.unsafeMove
 
--- | Compute the next (lexicographically) permutation of given vector in-place.
---   Returns False when input is the last permutation
+-- Modifying vectors
+-- -----------------
+
+-- | Compute the (lexicographically) next permutation of the given vector in-place.
+-- Returns False when the input is the last permutation.
 nextPermutation :: (PrimMonad m,Ord e,Unbox e) => MVector (PrimState m) e -> m Bool
 {-# INLINE nextPermutation #-}
 nextPermutation = G.nextPermutation
 
-
 -- Folds
 -- -----
 
@@ -436,7 +441,7 @@ imapM_ :: (PrimMonad m, Unbox a) => (Int -> a -> m b) -> MVector (PrimState m) a
 imapM_ = G.imapM_
 
 -- | /O(n)/ Apply the monadic action to every element of the vector,
--- discarding the results. It's same as the @flip mapM_@.
+-- discarding the results. It's the same as @flip mapM_@.
 --
 -- @since 0.12.3.0
 forM_ :: (PrimMonad m, Unbox a) => MVector (PrimState m) a -> (a -> m b) -> m ()
@@ -444,7 +449,7 @@ forM_ :: (PrimMonad m, Unbox a) => MVector (PrimState m) a -> (a -> m b) -> m ()
 forM_ = G.forM_
 
 -- | /O(n)/ Apply the monadic action to every element of the vector
--- and its index, discarding the results. It's same as the @flip imapM_@.
+-- and its index, discarding the results. It's the same as @flip imapM_@.
 --
 -- @since 0.12.3.0
 iforM_ :: (PrimMonad m, Unbox a) => MVector (PrimState m) a -> (Int -> a -> m b) -> m ()
@@ -465,14 +470,14 @@ foldl' :: (PrimMonad m, Unbox a) => (b -> a -> b) -> b -> MVector (PrimState m)
 {-# INLINE foldl' #-}
 foldl' = G.foldl'
 
--- | /O(n)/ Pure left fold (function applied to each element and its index).
+-- | /O(n)/ Pure left fold using a function applied to each element and its index.
 --
 -- @since 0.12.3.0
 ifoldl :: (PrimMonad m, Unbox a) => (b -> Int -> a -> b) -> b -> MVector (PrimState m) a -> m b
 {-# INLINE ifoldl #-}
 ifoldl = G.ifoldl
 
--- | /O(n)/ Pure left fold with strict accumulator (function applied to each element and its index).
+-- | /O(n)/ Pure left fold with strict accumulator using a function applied to each element and its index.
 --
 -- @since 0.12.3.0
 ifoldl' :: (PrimMonad m, Unbox a) => (b -> Int -> a -> b) -> b -> MVector (PrimState m) a -> m b
@@ -493,15 +498,15 @@ foldr' :: (PrimMonad m, Unbox a) => (a -> b -> b) -> b -> MVector (PrimState m)
 {-# INLINE foldr' #-}
 foldr' = G.foldr'
 
--- | /O(n)/ Pure right fold (function applied to each element and its index).
+-- | /O(n)/ Pure right fold using a function applied to each element and its index.
 --
 -- @since 0.12.3.0
 ifoldr :: (PrimMonad m, Unbox a) => (Int -> a -> b -> b) -> b -> MVector (PrimState m) a -> m b
 {-# INLINE ifoldr #-}
 ifoldr = G.ifoldr
 
--- | /O(n)/ Pure right fold with strict accumulator (function applied
--- to each element and its index).
+-- | /O(n)/ Pure right fold with strict accumulator using a function applied
+-- to each element and its index.
 --
 -- @since 0.12.3.0
 ifoldr' :: (PrimMonad m, Unbox a) => (Int -> a -> b -> b) -> b -> MVector (PrimState m) a -> m b
@@ -522,14 +527,14 @@ foldM' :: (PrimMonad m, Unbox a) => (b -> a -> m b) -> b -> MVector (PrimState m
 {-# INLINE foldM' #-}
 foldM' = G.foldM'
 
--- | /O(n)/ Monadic fold (action applied to each element and its index).
+-- | /O(n)/ Monadic fold using a function applied to each element and its index.
 --
 -- @since 0.12.3.0
 ifoldM :: (PrimMonad m, Unbox a) => (b -> Int -> a -> m b) -> b -> MVector (PrimState m) a -> m b
 {-# INLINE ifoldM #-}
 ifoldM = G.ifoldM
 
--- | /O(n)/ Monadic fold with strict accumulator (action applied to each element and its index).
+-- | /O(n)/ Monadic fold with strict accumulator using a function applied to each element and its index.
 --
 -- @since 0.12.3.0
 ifoldM' :: (PrimMonad m, Unbox a) => (b -> Int -> a -> m b) -> b -> MVector (PrimState m) a -> m b
@@ -550,15 +555,15 @@ foldrM' :: (PrimMonad m, Unbox a) => (a -> b -> m b) -> b -> MVector (PrimState
 {-# INLINE foldrM' #-}
 foldrM' = G.foldrM'
 
--- | /O(n)/ Monadic right fold (action applied to each element and its index).
+-- | /O(n)/ Monadic right fold using a function applied to each element and its index.
 --
 -- @since 0.12.3.0
 ifoldrM :: (PrimMonad m, Unbox a) => (Int -> a -> b -> m b) -> b -> MVector (PrimState m) a -> m b
 {-# INLINE ifoldrM #-}
 ifoldrM = G.ifoldrM
 
--- | /O(n)/ Monadic right fold with strict accumulator (action applied
--- to each element and its index).
+-- | /O(n)/ Monadic right fold with strict accumulator using a function applied
+-- to each element and its index.
 --
 -- @since 0.12.3.0
 ifoldrM' :: (PrimMonad m, Unbox a) => (Int -> a -> b -> m b) -> b -> MVector (PrimState m) a -> m b