Improve documentation for zip/unzip for unboxed vectors

vector/src/Data/Vector/Unboxed.hs

@@ -132,12 +132,15 @@ module Data.Vector.Unboxed (
   -- ** Zipping
   zipWith, zipWith3, zipWith4, zipWith5, zipWith6,
   izipWith, izipWith3, izipWith4, izipWith5, izipWith6,
+  -- *** Zipping tuples
+  -- $zip
   zip, zip3, zip4, zip5, zip6,
 
   -- ** Monadic zipping
   zipWithM, izipWithM, zipWithM_, izipWithM_,
 
   -- ** Unzipping
+  -- $unzip
   unzip, unzip3, unzip4, unzip5, unzip6,
 
   -- * Working with predicates
@@ -970,6 +973,26 @@ iforM_ = G.iforM_
 -- Zipping
 -- -------
 
+-- $zip
+--
+-- Following functions could be used to construct vector of tuples
+-- from tuple of vectors. This operation is done in /O(1)/ time and
+-- will share underlying buffers.
+--
+-- Note that variants from "Data.Vector.Generic" doesn't have this
+-- property.
+
+-- $unzip
+--
+-- Following functions could be used to access underlying
+-- representation of array of tuples. They convert array to tuple of
+-- arrays. This operation is done in /O(1)/ time and will share
+-- underlying buffers.
+--
+-- Note that variants from "Data.Vector.Generic" doesn't have this
+-- property.
+
+
 -- | /O(min(m,n))/ Zip two vectors with the given function.
 zipWith :: (Unbox a, Unbox b, Unbox c)
         => (a -> b -> c) -> Vector a -> Vector b -> Vector c

vector/src/Data/Vector/Unboxed/Mutable.hs

@@ -42,6 +42,7 @@ module Data.Vector.Unboxed.Mutable (
   clear,
 
   -- * Zipping and unzipping
+  -- $zip
   zip, zip3, zip4, zip5, zip6,
   unzip, unzip3, unzip4, unzip5, unzip6,
 
@@ -632,6 +633,13 @@ ifoldrM' :: (PrimMonad m, Unbox a) => (Int -> a -> b -> m b) -> b -> MVector (Pr
 ifoldrM' = G.ifoldrM'
 
 
+-- $zip
+--
+-- Following functions provide access to the representation of vector
+-- of tuples. Internally it's product of vectors for each element of
+-- tuple. Conversions are performed in /O(1)/ and produced vector will
+-- share underlying buffers with parameter vectors.
+
 #define DEFINE_MUTABLE
 #include "unbox-tuple-instances"