@@ -571,6 +571,16 @@ instance FromField JSON.Value where
571571--
572572-- The 'Typeable' constraint is required to show more informative
573573-- error messages when parsing fails.
574+--
575+-- Note that @fromJSONField :: FieldParser ('Maybe' Foo)@ will return
576+-- @'Nothing'@ on the json @null@ value, and return an exception on SQL @null@
577+-- value. Alternatively, one could write @'optionalField' fromJSONField@
578+-- that will return @Nothing@ on SQL @null@, and otherwise will call
579+-- @fromJSONField :: FieldParser Foo@ and then return @'Just'@ the
580+-- result value, or return its exception. If one would
581+-- like to return @Nothing@ on both the SQL @null@ and json @null@ values,
582+-- one way to do it would be to write
583+-- @\\f mv -> 'Control.Monad.join' '<$>' optionalField fromJSONField f mv@
574584fromJSONField :: (JSON.FromJSON a, Typeable a) => FieldParser a
575585fromJSONField f mbBs = do
576586 value <- fromField f mbBs