Add comparison/migration guide to failure

[shepmaster]

This will be obviously biased, but we can compare against what is in the documentation as best we can.

[lnicola]

I ported some code from failure. Some remarks:

• I was using tuple enum items, and I had to name the fields because the documentation didn't say whether they were supported or not
• It's not obvious that the source field is mandatory (fail is nifty, though)
• I'm somewhat worried about the size of the Results. IIRC the compiler is bad at optimizing them, and sometimes it might be better to do an allocation instead.
• I didn't look too much into it, but I'm not sure what eager_context is about

[shepmaster]

the documentation didn't say whether they were supported or not

They are not, but I’m open to discussion about it. I've opened #61 to talk about it.

I should also add this fact explicitly to the docs. You do get a specific error if you try to use tuple variants though.

the source field is mandatory

It is not; but if there’s no source field you can’t use context (where would the Result::Err go?). Instead you just use ContextSelector { fields }.fail(). Can you expand a bit more on wwhat you mean by "mandatory"?

• the size of the Results

Do you mean Result or the enum Error type? I would expect that the size of the enum is max(size-of(variants)) + 1 byte + small amount padding) if you have less than 256 variants. There is some discussion elsewhere about better supporting boxing source errors which might help a bit.

• what eager_context is about

TL;DR, context is used with ? and eager_context is used without ?.

[lnicola]

It is not; but if there’s no source field you can’t use context (where would the Result::Err go?). Instead you just use ContextSelector { fields }.fail(). Can you expand a bit more on wwhat you mean by "mandatory"?

I don't have anything more to add to my comment in #10 (comment). Again, I don't mind the way it works, it's just an issue I ran into because I wasn't aware of fail().

Do you mean Result or the enum Error type?

The Error enum, as the variants could presumably grow pretty large, depending on how many errors you're nesting.