error-kind 0.0.2

Separate `Error` from `ErrorKind` with convenient derive macros!
Documentation
Envelopes an [`ErrorKind`] to collect optional diagnostic information.

- [`Described`] collects an error description.
- [`Diagnostic`] collects all possible diagnostics information.
- [`Located`] collects the location the error occurred.

These types **do not compose**, so you cannot `Described<Located<K>>`.

Using an envelope is optional, `ErrorKind` by itself just ignores all diagnostic information.

[`ErrorKind`]: crate::ErrorKind

## About Envelopes

The [`ErrorEnvelope`] types exist to wrap an [`ErrorKind`], allowing it to collect additional information littered around the codebase during error propagation.

**This allows us to control how detailed our error message will be without changing other parts of the code!**

```rust
use error_kind::{error, Err, Error, ErrorKind};

#[derive(Copy, Clone, Debug, ErrorKind, Eq, Hash, Ord, PartialEq, PartialOrd)]
pub enum MyErrorKind {
    SomeSimpleError,
}

#[derive(Clone, Debug, Error)]
pub struct MyError {
    error: error_kind::envelopes::Diagnostic<MyErrorKind>,
}

#[error("calling some_function with fail={fail}")]
fn some_function(fail: bool) -> Result<(), MyError> {
    if fail {
        return Err!(
            MyErrorKind::SomeSimpleError,
            "asked to fail explicitly",
        );
    }
    Ok(())
}

fn main() {
    let err = some_function(true).unwrap_err();
    println!("error: {err}");
}
```

Since the envelope is [`Diagnostic`], all the additional context is captured and presented!

```text
error: some simple error: asked to fail explicitly
  with context
  ╰─ calling some_function with fail=true
```

The [`Diagnostic`] envelope even collects source lines and backtraces, which can be printed when formatting with the alternate error format (`"{error:#}"`).

**This system takes advantage of the heavy optimizations of the Rust compiler.**

If an envelope type *doesn't* capture some piece of debugging information, it will aggressively inline to suggest to the calling code that the data is not needed.

## Printing Locations and Backtraces

The default display format for any envelopes provided by this crate work in the following way:

- `"{error}"` will print all collected *user-relevant* information.
  - **Will Print:** description, context, and error kind.
  - **Will Omit:** backtraces and source locations.
- `"{error:#}"` will print all collected information.
  - **Will Print:** Everything.
  - **Will Omit:** Nothing.

```rust
# fn some_function(_: bool) -> Result<(), &'static str> { Err("") }
fn main() {
    let err = some_function(true).unwrap_err();

    // Backtrace & locations printed (if captured)!
    println!("error: {err:#}");
}
```

## Accessing Internal Information

**`ErrorEnvelope`s explicitly don't grant access to the information they wrap.**

You should always construct your code in a way in which the information passed into the error envelope is not *necessary*. It's only there to help understand why a failure occurred.

As such, there's no way to inspect any of this "diagnostic" information.