Unified · Split
| @@ -3,12 +3,40 @@ · 2 unmodified lines | ||
| 3 | 3 | //! # Usage |
| 4 | 4 | //! |
| 5 | 5 | //! * When there is **no callee error** to track, use *simple* `std::error::Error` implementations directly, |
| 6 | −//! via `Result<_, Simple>`. | |
| 7 | −//! * When there **is callee error to track** *in a `gix-plumbing`*, use `Result<_, Exn<Simple>>`. | |
| 8 | −//! - Remember that `Exn<Simple>` does not implement `std::error::Error` so it's not easy to use outside `gix-` crates. | |
| 9 | −//! - Use the type-erased version in callbacks like [`Exn`] (without type arguments). | |
| 10 | −//! * When there **is callee error to track** *in a `gix`*, convert both `std::error::Error` and `Exn<E>` into [`Error`] | |
| 6 | +//! e.g. `Result<_, Simple>`. | |
| 7 | +//! * When there **is callee error to track** *in a `gix-plumbing`*, use e.g. `Result<_, Exn<Simple>>`. | |
| 8 | +//! - Remember that `Exn<T>` does not implement `std::error::Error` so it's not easy to use outside `gix-` crates. | |
| 9 | +//! - Use the type-erased version in callbacks like [`Exn`] (without type arguments), i.e. `Result<T, Exn>`. | |
| 10 | +//! * When there **is callee error to track** *in the `gix` crate*, convert both `std::error::Error` and `Exn<E>` into [`Error`] | |
| 11 | 11 | //! |
| 12 | +//! # Standard Error Types | |
| 13 | +//! | |
| 14 | +//! These should always be used if they match the meaning of the error well enough instead of creating an own | |
| 15 | +//! [`Error`](std::error::Error)-implementing type, and used with `Result|Option::or_raise(<StandardErrorType>)`. | |
| 16 | +//! | |
| 17 | +//! All these types implement [`Error`](std::error::Error). | |
| 18 | +//! | |
| 19 | +//! ## [`Message`] | |
| 20 | +//! | |
| 21 | +//! The baseline that provides a formatted message. | |
| 22 | +//! Formatting can more easily be done with the [`message!`] macro as convenience, roughly equivalent to | |
| 23 | +//! `Message(format!("…"))` or `format!("…").into()`. | |
| 24 | +//! | |
| 25 | +//! ## Specialised types | |
| 26 | +//! | |
| 27 | +//! - [`ParseError`] | |
| 28 | +//! - like [`Message`], but can optionally store the input that caused the failure. | |
| 29 | +//! | |
| 30 | +//! # [`Exn<ErrorType>`](Exn) and [`Exn`] | |
| 31 | +//! | |
| 32 | +//! The [`Exn`] type does not implement [`Error`](std::error::Error) itself, but is able to store causing errors | |
| 33 | +//! via [`ResultExt::or_raise()`] (and friends) as well as location information of the creation site. | |
| 34 | +//! | |
| 35 | +//! While plumbing functions that need to track causes should always return a distinct type like [`Exn<Message>`](Exn), | |
| 36 | +//! if that's not possible, use [`Exn::erased`] to let it return `Result<T, Exn>` instead, allowing any return type. | |
| 37 | +//! | |
| 38 | +//! A side effect of this is that any callee that causes errors needs to be annotated with | |
| 39 | +//! `.or_raise(|| message!("context information"))` or `.or_raise_erased(|| message!("context information"))`. | |
| 12 | 40 | #![deny(missing_docs, unsafe_code)] |
| 13 | 41 | /// A result type to hide the [Exn] error wrapper. |
| 14 | 42 | mod exn; |