Write extensive documentation on the crate and the macro

[irevoire]

Fix #14

[dureuill]

The README motivates the need for the library really well, and explains the available options clearly.

I have a few suggestions, see inline comments

[loiclec]

Excellent! Thank you so much for making deserr such a proper, well-documented, well-tested, ambitious crate :-)

[loiclec]

I would really like at least one example where a custom function provided by the user returns a non-generic type. Maybe we can add one after the error container/field attribute is explained. Maybe also as an example for the MergeWithError trait?

[irevoire]

Yep that's true, it would be nice to show how to use the MergeWithError trait

[dureuill]

Beautiful README. I have a couple of additional suggestions but feel free to apply or not.

(other reviewers might also have outstanding comments)

[loiclec]

Excellent, thank you :)
I added a few more comments. The only ones that are truly important are those that concern outdated derive attribute names and code samples. Otherwise, I would approve it!

Outdated code samples:

The following still uses Result in the comment instead of ControlFlow:

impl DeserializeError for MyError {
    /// Create a new error with the custom message.
    ///
    /// Return `Ok` to continue deserializing or `Err` to fail early.
    fn error<V: IntoValue>(_self_: Option<Self>, error: ErrorKind<V>, location: ValuePointerRef) -> ControlFlow<Self, Self> {
        ControlFlow::Break(Self::Other(take_cf_content(JsonError::error(None, error, location))))
    }
}

(Also: should we rename the parameters of merge from (self_, other, ...) to (existing/prev, next/new)?)

I didn't check, but is the following implementation necessary?

impl From<JsonError> for MyError {
    fn from(error: JsonError) -> Self {
        Self::Other(error)
    }
}

Other suggestions:
I wrote the "Robert '); DROP TABLE Students; --" code sample, but I don't find it very nice anymore. It seems a bit complicated because we implement all the traits manually, but at the same time it does not show many benefits of deserr. I think it undersells it. Maybe we could move it at the end, or instead link to an example code instead? For example, here's how you would implement the trait manually: <link to example file>. Also, maybe saying something lile:

deserr offers a derive proc macro to automatically implement Deserr for your types. However, unlike serde, it is also very easy to implement these traits manually. See <this file/folder> etc...

[loiclec]

Future improvement: don't say one of when there is only one accepted field?

[loiclec]

No for deserr, but mostly not applicable or not needed, right? Because we have made the choice to force the use of the default field attribute.

[irevoire]

I don’t think that’s related?
We could let people have a default container attribute so you don’t have to specify it as a field attribute right?