@@ -293,14 +293,21 @@ genericLiftParseJSON opts pj pjl = fmap to1 . gParseJSON opts (From1Args pj pjl)
293293--
294294-- The basic ways to signal a failed conversion are as follows:
295295--
296−-- * 'empty' and 'mzero' work, but are terse and uninformative;
296+-- * 'fail' yields a custom error message: it is the recommended way of
297+-- reporting a failure;
297298--
298−-- * 'fail' yields a custom error message;
299+-- * 'Control.Applicative.empty' (or 'Control.Monad.mzero') is uninformative:
300+-- use it when the error is meant to be caught by some @('<|>')@;
299301--
300−-- * 'typeMismatch' produces an informative message for cases when the
301−-- value encountered is not of the expected type.
302+-- * 'typeMismatch' can be used to report a failure when the encountered value
303+-- is not of the expected JSON type; 'unexpected' is an appropriate alternative
304+-- when more than one type may be expected, or to keep the expected type
305+-- implicit.
302306--
303−-- An example type and instance using 'typeMismatch':
307+-- 'prependFailure' (or 'modifyFailure') add more information to a parser's
308+-- error messages.
309+--
310+-- An example type and instance using 'typeMismatch' and 'prependFailure':
304311--
305312-- @
306313-- \-- Allow ourselves to write 'Text' literals.
@@ -314,9 +321,11 @@ genericLiftParseJSON opts pj pjl = fmap to1 . gParseJSON opts (From1Args pj pjl)
314321-- '<*>' v '.:' \"y\"
315322--
316323-- \-- We do not expect a non-'Object' value here.
317−-- \-- We could use 'mzero' to fail, but 'typeMismatch'
324+-- \-- We could use 'Control.Applicative.empty' to fail, but 'typeMismatch'
318325-- \-- gives a much more informative error message.
319−-- 'parseJSON' invalid = 'typeMismatch' \"Coord\" invalid
326+-- 'parseJSON' invalid =
327+-- 'prependFailure' "parsing Coord failed, "
328+-- ('typeMismatch' \"Object\" invalid)
320329-- @
321330--
322331-- For this common case of only being concerned with a single
@@ -359,7 +368,7 @@ genericLiftParseJSON opts pj pjl = fmap to1 . gParseJSON opts (From1Args pj pjl)
359368-- @
360369--
361370-- The default implementation will be equivalent to
362−-- @parseJSON = 'genericParseJSON' 'defaultOptions'@; If you need different
371+-- @parseJSON = 'genericParseJSON' 'defaultOptions'@; if you need different
363372-- options, you can customize the generic decoding by defining:
364373--
365374-- @