Update feature name

I discussed the logic here andrewhickman#59 (comment).

The prior suggested name "anyhow" was a little too specific/esoteric and in the event that the feature flag outlives the popularity of `anyhow` it wouldn't make sense.

This suggested name tries to focus on the behavior outcome of the feature. It empowers callers to format the "called by" information however they want by:

- Providing a source of that data (Error::source)
- Not formatting emitting that data in `Display`

Author: schneems

.github/workflows/ci.yml

@@ -68,8 +68,8 @@ jobs:
           args: --features tokio
         if: ${{ matrix.rust_version == 'stable' || matrix.rust_version == 'beta' }}
 
-      - name: cargo check --features anyhow
+      - name: cargo check --features custom_caused_by
         uses: actions-rs/cargo@v1
         with:
           command: check
-          args: --features anyhow
+          args: --features custom_caused_by

CHANGELOG.md

@@ -1,6 +1,6 @@
 # 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 `anyhow` ([#60](https://github.com/andrewhickman/fs-err/pull/60)).
+* 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 `custom_caused_by` ([#60](https://github.com/andrewhickman/fs-err/pull/60)).
 
 ## 2.11.0
 

Cargo.toml

@@ -23,9 +23,13 @@ serde_json = "1.0.64"
 [features]
 # Adds I/O safety traits, introduced in Rust 1.63
 io_safety = []
-# Removes the original error text from Display and relies on a wrapper library
-# (such as anyhow) to emit them via `Error::source()`.
-anyhow = []
+
+# Allow custom formatting of the error source
+#
+# When enabled errors emit `std::error::Error::source()` as Some (default is `None`) and
+# no longer include the original `std::io::Error` source in the `Display` implementation.
+# This is useful if errors are wrapped in another library such as Anyhow.
+custom_caused_by = []
 
 [package.metadata.release]
 tag-name = "{{version}}"

src/errors.rs

@@ -101,7 +101,7 @@ impl fmt::Display for Error {
             E::WriteAt => write!(formatter, "failed to write with offset to `{}`", path),
         }?;
 
-        #[cfg(not(feature = "anyhow"))]
+        #[cfg(not(feature = "custom_caused_by"))]
         write!(formatter, "    caused by: {}", self.source)?;
 
         Ok(())
@@ -113,12 +113,12 @@ impl StdError for Error {
         self.source()
     }
 
-    #[cfg(not(feature = "anyhow"))]
+    #[cfg(not(feature = "custom_caused_by"))]
     fn source(&self) -> Option<&(dyn StdError + 'static)> {
         None
     }
 
-    #[cfg(feature = "anyhow")]
+    #[cfg(feature = "custom_caused_by")]
     fn source(&self) -> Option<&(dyn StdError + 'static)> {
         Some(&self.source)
     }
@@ -201,7 +201,7 @@ impl fmt::Display for SourceDestError {
             }
         }?;
 
-        #[cfg(not(feature = "anyhow"))]
+        #[cfg(not(feature = "custom_caused_by"))]
         write!(formatter, "    caused by: {}", self.source)?;
 
         Ok(())
@@ -213,12 +213,12 @@ impl StdError for SourceDestError {
         self.source()
     }
 
-    #[cfg(not(feature = "anyhow"))]
+    #[cfg(not(feature = "custom_caused_by"))]
     fn source(&self) -> Option<&(dyn StdError + 'static)> {
         None
     }
 
-    #[cfg(feature = "anyhow")]
+    #[cfg(feature = "custom_caused_by")]
     fn source(&self) -> Option<&(dyn StdError + 'static)> {
         Some(&self.source)
     }

src/lib.rs

@@ -26,9 +26,8 @@ failed to open file `does not exist.txt`
     caused by: The system cannot find the file specified. (os error 2)
 ```
 
-> Note: To bypass displaying the original error message you can enable the `anyhow` feature.
-> When the `anyhow` feature is enabled `Error::source()` will return `Some` and the original
-> error will not be `Display`-ed via fs-err.
+> Note: Users of `anyhow` or other libraries that format an Error's sources can enable the `custom_caused_by` 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