more documentation and formatting

README.md

@@ -31,16 +31,21 @@ Read the [Tutorial](https://haraldh.github.io/chainerror/tutorial1.html)
 
 ## Examples
 
+examples/examples.rs:
+```rust
+// […]
+fn main() {
+   if let Err(e) = func1() {
+       eprintln!("\nDebug Error {{:?}}:\n{:?}", e);
+       eprintln!("\nAlternative Debug Error {{:#?}}:\n{:#?}\n", e);
+       // […]
+  }
+}
+```
+
 ```console
 $ cargo run -q --example example
-Main Error Report: func1 error calling func2
+Debug Error {:?}:
-
-Error reported by Func2Error: func2 error: calling func3
-The root cause was: std::io::Error: Kind(
-    NotFound
-)
-
-Debug Error:
 examples/example.rs:46:13: func1 error calling func2
 Caused by:
 examples/example.rs:21:13: Func2Error(func2 error: calling func3)
@@ -49,7 +54,7 @@ examples/example.rs:14:18: Error reading 'foo.txt'
 Caused by:
 Kind(NotFound)
 
-Alternative Debug Error:
+Alternative Debug Error {:#?}:
 ChainError<example::Func1Error> {
     occurrence: Some(
         "examples/example.rs:46:13",
@@ -65,8 +70,8 @@ ChainError<example::Func1Error> {
                 ChainError<alloc::string::String> {
                     occurrence: Some(
                         "examples/example.rs:14:18",
-                    ),
+                   ),
-                    kind: "Error reading \'foo.txt\'",
+                   kind: "Error reading \'foo.txt\'",
                     source: Some(
                         Kind(
                             NotFound,

booksrc/SUMMARY.md

@@ -5,7 +5,7 @@
 - [Simple String Errors](tutorial1.md)
 - [Simple Chained String Errors](tutorial2.md)
 - [Mapping Errors](tutorial3.md)
-- [Saving coding chars](tutorial4.md)
+- [More Information](tutorial4.md)
 - [The source() of Errors](tutorial5.md)
 - [Downcast the Errors](tutorial6.md)
 - [The root cause of all Errors](tutorial7.md)
@@ -17,4 +17,4 @@
 - [Writing a library](tutorial13.md)
 - [Going back to std](tutorial14.md)
 
-[The End](end.md)
+[The End](end.md)

booksrc/tutorial10.md

@@ -5,9 +5,6 @@ To cope with different kind of errors, we introduce the kind of an error `Func1E
 Because we derive `Debug` and implement `Display` our `Func1ErrorKind` enum, this enum can be used as
 a `std::error::Error`.
 
-Not using `String` errors anymore, the `context()` function seen in the beginning of
-the tutorial can be used again.
-
 Only returning `Func1ErrorKind` in `func1()` now let us get rid of `Result<(), Box<Error + Send + Sync>>` and we can
 use `ChainResult<(), Func1ErrorKind>`.
 

booksrc/tutorial11.md

@@ -1,6 +1,6 @@
 # Debug for the ErrorKind
 
-One small improvement at the end of the tutorial is to fix the debug output of
+One small improvement is to fix the debug output of
 `Func1ErrorKind`. As you probably noticed, the output doesn't say much of the enum.
 
 ~~~

examples/example.rs

@@ -51,6 +51,10 @@ fn func1() -> ChainResult<(), Func1Error> {
 
 fn main() {
     if let Err(e) = func1() {
+        eprintln!("\nDebug Error {{:?}}:\n{:?}", e);
+
+        eprintln!("\nAlternative Debug Error {{:#?}}:\n{:#?}\n", e);
+
         match e.kind() {
             Func1Error::Func2 => eprintln!("Main Error Report: func1 error calling func2"),
             Func1Error::IO(filename) => {
@@ -66,9 +70,5 @@ fn main() {
             let ioerror = e.downcast_ref::<io::Error>().unwrap();
             eprintln!("\nThe root cause was: std::io::Error: {:#?}", ioerror);
         }
-
-        eprintln!("\nDebug Error:\n{:?}", e);
-
-        eprintln!("\nAlternative Debug Error:\n{:#?}", e);
     }
 }

examples/tutorial14.rs

@@ -1,7 +1,7 @@
 pub mod mycrate {
     use std::error::Error as StdError;
 
-    use func2mod::{do_some_io, func2};
+    use self::func2mod::{do_some_io, func2};
 
     pub mod func2mod {
         use std::error::Error as StdError;

examples/tutorial15.rs

@@ -1,7 +1,6 @@
 pub mod mycrate {
-    use std::io;
-
     use chainerror::prelude::v1::*;
+    use std::io;
 
     fn do_some_io(_f: &str) -> std::result::Result<(), io::Error> {
         Err(io::Error::from(io::ErrorKind::NotFound))?;

src/lib.rs

@@ -21,16 +21,21 @@
 //!
 //! # Examples
 //!
+//! examples/examples.rs:
+//! ```rust,no_run
+//! // […]
+//! fn main() {
+//!    if let Err(e) = func1() {
+//!        eprintln!("\nDebug Error {{:?}}:\n{:?}", e);
+//!        eprintln!("\nAlternative Debug Error {{:#?}}:\n{:#?}\n", e);
+//!        // […]
+//!   }
+//! }
+//! ```
+//!
 //! ```console
 //! $ cargo run -q --example example
-//! Main Error Report: func1 error calling func2
+//! Debug Error {:?}:
-//!
-//! Error reported by Func2Error: func2 error: calling func3
-//! The root cause was: std::io::Error: Kind(
-//!     NotFound
-//! )
-//!
-//! Debug Error:
 //! examples/example.rs:46:13: func1 error calling func2
 //! Caused by:
 //! examples/example.rs:21:13: Func2Error(func2 error: calling func3)
@@ -39,7 +44,7 @@
 //! Caused by:
 //! Kind(NotFound)
 //!
-//! Alternative Debug Error:
+//! Alternative Debug Error {:#?}:
 //! ChainError<example::Func1Error> {
 //!     occurrence: Some(
 //!         "examples/example.rs:46:13",
@@ -55,8 +60,8 @@
 //!                 ChainError<alloc::string::String> {
 //!                     occurrence: Some(
 //!                         "examples/example.rs:14:18",
-//!                     ),
+//!                    ),
-//!                     kind: "Error reading \'foo.txt\'",
+//!                    kind: "Error reading \'foo.txt\'",
 //!                     source: Some(
 //!                         Kind(
 //!                             NotFound,
@@ -430,7 +435,10 @@ impl<T: 'static + Display + Debug> ChainError<T> {
 /// Convenience methods for `Result<>` to turn the error into a decorated ChainError
 pub trait ResultTrait<O, E: Into<Box<dyn Error + 'static + Send + Sync>>> {
     /// Decorate the error with a `kind` of type `T` and the source `Location`
-    fn context<T: 'static + Display + Debug>(self, kind: T) -> std::result::Result<O, ChainError<T>>;
+    fn context<T: 'static + Display + Debug>(
+        self,
+        kind: T,
+    ) -> std::result::Result<O, ChainError<T>>;
 
     /// Decorate the `error` with a `kind` of type `T` produced with a `FnOnce(&error)` and the source `Location`
     fn map_context<T: 'static + Display + Debug, F: FnOnce(&E) -> T>(
@@ -443,7 +451,10 @@ impl<O, E: Into<Box<dyn Error + 'static + Send + Sync>>> ResultTrait<O, E>
     for std::result::Result<O, E>
 {
     #[track_caller]
-    fn context<T: 'static + Display + Debug>(self, kind: T) -> std::result::Result<O, ChainError<T>> {
+    fn context<T: 'static + Display + Debug>(
+        self,
+        kind: T,
+    ) -> std::result::Result<O, ChainError<T>> {
         match self {
             Ok(t) => Ok(t),
             Err(error_cause) => Err(ChainError::new(
@@ -895,8 +906,7 @@ macro_rules! derive_str_context {
 /// pub fn func1() -> std::result::Result<(), Error> {
 ///     let filename = "bar.txt";
 ///
-///     do_some_io(filename)
+///     do_some_io(filename).map_context(|e| ErrorKind::from_io_error(e, filename.into()))?;
-///         .map_context(|e| ErrorKind::from_io_error(e, filename.into()))?;
 ///     do_some_io(filename).map_context(|e| ErrorKind::IO(filename.into()))?;
 ///     do_some_io(filename).map_context(|e| ErrorKind::from(e))?;
 ///     Ok(())