@@ -261,9 +261,11 @@ unpin arr@(MutableByteArray marr#) =
261261-- deserializes the boxed type from the mutable byte array. The write operation
262262-- 'pokeByteIndex' serializes the boxed type to the mutable byte array.
263263--
264−-- Instances can be derived via 'Generic'. Note that the data type must be
265−-- non-recursive. Here is an example, for deriving an instance of this type
266−-- class.
264+-- Instances can be derived via Generics or Template Haskell. Note that the data
265+-- type must be non-recursive.
266+--
267+-- Here is an example, for deriving an instance of this type class using
268+-- generics:
267269--
268270-- >>> import GHC.Generics (Generic)
269271-- >>> :{
@@ -273,7 +275,24 @@ unpin arr@(MutableByteArray marr#) =
273275-- } deriving Generic
274276-- :}
275277--
276−-- WARNING! Generic deriving hangs for recursive data types.
278+-- To derive the instance via Template Haskell:
279+--
280+-- @
281+-- import Streamly.Data.Unbox (deriveUnbox)
282+-- $(deriveUnbox ''Object)
283+-- @
284+--
285+-- See 'Streamly.Data.Unbox.deriveUnbox' and
286+-- 'Streamly.Data.Unbox.deriveUnboxWith' for more information on deriving using
287+-- Template Haskell.
288+--
289+-- Deriving via Template Haskell should be preferred for the following reasons:
290+-- 1. Instances derived via Template Haskell have more performant routines.
291+-- 2. Template Haskell deriving can handle (maxBound :: Word64) number of
292+-- constructors whereas the Generic deriving can only handle 256.
293+--
294+-- WARNING! Generic and Template Haskell deriving, both hang for recursive data
295+-- types.
277296--
278297-- >>> import Streamly.Data.Array (Unbox(..))
279298-- >>> instance Unbox Object