fix: re-add the basic doc test (#11)

and more doc improvements

Cargo.toml

@@ -21,3 +21,6 @@ github = { repository = "haraldh/chainerror", workflow = "Rust" }
 maintenance = { status = "actively-developed" }
 is-it-maintained-issue-resolution = { repository = "haraldh/chainerror" }
 is-it-maintained-open-issues = { repository = "haraldh/chainerror" }
+
+[package.metadata.docs.rs]
+cargo-args = ["-Zunstable-options", "-Zrustdoc-scrape-examples"]

README.md

@@ -84,7 +84,7 @@ Os { code: 2, kind: NotFound, message: "No such file or directory" }
 `chainerror` uses `.source()` of `std::error::Error` along with `#[track_caller]` and `Location` to provide a nice debug error backtrace.
 It encapsulates all types, which have `Display + Debug` and can store the error cause internally.
 
-Along with the `ChainError<T>` struct, `chainerror` comes with some useful helper macros to save a lot of typing.
+Along with the `Error<T>` struct, `chainerror` comes with some useful helper macros to save a lot of typing.
 
 `chainerror` has no dependencies!
 
@@ -98,8 +98,8 @@ Read the [Tutorial](https://haraldh.github.io/chainerror/tutorial1.html)
 
 Licensed under either of
 
-* Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or https://www.apache.org/licenses/LICENSE-2.0)
-* MIT license ([LICENSE-MIT](LICENSE-MIT) or https://opensource.org/licenses/MIT)
+* Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or <https://www.apache.org/licenses/LICENSE-2.0>)
+* MIT license ([LICENSE-MIT](LICENSE-MIT) or <https://opensource.org/licenses/MIT>)
 
 at your option.
 

src/lib.rs

@@ -100,9 +100,9 @@ impl<T: 'static + Display + Debug> Error<T> {
             .next()
     }
 
-    /// Find the first error cause of type `ChainError<U>`, if any exists
+    /// Find the first error cause of type [`Error<U>`](Error), if any exists
     ///
-    /// Same as `find_cause`, but hides the `ChainError<U>` implementation internals
+    /// Same as `find_cause`, but hides the [`Error<U>`](Error) implementation internals
     ///
     /// # Examples
     ///
@@ -123,9 +123,9 @@ impl<T: 'static + Display + Debug> Error<T> {
             .next()
     }
 
-    /// Find the first error cause of type `ChainError<U>` or `U`, if any exists and return `U`
+    /// Find the first error cause of type [`Error<U>`](Error) or `U`, if any exists and return `U`
     ///
-    /// Same as `find_cause` and `find_chain_cause`, but hides the `ChainError<U>` implementation internals
+    /// Same as `find_cause` and `find_chain_cause`, but hides the [`Error<U>`](Error) implementation internals
     ///
     /// # Examples
     ///
@@ -154,7 +154,7 @@ impl<T: 'static + Display + Debug> Error<T> {
             .next()
     }
 
-    /// Return a reference to T of `ChainError<T>`
+    /// Return a reference to T of [`Error<T>`](Error)
     ///
     /// # Examples
     ///
@@ -224,7 +224,7 @@ impl<T: 'static + Display + Debug> Error<T> {
     }
 }
 
-/// Convenience methods for `Result<>` to turn the error into a decorated ChainError
+/// Convenience methods for `Result<>` to turn the error into a decorated [`Error`](Error)
 pub trait ResultTrait<O, E: Into<Box<dyn StdError + '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, Error<T>>;
@@ -297,17 +297,17 @@ impl<T: 'static + Display + Debug> std::ops::Deref for Error<T> {
     }
 }
 
-/// Convenience trait to hide the `ChainError<T>` implementation internals
+/// Convenience trait to hide the [`Error<T>`](Error) implementation internals
 pub trait ChainErrorDown {
-    /// Test if of type `ChainError<T>`
+    /// Test if of type `Error<T>`
     fn is_chain<T: 'static + Display + Debug>(&self) -> bool;
-    /// Downcast to a reference of `ChainError<T>`
+    /// Downcast to a reference of `Error<T>`
     fn downcast_chain_ref<T: 'static + Display + Debug>(&self) -> Option<&Error<T>>;
-    /// Downcast to a mutable reference of `ChainError<T>`
+    /// Downcast to a mutable reference of `Error<T>`
     fn downcast_chain_mut<T: 'static + Display + Debug>(&mut self) -> Option<&mut Error<T>>;
-    /// Downcast to T of `ChainError<T>`
+    /// Downcast to T of `Error<T>`
     fn downcast_inner_ref<T: 'static + StdError>(&self) -> Option<&T>;
-    /// Downcast to T mutable reference of `ChainError<T>`
+    /// Downcast to T mutable reference of `Error<T>`
     fn downcast_inner_mut<T: 'static + StdError>(&mut self) -> Option<&mut T>;
 }
 
@@ -505,7 +505,7 @@ impl<T: 'static + Display + Debug> Debug for Error<T> {
     #[inline]
     fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
         if f.alternate() {
-            let mut f = f.debug_struct(&format!("ChainError<{}>", std::any::type_name::<T>()));
+            let mut f = f.debug_struct(&format!("Error<{}>", std::any::type_name::<T>()));
 
             let f = f
                 .field("occurrence", &self.occurrence)
@@ -601,9 +601,9 @@ macro_rules! derive_str_context {
     };
 }
 
-/// Derive an Error for an ErrorKind, which wraps a `ChainError` and implements a `kind()` method
+/// Derive an Error for an ErrorKind, which wraps a [`Error`](Error) and implements a `kind()` method
 ///
-/// It basically hides `ChainError` to the outside and only exposes the `kind()`
+/// It basically hides [`Error`](Error) to the outside and only exposes the [`kind()`](Error::kind)
 /// method.
 ///
 /// Error::kind() returns the ErrorKind
@@ -682,7 +682,7 @@ macro_rules! derive_err_kind {
             }
         }
 
-        impl From<ChainError<$k>> for $e {
+        impl From<$crate::Error<$k>> for $e {
             fn from(e: $crate::Error<$k>) -> Self {
                 $e(e)
             }

tests/test_basic.rs

@@ -0,0 +1,34 @@
+use chainerror::prelude::v1::*;
+
+#[test]
+fn test_basic() {
+    use std::path::PathBuf;
+    type BoxedError = Box<dyn std::error::Error + Send + Sync>;
+    fn read_config_file(path: PathBuf) -> Result<(), BoxedError> {
+        // do stuff, return other errors
+        let _buf = std::fs::read_to_string(&path).context(format!("Reading file: {:?}", &path))?;
+        // do stuff, return other errors
+        Ok(())
+    }
+    fn process_config_file() -> Result<(), BoxedError> {
+        // do stuff, return other errors
+        read_config_file("_non_existent.txt".into()).context("read the config file")?;
+        // do stuff, return other errors
+        Ok(())
+    }
+
+    if let Err(e) = process_config_file() {
+        let os_notfound_error = std::io::Error::from_raw_os_error(2);
+        eprintln!("Error:\n{:?}", e);
+        let s = format!("{:?}", e);
+        let lines = s.lines().collect::<Vec<_>>();
+        assert_eq!(lines.len(), 5);
+        assert!(lines[0].starts_with("tests/test_basic.rs:"));
+        assert_eq!(lines[1], "Caused by:");
+        assert!(lines[2].starts_with("tests/test_basic.rs:"));
+        assert_eq!(lines[3], "Caused by:");
+        assert_eq!(lines[4], format!("{:?}", os_notfound_error));
+    } else {
+        panic!();
+    }
+}