Update changelog and docs for #60

Author: andrewhickman

CHANGELOG.md

@@ -1,6 +1,20 @@
 # fs-err Changelog
 
-* Change errors to output original `std::io::Error` information Display by default. This functionality can be disabled for [anyhow](https://docs.rs/anyhow/latest/anyhow/) users by using the new feature `expose_original_error` ([#60](https://github.com/andrewhickman/fs-err/pull/60)).
+## 3.0.0
+
+* Error messages now include the original message from `std::io::Error` by default ([#60](https://github.com/andrewhickman/fs-err/pull/60)). Previously this was exposed through the [`Error::source()`](https://doc.rust-lang.org/stable/std/error/trait.Error.html#method.source) method. For example, previously a message would look like:
+
+  ```
+  failed to open file `file.txt`
+  ```
+
+  and you would have to remember to print the source, or use a library like `anyhow` to print the full chain of source errors. The new error message includes the cause by default
+
+  ```
+  failed to open file `file.txt`: The system cannot find the file specified. (os error 2)
+  ```
+
+  Note that the original error is no longer exposed though [`Error::source()`](https://doc.rust-lang.org/stable/std/error/trait.Error.html#method.source) by default. If you need access to it, you can restore the previous behaviour with the `expose_original_error` feature flag.
 
 ## 2.11.0
 

README.md

@@ -30,8 +30,7 @@ The system cannot find the file specified. (os error 2)
 ...but if we use fs-err instead, our error contains more actionable information:
 
 ```txt
-failed to open file `does not exist.txt`
-    caused by: The system cannot find the file specified. (os error 2)
+failed to open file `does not exist.txt`: The system cannot find the file specified. (os error 2)
 ```
 
 ## Usage
@@ -66,10 +65,11 @@ println!("Program config: {:?}", decoded);
 
 ```
 
-[std::fs]: https://doc.rust-lang.org/stable/std/fs/
-[std::io::Error]: https://doc.rust-lang.org/stable/std/io/struct.Error.html
-[std::io::Read]: https://doc.rust-lang.org/stable/std/io/trait.Read.html
-[serde_json]: https://crates.io/crates/serde_json
+## Feature flags
+
+* `expose_original_error`: when enabled, the [`Error::source()`](https://doc.rust-lang.org/stable/std/error/trait.Error.html#method.source) method of errors returned by this crate return the original `io::Error`. To avoid duplication in error messages,
+  this also suppresses printing its message in their `Display` implementation, so make sure that you are printing the full error chain.
+
 
 ## Minimum Supported Rust Version
 
@@ -79,6 +79,11 @@ This crate will generally be conservative with rust version updates. It uses the
 
 If the `tokio` feature is enabled, this crate will inherit the MSRV of the selected [`tokio`](https://crates.io/crates/tokio) version.
 
+[std::fs]: https://doc.rust-lang.org/stable/std/fs/
+[std::io::Error]: https://doc.rust-lang.org/stable/std/io/struct.Error.html
+[std::io::Read]: https://doc.rust-lang.org/stable/std/io/trait.Read.html
+[serde_json]: https://crates.io/crates/serde_json
+
 ## License
 
 Licensed under either of

src/errors.rs

@@ -103,7 +103,7 @@ impl fmt::Display for Error {
 
         // The `expose_original_error` feature indicates the caller should display the original error
         #[cfg(not(feature = "expose_original_error"))]
-        write!(formatter, "    caused by: {}", self.source)?;
+        write!(formatter, ": {}", self.source)?;
 
         Ok(())
     }
@@ -204,7 +204,7 @@ impl fmt::Display for SourceDestError {
 
         // The `expose_original_error` feature indicates the caller should display the original error
         #[cfg(not(feature = "expose_original_error"))]
-        write!(formatter, "    caused by: {}", self.source)?;
+        write!(formatter, ": {}", self.source)?;
 
         Ok(())
     }

src/lib.rs

@@ -22,13 +22,9 @@ The system cannot find the file specified. (os error 2)
 ...but if we use fs-err instead, our error contains more actionable information:
 
 ```txt
-failed to open file `does not exist.txt`
-    caused by: The system cannot find the file specified. (os error 2)
+failed to open file `does not exist.txt`: The system cannot find the file specified. (os error 2)
 ```
 
-> Note: Users of `anyhow` or other libraries that format an Error's sources can enable the `expose_original_error` feature to control the formatting of the orginal error message.
-> When enabled, the `std::fmt::Display` implementation will emit the failed operation and paths but not the original `std::io::Error`. It will instead provide access via [Error::source](https://doc.rust-lang.org/std/error/trait.Error.html#method.source), which will be used by `anyhow` (or similar) libraries.
-
 # Usage
 
 fs-err's API is the same as [`std::fs`][std::fs], so migrating code to use it is easy.
@@ -63,6 +59,20 @@ println!("Program config: {:?}", decoded);
 # Ok::<(), Box<dyn std::error::Error>>(())
 ```
 
+# Feature flags
+
+* `expose_original_error`: when enabled, the [`Error::source()`](https://doc.rust-lang.org/stable/std/error/trait.Error.html#method.source) method of errors returned by this crate return the original `io::Error`. To avoid duplication in error messages,
+  this also suppresses printing its message in their `Display` implementation, so make sure that you are printing the full error chain.
+
+
+# Minimum Supported Rust Version
+
+The oldest rust version this crate is tested on is **1.40**.
+
+This crate will generally be conservative with rust version updates. It uses the [`autocfg`](https://crates.io/crates/autocfg) crate to allow wrapping new APIs without incrementing the MSRV.
+
+If the `tokio` feature is enabled, this crate will inherit the MSRV of the selected [`tokio`](https://crates.io/crates/tokio) version.
+
 [std::fs]: https://doc.rust-lang.org/stable/std/fs/
 [std::io::Error]: https://doc.rust-lang.org/stable/std/io/struct.Error.html
 [std::io::Read]: https://doc.rust-lang.org/stable/std/io/trait.Read.html