@@ -568,6 +568,39 @@ data Options = Options
568568 -- ^ If 'True' record fields with a 'Nothing' value will be
569569 -- omitted from the resulting object. If 'False' the resulting
570570 -- object will include those fields mapping to @null@.
571+ --
572+ -- === Note
573+ --
574+ -- Setting 'omitNothingFields' to 'True' only affects fields which are of
575+ -- type 'Maybe' /uniformly/ in the 'ToJSON' or 'FromJSON' instance. In
576+ -- particular, if the type of a field is declared as a type variable, it
577+ -- will not be omitted from the JSON object, unless the field is
578+ -- specialized upfront in the instance.
579+ --
580+ -- ==== __Example__
581+ --
582+ -- The generic instance for the following type @Fruit@ depends on whether
583+ -- the instance head is @Fruit a@ or @Fruit (Maybe a)@.
584+ --
585+ -- @
586+ -- data Fruit a =
587+ -- { apples :: a -- A field whose type is a type variable.
588+ -- , oranges :: 'Maybe' Int
589+ -- }
590+ --
591+ -- options :: 'Options'
592+ -- options = 'defaultOptions' { 'omitNothingFields' = 'True' }
593+ --
594+ -- -- apples required, oranges optional
595+ -- -- Even if 'Data.Aeson.fromJSON' is then specialized to (Fruit ('Maybe' a)).
596+ -- instance 'Data.Aeson.FromJSON' a => 'Data.Aeson.FromJSON' (Fruit a) where
597+ -- 'Data.Aeson.fromJSON' = 'Data.Aeson.genericFromJSON' options
598+ --
599+ -- -- apples optional, oranges optional
600+ -- -- In this instance, the field apples is uniformly of type ('Maybe' a).
601+ -- instance 'Data.Aeson.FromJSON' a => 'Data.Aeson.FromJSON' (Fruit ('Maybe' a)) where
602+ -- 'Data.Aeson.fromJSON' = 'Data.Aeson.genericFromJSON' options
603+ -- @
571604 , sumEncoding :: SumEncoding
572605 -- ^ Specifies how to encode constructors of a sum datatype.
573606 , unwrapUnaryRecords :: Bool