Disambiguate documentation for strict & lazy parsers

[remysucre]

It's not very clear to me how the strict parser differs from the lazy one from the documentation:

It can be useful to think of parsing as occurring in two phases:

• Identification of the textual boundaries of a JSON value. This is always strict, so that an invalid JSON document can be rejected as soon as possible.
• Conversion of a JSON value to a Haskell value. This may be either immediate (strict) or deferred (lazy); see below for details.

Initially I thought "Haskell value" is the user-defined datatype that is an instance of FromJSON, but the source suggests that decode' json' don't really have control over that. Then is it actually the Value? If that is the case, then how is "JSON value" represented, if not as Value?

I'm also curious to find all fields of Value are strict: doesn't that cancel out any laziness from the lazy parser (json decode)? In fact, on the the benchmark AesonParse.hs supplied the lazy and strict parsers have identical performance (I tried changing json to json' and ran both with bench-parse.py).

[andrewthad]

This is a good question. Based on my reading of the code, I am also unable to figure out what the difference between the strict and lazy variants of decode is.

[chshersh]

I'm also confused by current documentation but didn't found this issue and asked my question on StackOverflow.

[bergmark]

Cool, seems like that was a better way to get a good answer :)

It would be nice to add a shorter explanation with a link to the docs, is anyone up for it?

[phadej]

In aeson-2.2 there won't be difference between decode and decode'. I'll update the docs.