An example full project using snafu?

[dpc]

I am having a hard time going through the guide.

What I'd actually like to see in the guide is a link to a github repo with a real-like example of a tiny project that uses snafu in some "best practices" manner.

E.g. I wrote a simple project:

use snafu::{ensure, whatever, ResultExt, Snafu, Whatever};

#[derive(Debug, Snafu)]
struct NeighborhoodError {
    #[snafu(implicit)]
    loc: snafu::Location,
}

#[derive(Debug, Snafu)]
enum AppError {
    Whatever {
        #[snafu(implicit)]
        loc: snafu::Location,
        source: Whatever,
    },
}

fn everything_quiet() -> Result<(), Whatever> {
    whatever!("boo")
}

fn check_next_door() -> Result<(), AppError> {
    everything_quiet().context(WhateverSnafu)?;
    Ok(())
}

fn main() -> Result<(), AppError> {
    check_next_door()?;

    Ok(())
}

and when I run it it prints:

Error: Whatever { loc: Location { file: "src/main.rs", line: 23, column: 24 }, source: Whatever { source: None, message: "boo", backtrace: Backtrace [{ fn: "snafu::backtrace_impl::<impl snafu::GenerateImplicitData for std::backtrace::Backtrace>::generate", file: "/home/dpc/.cargo/registry/src/index.crates.io-6f17d22bba15001f/snafu-0.8.5/src/backtrace_impl_std.rs", line: 5 }, { fn: "<snafu::Whatever as snafu::FromString>::without_source", file: "/home/dpc/.cargo/registry/src/index.crates.io-6f17d22bba15001f/snafu-0.8.5/src/lib.rs", line: 1574 }, { fn: "snafu_test::everything_quiet", file: "./src/main.rs", line: 19 }, { fn: "snafu_test::check_next_door", file: "./src/main.rs", line: 23 }, { fn: "snafu_test::main", file: "./src/main.rs", line: 28 }, { fn: "core::ops::function::FnOnce::call_once", file: "/build/rustc-1.82.0-src/library/core/src/ops/function.rs", line: 250 }, { fn: "std::sys::backtrace::__rust_begin_short_backtrace", file: "/build/rustc-1.82.0-src/library/std/src/sys/backtrace.rs", line: 154 }, { fn: "std::rt::lang_start::{{closure}}", file: "/build/rustc-1.82.0-src/library/std/src/rt.rs", line: 164 }, { fn: "std::rt::lang_start_internal" }, { fn: "std::rt::lang_start", file: "/build/rustc-1.82.0-src/library/std/src/rt.rs", line: 163 }, { fn: "main" }, { fn: "__libc_start_call_main" }, { fn: "__libc_start_main_alias_2" }, { fn: "_start" }] } }

instead of ... something nicer. And now what? Do I need to register something? Bring another crate?

The examples in the user guide are just isolated modules, and generally reading [source] is meh UX.

Edit: I needed #[snafu::report] on main.

But again - the current model of a rustdoc based "user guide" ... is not my favourite and actually locally cloning some real code playing with it, running etc. would work much better for me.

[Enet4]

Regarding error reporting, the next version will feature an extension to the root crate documentation on the subject (#466). You can see the preview here.

The documentation already contains some interesting examples (such as trying to open a file). Ultimately, this becomes a matter of striking a balance between use case coverage and readability without excessive verbosity.

[dpc]

@Enet4 Thanks. This looks like a good addition. Though I still think an ./examples/ folder with one/few short projects would be a relatively easy to maintain alternative educational material that people can just open in their text editor, jump around with LSP and hack to learn. At least for me that's a much more approachable (compared to reading docs.rs) way to digest an entirety of new approach of error handling.

[shepmaster]

One of my super-long-term stretch goals is to really dig into something like Diátaxis and see how SNAFU could leverage it. One pain that I've felt is how one person wants the documentation to be one way and then another wants it a completely different way. The only solution I know of is to create multiple types of documentation which then incurs overhead and maintenance problems.

in some "best practices" manner

I can tell you what I do, which doesn't mean it's best for you. Specifically, I attempt to never use whatevers or locations / backtraces. Instead, I create a lot of error types (recently experimenting with one error type per function) and never construct the same error in more than one location.

As for reporting the error, that depends a lot on what kind of program you are writing. A CLI tool can use Report as mentioned above, but a server application will usually need to put the error into something like a JSON blob. I'm not sure what would be nice for a TUI or GUI.

[dpc]

The only solution I know of is to create multiple types of documentation which then incurs overhead and maintenance problems.

I know, I've been there. It's even worse then that - some people would love YT videos, some book, some code examples, etc.

That's why I mentioned that short examples/ is probably "easy to maintain". I am not trying to sell writting an extra mdbook etc. I actually really like leveraging rustdocs for documentation as much a I can, to avoid maintaining extra stuffs. But in this case I think it's worth it (my subjective opinion though).

I can tell you what I do, which doesn't mean it's best for you. Specifically, I attempt to never use whatevers or locations / backtraces. Instead, I create a lot of error types (recently experimenting with one error type per function) and never construct the same error in more than one location.

I think showing anything would be useful. Ideally there could be 2 or 3 examples showing most popular approaches. But again - a single example would at very least be and end-to-end example that one could clone, edit, run and play with, while docs.rs is not like that.

As for reporting the error, that depends a lot on what kind of program you are writing.

#[snafu::report] completely satisifies me. I just initially didn't find it among rest of the docs.rs docs. Another problem with docs: the more you write, the harder is for the user to find what they are looking for in particular. 🤷