Document Error Handling Strategy

[elfenpiff]

Brief feature description

The error handling strategy must be documented.

• That we use enums as error codes
• A strategy how internal error codes from a lower architectural level are translated into enum error codes of an higher architectural level
• How std::error::Error and later (when it is in stable) core::error::Error is implemented for all error enums.

The issue shall be concluded with a markdown file explaining the above points and showing some code snippets to illustrate them.

Detailed information

From @elBoberido

I found another solution in the zstd crate. They use derive_more with a feature flag to derive Error only on std. This makes would allow no_std on stable but without the Error trait. Something to think of.

They basically did this

[dependencies]
derive_more = { version = "0.99", default-features = false, features = ["display", "from"] }

[features]
default = ["std"]
std = ["derive_more/error"]

#[derive(Debug, derive_more::Display, derive_more::From)]
#[cfg_attr(feature = "std", derive(derive_more::Error))]
#[non_exhaustive]
pub enum Foo {
    #[display(fmt = "Bar occurred. Is: {baz}, must be either 1 or 2")]
    Bar { baz: u8 },
    //...
}

The attributes on the enum tags are quite similar to thiserror so it wouldn't be too hard to switch between the two crates.