GEN-108(issue): Show some minimal but working example on the main documentation page

[dpc]

Related Problem

I'm a returning user, trying error-stack again, and I go to https://docs.rs/error-stack and I see Quick-Start Guide which doesn't actually show me any full, usable code. Instead it jumps straight to discussing some aspects of error-stack.

What I'd like is a bit of copy-pasta that reminds me what goes where, and how to get started. I was able to find some example, which will do, but it's just inconvenient.

Proposed Solution

Take this example, get rid of all the unstable stuff, slap it right under Quick-Start Guide header.

Alternatives

No response

Additional context

No response

[TimDiekmann]

Hi @dpc and thank you for your suggestion. It's a very good concern. Are you happy to provide a PR?

[dpc]

@TimDiekmann I could, but I'm not even sure exactly how it should look like. As a frequent returning user, I don't even know how do developers of error-stack would like people to use it in a new, starting small from scratch.

Should it be:

#[derive(Error, Debug)]
#[error("application error")]
struct AppError;

type AppResult<T> = error_stack::Result<T, AppError>;

or

#[derive(Error, Debug)]
#[error("application error")]
enum AppError {
  Something
  Somethingelse
}

type AppResult<T> = error_stack::Result<T, AppError>;

or should they start without thiserror first?

With error-stack I can tell that developers built it for themselves, being already experienced with error handling, and wanting to level up their error handling game with their somewhat opinionated vision. So the documentation focuses on listing all the details of the solution aimed at other experienced error handling users.

But then, if I want to tell someone "hey, try handling errors with error-stack", there's little help for them. Even as a returning user, I still don't feel like I know exactly what I should do, like I do when I use anyhow (slap anyhow::Result everywhere, thiserror (make enum with messages everywhere), clap, or any other popular crates.

[TimDiekmann]

The "issue" with error-stack is that there is no "put error_stack::Report everywhere and you're good" (Even if you have well-defined errors you still need to change contexts at least) and that's actually on purpose.

I noticed myself using structs more often than enums for Context, but mainly because I didn't find the time to properly create enum variants for the different error variants which could happen. A thing, where thiserror helps a lot. In most cases, it's probably easier to use an enum for the Context as you have proposed. For attachments in most cases you either just add something easily printables (such as a string) or structs containing more information about this error which helps the user (end user or consuming library) to handle this error (e.g. a suggestion, a warning, or a hint).

As a rule of thumb, and probably something which is good as an intro, you could say that

• If you have multiple error variants you should use enums as the Context (as in your second example)
• If you only have a single error variant, you should use a struct (as in your first example)
• If you just have an inner error and the API does not need to abstract that error away just use that error (e.g. Report<std::io::Error>

For the example I'd go with an enumeration.

Maybe it's worth pointing out explicitly in the docs that in comparison to thiserror, error-stack does not require you to put the inner error inside of the enum variant, that is what Report does for you. You only have to provide the additional context (e.g. variants for "Could not open the config file" or "Could not connect to GitHub").

I would not use thiserror in the quickstart guide. It's an amazing crate that mainly helps you to implement Display. source is probably not as interesting in a crate using error-stack as in a crate without error-stack. But we, however, should give the reader a hint, that the Display and Error implementation could easily provided by thiserror - maybe as a comment next to the Display implementation?

[dpc]

The "issue" with error-stack is that there is no "put error_stack::Report everywhere and you're good" (Even if you have well-defined errors you still need to change contexts at least) and that's actually on purpose.

It should have something to put a new user on some rails and propel them forward.

For the example I'd go with an enumeration.

OK

I would not use thiserror in the quickstart guide. It's an amazing crate that mainly helps you to implement Display. source is probably not as interesting in a crate using error-stack as in a crate without error-stack.

I would use it, and mention in one comment that it is not necessary. It just makes everything shorter and easier. Personally I use 100% of time if I go with a enum.

[TimDiekmann]

It should have something to put a new user on some rails and propel them forward.

The general migration strategy to error-stack I guess (assuming neither eyre, nor anyhow are used) is to start at the most outer result - e.g. the return value of main. If the Err variant of that Result is wrapped inside of Report it's mainly following compiler hints. Then it should be easily possible to further add Report to other functions. The other way around will probably lead to issues. Maybe we can mention that somehow?

I would use it, and mention in one comment that it is not necessary. It just makes everything shorter and easier.

I think it's fair to do that but at least in the very first example, Display and Context should be implemented manually. Then it's possible to just copy/paste the code and only add error-stack as dependency (even in no_std). Any further example may use thiserror.

[dpc]

Display and Context should be implemented manually

They're confusing and unnecessary to actually start using error-stack.

The general migration strategy to error-stack ...

Users migrating existing projects are not a target of this issue. :D

Don't get blinded by all your experience actually using error-stack in an existing project. This one example is supposed to be the simplest, most convenient starting point for a new user starting a new (possibly toy) project, not a show-case of low levels details and explanations, like pretty much all the existing documentation is.