probe-rs
probe-rs copied to clipboard
Improve erroring
Many errors are quite hard to guess for folks on what's actually going wrong. People come in to the Matrix chat and it's easy for us to tell what's wrong or what might be wrong.
We should add a means to add hints to an error on what might be wrong.
@therealprof started on utilizing thiserror
properly, together with anyhow
. This is a great start, but we need to start adding those additional hints to the error messages.
Could be a great issue for starters at oxidize impl Days.
I guess we should also setup a few guidelines to help people who want to help.
The basic idea of the error handling is those errors will stack and bubble up. I.e:
- someone starts witch a high-level task ("flash this binary")
- probe-rs detects the available probes and initialises them
- probe-rs breaks down the task into DAP commands and sends those down in the right format to the probe specific implementation
- the probe-specific implementations tries to execute those DAP commands against the target
At any of these levels errors may occur which are of two kinds:
- Errors which need error specific handling by any higher level code
- Errors which need to be reported back to the user with an appropriate level of detail
For 1) we use thiserror
to have specific error types. The job here is to identify which errors can actually be handled by higher level code and remove those which are irrelevant and replace them by generic anyhow
errors. The remaining errors should be as detailed as possible and include error specific details. A rule of thumb is: If there's no caller matching on an error variant, there's a good chance that the error variant can go and should be replaced by an anyhow::Error
.
For 2) we use anyhow
. anyhow
allows us to have user friendly error messages which can have context attached. To properly use anyhow
, any relevant custom error enum (remaining after the error pruning) should have a
#[error(transparent)]
Other(#[from] anyhow::Error),
value to allow pass through of anyhow
errors from lower layers. anyhow
also allows to add a context, so instead of merely matching and passing on an error, a caller handling an error with the question mark operator should also consider adding a anyhow::Context
to let the user know what the caller was trying to do while the error occured.