Circe: Clarify the role of DecodingFailure's "message"

[travisbrown]

circe's DecodingFailure is a descendant of Argonaut's (String, CursorHistory) in DecodeResult, and in Argonaut there's some ambiguity about what the string represents—in some places it's just a string representation of the type, and in other places it's a more detailed message about what went wrong. Since it doesn't have a name in Argonaut (and the corresponding argument to e.g. DecodeResult.fail is just named s), the library doesn't seem to make any particular commitment to how the string should be interpreted.

I originally planned to provide more guidance here in circe, but we're at version 0.5 and message in DecodingFailure is still playing both roles, and now the new DecodingFailure.fromThrowable in #303 puts a printed stack trace in the message field, which introduces yet another kind of thing that it can do.

I'd be interested in any suggestions about how we can refine the fields in DecodingFailure to make it clear what each one should do. One straightforward approach would be just to add new fields: something like name: String, message: String, an optional underlying: Option[Throwable], and the lazy CursorHistory, but I'm definitely open to other ideas.

[tomjadams]

Without knowing the particular piece of code overly well, your suggestions seem like a good first approach. Have you tried it and seen how the code pans out?

[liff]

Just my €0.000002:

Personally, I'd be very much in favour of more descriptive error messages.

I think, compared to message being just the name of the type, The name, message, underlying triplet sounds very good. In particular, the stack trace in DecodingFailure.fromThrowable would make more sense as a separate field. Right now the failure messages from Decoder#emapTry are rather inconveniently messy :)

[jatcwang]

My preference is actual error classes representing common error cases. This gives the developers freedom to transform a decoding error into w/e output they need.

I think these should cover the common errors:

• Missing Field
• Incorrect Type (wrong JSON type)
• Invalid data (e.g. constraint violation across multiple fields like start cannot be after end for a java.time.Period)

[fleipold]

While this is being pondered it would be nice to just use the Show instance added in #222 to produce the message. That way we would get the nice javascript-style path for the history which is much more usable for bigger documents.