Merge pull request #500 from AlexMaryW/improve-fromlist-docs

Improve `fromList` docs

vector/src/Data/Vector.hs

@@ -2172,7 +2172,15 @@ toList :: Vector a -> [a]
 {-# INLINE toList #-}
 toList = G.toList
 
--- | /O(n)/ Convert a list to a vector.
+-- | /O(n)/ Convert a list to a vector. During the operation, the 
+-- vector’s capacity will be doubling until the list's contents are 
+-- in the vector. Depending on the list’s size, up to half of the vector’s 
+-- capacity might be empty. If you’d rather avoid this, you can use 
+-- 'fromListN', which will provide the exact space the list requires but will 
+-- prevent list fusion, or @'force' . 'fromList'@, which will create the 
+-- vector and then copy it without the superfluous space.
+--
+-- @since 0.3
 fromList :: [a] -> Vector a
 {-# INLINE fromList #-}
 fromList = G.fromList

vector/src/Data/Vector/Generic.hs

@@ -2364,7 +2364,15 @@ toList :: Vector v a => v a -> [a]
 {-# INLINE toList #-}
 toList = Bundle.toList . stream
 
--- | /O(n)/ Convert a list to a vector.
+-- | /O(n)/ Convert a list to a vector. During the operation, the 
+-- vector’s capacity will be doubling until the list's contents are 
+-- in the vector. Depending on the list’s size, up to half of the vector’s 
+-- capacity might be empty. If you’d rather avoid this, you can use 
+-- 'fromListN', which will provide the exact space the list requires but will 
+-- prevent list fusion, or @'force' . 'fromList'@, which will create the 
+-- vector and then copy it without the superfluous space.
+--
+-- @since 0.4
 fromList :: Vector v a => [a] -> v a
 {-# INLINE fromList #-}
 fromList = unstream . Bundle.fromList

vector/src/Data/Vector/Primitive.hs

@@ -1836,7 +1836,15 @@ toList :: Prim a => Vector a -> [a]
 {-# INLINE toList #-}
 toList = G.toList
 
--- | /O(n)/ Convert a list to a vector.
+-- | /O(n)/ Convert a list to a vector. During the operation, the 
+-- vector’s capacity will be doubling until the list's contents are 
+-- in the vector. Depending on the list’s size, up to half of the vector’s 
+-- capacity might be empty. If you’d rather avoid this, you can use 
+-- 'fromListN', which will provide the exact space the list requires but will 
+-- prevent list fusion, or @'force' . 'fromList'@, which will create the 
+-- vector and then copy it without the superfluous space.
+--
+-- @since 0.4
 fromList :: Prim a => [a] -> Vector a
 {-# INLINE fromList #-}
 fromList = G.fromList

vector/src/Data/Vector/Storable.hs

@@ -1883,7 +1883,15 @@ toList :: Storable a => Vector a -> [a]
 {-# INLINE toList #-}
 toList = G.toList
 
--- | /O(n)/ Convert a list to a vector.
+-- | /O(n)/ Convert a list to a vector. During the operation, the 
+-- vector’s capacity will be doubling until the list's contents are 
+-- in the vector. Depending on the list’s size, up to half of the vector’s 
+-- capacity might be empty. If you’d rather avoid this, you can use 
+-- 'fromListN', which will provide the exact space the list requires but will 
+-- prevent list fusion, or @'force' . 'fromList'@, which will create the 
+-- vector and then copy it without the superfluous space.
+--
+-- @since 0.4
 fromList :: Storable a => [a] -> Vector a
 {-# INLINE fromList #-}
 fromList = G.fromList

vector/src/Data/Vector/Strict.hs

@@ -2442,7 +2442,13 @@ toList :: Vector a -> [a]
 {-# INLINE toList #-}
 toList = G.toList
 
--- | /O(n)/ Convert a list to a vector.
+-- | /O(n)/ Convert a list to a vector. During the operation, the 
+-- vector’s capacity will be doubling until the list's contents are 
+-- in the vector. Depending on the list’s size, up to half of the vector’s 
+-- capacity might be empty. If you’d rather avoid this, you can use 
+-- 'fromListN', which will provide the exact space the list requires but will 
+-- prevent list fusion, or @'force' . 'fromList'@, which will create the 
+-- vector and then copy it without the superfluous space.
 --
 -- @since 0.13.2.0
 fromList :: [a] -> Vector a

vector/src/Data/Vector/Unboxed.hs

@@ -1928,7 +1928,15 @@ toList :: Unbox a => Vector a -> [a]
 {-# INLINE toList #-}
 toList = G.toList
 
--- | /O(n)/ Convert a list to a vector.
+-- | /O(n)/ Convert a list to a vector. During the operation, the 
+-- vector’s capacity will be doubling until the list's contents are 
+-- in the vector. Depending on the list’s size, up to half of the vector’s 
+-- capacity might be empty. If you’d rather avoid this, you can use 
+-- 'fromListN', which will provide the exact space the list requires but will 
+-- prevent list fusion, or @'force' . 'fromList'@, which will create the 
+-- vector and then copy it without the superfluous space.
+--
+-- @since 0.3
 fromList :: Unbox a => [a] -> Vector a
 {-# INLINE fromList #-}
 fromList = G.fromList