Add docs about error handling (#1745)

* docs: Add ERROR_HANDLING

that explains how we plan to change error handling in zellij and invites
new contributors to join the fun. Details the currently existent error
handling capabilities and gives a bunch of examples taken from #1670.

* utils/errors: Shorten docblock

by moving previous content under "Help Wanted" to the new
`docs/ERROR_HANDLING` document and link to the document instead.

1 files changed, 5 insertions, 79 deletions

diff --git a/zellij-utils/src/errors.rs b/zellij-utils/src/errors.rs
index a46427ed6..dac249fc0 100644
--- a/zellij-utils/src/errors.rs
+++ b/zellij-utils/src/errors.rs
@@ -3,85 +3,11 @@
 //!
 //! # Help wanted
 //!
-//! As of writing this, zellij relies on `unwrap()` to catch errors (terminate execution) in many
-//! functions, rather than returning a [`Result`] to propagate these errors further up. While we
-//! don't consider `unwrap` to be a bad thing in general, it hides the underlying error and leaves
-//! the user only with a stack trace to go on. Worse than this, it will crash the application. This
-//! is particularly bad when the user is using long-running sessions to perform tasks.
-//!
-//! Hence, we would like to eliminate `unwrap()` statements from the code where possible, and apply
-//! better error handling instead. This way, functions higher up in the call stack can react to
-//! errors from underlying functions and either try to recover, or give some meaningful error
-//! messages if recovery isn't possible.
-//!
-//! Since the zellij codebase is pretty big and growing rapidly, this endeavour will continue to be
-//! pursued over time, as zellij develops. The idea is that modules or single files are converted
-//! bit by bit, preferrably in small PRs that each target a specific module or file. **If you are
-//! looking to contribute to zellij, this may be an ideal start for you!** This way you get to know
-//! the codebase and get an idea which modules are used at which other places in the code.
-//!
-//! If you have an interest in this, don't hesitate to get in touch with us.
-//!
-//!
-//! # Error handling facilities
-//!
-//! ## Displaying panic messages
-//!
-//! Panics are generally handled via the [`Panic`] error type and the
-//! [`handle_panic`][`handle_panic`] panic handler function. The fancy formatting is performed by
-//! the [`miette`] crate.
-//!
-//!
-//! ## Propagating errors
-//!
-//! We use the [`anyhow`] crate to propagate errors up the call stack. At the moment, zellij
-//! doesn't have custom error types, so we wrap whatever errors the underlying libraries give us,
-//! if any. [`anyhow`] serves the purpose of providing [`context`][`context`] about where (i.e.
-//! under which circumstances) an error happened.
-//!
-//! A critical requirement for propagating errors is that all functions involved must return the
-//! [`Result`] type. This allows convenient error handling with the `?` operator.
-//!
-//! At some point you will likely stop propagating errors and decide what to do with the error.
-//! Generally you can:
-//!
-//! 1. Try to recover from the error, or
-//! 2. Report the error to the user and either
-//!     1. Terminate program execution (See [`fatal`][`fatal`]), or
-//!     2. Continue program execution (See [`non_fatal`][`non_fatal`])
-//!
-//!
-//! ## Handling errors
-//!
-//! Ideally, when the program encounters an error it will try to recover as best as it can. This
-//! can mean falling back to some sane default if a specific value (e.g. an environment variable)
-//! cannot be found. Note that this isn't always applicable. If in doubt, don't hesitate to ask.
-//!
-//! Recovery usually isn't an option if an operation has changed the internal state (i.e. the value
-//! or content of specific variables) of objects in the code. In this case, if an error is
-//! encountered, it is best to declare the program state corrupted and terminate the whole
-//! application. This can be done by [`unwrap`]ing on the [`Result`] type. Always try to propagate
-//! the error as best as you can and attach meaningful context before [`unwrap`]ing. This gives the
-//! user an idea what went wrong and can also help developers in quickly identifying which parts of
-//! the code to debug if necessary.
-//!
-//! When you encounter such a fatal error and cannot propagate it further up (e.g. because the
-//! current function cannot be changed to return a [`Result`], or because it is the "root" function
-//! of a program thread), use the [`fatal`][`fatal`] function to panic the application. It will
-//! attach some small context to the error and finally [`unwrap`] it. Using this function over the
-//! regular [`unwrap`] has the added benefit that other developers seeing this in the code know
-//! that someone has previously spent some thought about error handling at this location.
-//!
-//! If you encounter a non-fatal error, use the [`non_fatal`][`non_fatal`] function to handle
-//! it. Instead of [`panic`]ing the application, the error is written to the application log and
-//! execution continues. Please use this sparingly, as an error usually calls for actions to be
-//! taken rather than ignoring it.
-//!
-//!
-//! [`handle_panic`]: not_wasm::handle_panic
-//! [`context`]: anyhow::Context
-//! [`fatal`]: FatalError::fatal
-//! [`non_fatal`]: FatalError::non_fatal
+//! There is an ongoing endeavor to improve the state of error handling in zellij. Currently, many
+//! functions rely on [`unwrap`]ing [`Result`]s rather than returning and hence propagating
+//! potential errors. If you're interested in helping to add error handling to zellij, don't
+//! hesitate to get in touch with us. Additional information can be found in [the docs about error
+//! handling](https://github.com/zellij-org/zellij/tree/main/docs/ERROR_HANDLING.md).
 
 use anyhow::Context;
 use colored::*;