Unified · Split
| @@ -3,12 +3,40 @@ · 2 unmodified lines | |||
| 3 | //! # Usage | 3 | //! # Usage |
| 4 | //! | 4 | //! |
| 5 | //! * When there is **no callee error** to track, use *simple* `std::error::Error` implementations directly, | 5 | //! * When there is **no callee error** to track, use *simple* `std::error::Error` implementations directly, |
| 6 | //! via `Result<_, Simple>`. | 6 | //! e.g. `Result<_, Simple>`. |
| 7 | //! * When there **is callee error to track** *in a `gix-plumbing`*, use `Result<_, Exn<Simple>>`. | 7 | //! * When there **is callee error to track** *in a `gix-plumbing`*, use e.g. `Result<_, Exn<Simple>>`. |
| 8 | //! - Remember that `Exn<Simple>` does not implement `std::error::Error` so it's not easy to use outside `gix-` crates. | 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). | 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 a `gix`*, convert both `std::error::Error` and `Exn<E>` into [`Error`] | 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 | #![deny(missing_docs, unsafe_code)] | 40 | #![deny(missing_docs, unsafe_code)] |
| 13 | /// A result type to hide the [Exn] error wrapper. | 41 | /// A result type to hide the [Exn] error wrapper. |
| 14 | mod exn; | 42 | mod exn; |