Add use-site examples to the attributes section of the guide

[shepmaster]

https://docs.rs/snafu/0.4.1/snafu/guide/attributes/index.html#transforming-the-source could use examples of what changes in the code handling errors or something. Otherwise it's not immediately clear what have actually changed.

[mikeando]

One question I thought of when looking at that section, is "can we apply this multiple times to a given entry".

i.e.

#[derive(Debug, Snafu)]
enum Error {
    SourceNeedsToBeConverted {
        #[snafu(
              source(from(another::ErrorIO, from_io_error)),
              source(from(another::ErrorInitialization, from_init_error))
        )]
        source: Box<another::ErrorBase>,
    },
}

I suspect the answer is currently "no".

But, I suspect but such a method might help me reduce the number of error types I end up with in my applications.

[shepmaster]

can we apply this multiple times to a given entry

This was an idea that I had in mind when implementing it. You are right that it's not currently supported. It's not a trivial amount of work, but it isn't impossible either.

[tjkirch]

I think it'd be worth having a separate issue for supporting multiple source(from) attributes. To rephrase, the goal would be to allow multiple source error types to use the same context selector, right?

#[derive(Debug, Snafu)]
enum Error {
   IoOrFmtError {
      #[snafu(source(from(std::fmt::Error, from_fmt_error)))]
      #[snafu(source(from(std::io::Error, from_io_error)))]
      source: Box<ErrorBase>,
   },
}

fn_that_generates_io_error().context(IoOrFmtError)?;
fn_that_generates_fmt_error().context(IoOrFmtError)?;

---

And to clarify the goal of this issue, I think we want example(s) of what source(from) can be used for, and in particular how it impacts the context() call, if at all?

I've used it for handling recursive errors, which I think might be a common case, so maybe that's something I could write.

[tjkirch]

supporting multiple source(from) attributes

(This strikes me as somewhat similar to the request in #123 for "N->1" error mappings, except using multiple concrete types instead of a trait bound. I wonder if those ideas could be unified?)

[shepmaster]

I think it'd be worth having a separate issue for supporting multiple source(from) attributes.

Agreed. I mostly didn't do it originally to avoid YAGNI; was hoping that if someone needed it they would create an issue for it.

And to clarify the goal of this issue, I think we want example(s) of what source(from) can be used for, and in particular how it impacts the context() call, if at all?

That's a specific example, yes. This issue was also broadly about how most of the attributes on that page show the #[snafu(...)] part, but not what happens "at the other end". The Display implementation was more recently touched and does at least attempt to show that.

One thing that I worry about with the user's guide is getting just the right amount of duplication. Too DRY and the documentation becomes a maze of links where you have to read everything to understand anything. Too WET and we run a higher chance of having out-of-date, misleading, or just plain incorrect information, lowering the confidence in the guide.

Concretely, I think that showing "what it can be used for" might be a better as a part of #104.

[shepmaster]

using multiple concrete types instead of a trait bound. I wonder if those ideas could be unified?

Some unification would be cool, but I haven't seen how yet.