@@ -568,6 +568,39 @@ data Options = Options
568 -- ^ If 'True' record fields with a 'Nothing' value will be
568 -- ^ If 'True' record fields with a 'Nothing' value will be
569 -- omitted from the resulting object. If 'False' the resulting
569 -- omitted from the resulting object. If 'False' the resulting
570 -- object will include those fields mapping to @null@.
570 -- object will include those fields mapping to @null@.
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.
582+ -- The generic instance for the following type @Fruit@ depends on whether
583+ -- the instance head is @Fruit a@ or @Fruit (Maybe a)@.
587+ -- { apples :: a -- A field whose type is a type variable.
588+ -- , oranges :: 'Maybe' Int
591+ -- options :: 'Options'
592+ -- options = 'defaultOptions' { 'omitNothingFields' = 'True' }
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
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
571 , sumEncoding :: SumEncoding
604 , sumEncoding :: SumEncoding
572 -- ^ Specifies how to encode constructors of a sum datatype.
605 -- ^ Specifies how to encode constructors of a sum datatype.
573 , unwrapUnaryRecords :: Bool
606 , unwrapUnaryRecords :: Bool