Show use of `.fail()` method in user guide

[tkaitchuck]

I am not sure is this is a duplicate of https://github.com/shepmaster/snafu/issues/192 but I found myself in the following situation:

match type_of_thing {
  type1 => //do something
  type2 => //something else
  _ => ensure!(false, InvalidType { type: type_of_thing })
}

Of course this doesn't work if the match block is expected to return a result type. I don't really see any neat way to do that if the InvalidType error is going to contain a backtrace.

So from my POV it would be ideal to have some other macro which works like ensure, but doesn't take the boolean.

[shepmaster]

One thing mentioned in #192 is this:

ContextSelector {/* ... */}.fail();

Applied, it would look like

use snafu::{Backtrace, Snafu};

#[derive(Debug, Snafu)]
enum Error {
    InvalidType { v: i32, backtrace: Backtrace },
}

type Result<T, E = Error> = std::result::Result<T, E>;

fn example() -> Result<()> {
    let v = 42;

    match v {
        1 => println!("do something"),
        2 => println!("something else"),
        _ => InvalidType { v }.fail()?,
    };

    Ok(())
}

Does that work for your case?

[shepmaster]

Comparing the two possibilities shows it's only a single character difference:

InvalidType { v }.fail()?
bail!(InvalidType { v })

[tkaitchuck]

Awesome. That works. It just was not very discoverable. Perhaps an example showing that could be added to the docs.