Clarify docs for the Json.Decode (:=) operator.

[rgrempel]

The purpose of this change would be to clarify the documentation for the Json.Decode (:=) operator.

It seems to me that the current documentation ("Decode an object if it has a certain field"), could be misleading to some people. Consider an example JSON object, e.g.

{
    "username": "bob",
    "password": "secret"
}

Then, consider the work done by something like:

"username" := string

The 'object' which this decodes is "bob". But, "bob" does not have the field 'username' -- it is the field 'username'. To the extent that the whole object is decoded -- that is, the object which 'has' the field 'username' -- the whole object is decoded by something like Json.Decode.object2.

Also, I think that it would be helpful to specifically mention the word "fail", rather than simply leave it at "if". This lines up with the use of the word "fail" in the rest of the docs -- thus, pointing the user to what can be done to deal with failure.

[fbonetti]

👍

[fbonetti]

👍