@@ -96,7 +96,11 @@ foldl' f z arr = runIdentity $ D.foldl' f z $ toStreamD arr
9696foldr :: (a -> b -> b) -> b -> SmallArray a -> b
9797foldr f z arr = runIdentity $ D.foldr f z $ toStreamD arr
9898
99−-- writeN n = S.evertM (fromStreamDN n)
99+-- | @writeN n@ folds a maximum of @n@ elements from the input stream to an
100+-- 'SmallArray'.
101+--
102+-- Since we are folding to a 'SmallArray' @n@ should be <= 128, for larger number
103+-- of elements use an 'Array' from either "Streamly.Data.Array" or "Streamly.Memory.Array".
100104{-# INLINE_NORMAL writeN #-}
101105writeN :: MonadIO m => Int -> Fold m a (SmallArray a)
102106writeN limit = Fold step initial extract
@@ -122,6 +126,13 @@ fromStreamDN limit str = do
122126 D.take limit str
123127 liftIO $ freezeSmallArray marr 0 i
124128
129+-- | Create a 'SmallArray' from the first @n@ elements of a list. The
130+-- array may hold less than @n@ elements if the length of the list <=
131+-- @n@.
132+--
133+-- It is recommended to use a value of @n@ <= 128. For larger sized
134+-- arrays, use an 'Array' from "Streamly.Data.Array" or
135+-- "Streamly.Memory.Array"
125136{-# INLINABLE fromListN #-}
126137fromListN :: Int -> [a] -> SmallArray a
127138fromListN n xs = unsafePerformIO $ fromStreamDN n $ D.fromList xs
@@ -130,6 +141,11 @@ instance NFData a => NFData (SmallArray a) where
130141 {-# INLINE rnf #-}
131142 rnf = foldl' (\_ x -> rnf x) ()
132143
144+-- | Create a 'SmallArray' from the first @n@ elements of a stream. The
145+-- array is allocated to size @n@, if the stream terminates before @n@
146+-- elements then the array may hold less than @n@ elements.
147+--
148+-- For optimal performance use this with @n@ <= 128.
133149{-# INLINE fromStreamN #-}
134150fromStreamN :: MonadIO m => Int -> SerialT m a -> m (SmallArray a)
135151fromStreamN n m = do