Repository: rust-lang-deprecated/failure (language: rust)

Issue:
`Error::cause` should probably be `Error::as_fail`
Treating the error "lifted" into `Error` as a *cause* is misleading; it simply *is* the root error. I think we should rename the `Error::cause` method to something like `Error::as_fail`, which we would plan to deprecate someday when `Error` can implement `Fail`.


Discussion / hints:

Fix patch:
diff --git a/failure-1.X/src/context.rs b/failure-1.X/src/context.rs
index 68f3785..69903af 100644
--- a/failure-1.X/src/context.rs
+++ b/failure-1.X/src/context.rs
@@ -82,7 +82,7 @@ with_std! {
 
     impl<D: Display + Send + Sync + 'static> Fail for Context<D> {
         fn cause(&self) -> Option<&Fail> {
-            self.failure.cause()
+            self.failure.as_cause()
         }
 
         fn backtrace(&self) -> Option<&Backtrace> {
@@ -115,10 +115,10 @@ with_std! {
             }
         }
 
-        fn cause(&self) -> Option<&Fail> {
+        fn as_cause(&self) -> Option<&Fail> {
             match *self {
                 Either::This(_)         => None,
-                Either::That(ref error) => Some(error.cause())
+                Either::That(ref error) => Some(error.as_fail())
             }
         }
     }
diff --git a/failure-1.X/src/error/error_impl_small.rs b/failure-1.X/src/error/error_impl_small.rs
index 8df2919..6ff7c78 100644
--- a/failure-1.X/src/error/error_impl_small.rs
+++ b/failure-1.X/src/error/error_impl_small.rs
@@ -25,11 +25,13 @@ extern {
     type FailData;
 }
 
+#[allow(dead_code)]
 struct InnerRaw<F> {
     header: InnerHeader,
     failure: F,
 }
 
+#[allow(dead_code)]
 struct InnerHeader {
     backtrace: Backtrace,
     vtable: *const VTable,
diff --git a/failure-1.X/src/error/mod.rs b/failure-1.X/src/error/mod.rs
index eb5f21f..7a705e2 100644
--- a/failure-1.X/src/error/mod.rs
+++ b/failure-1.X/src/error/mod.rs
@@ -33,11 +33,21 @@ impl<F: Fail> From<F> for Error {
 }
 
 impl Error {
+    /// Return a reference to the underlying failure that this `Error`
+    /// contains.
+    pub fn as_fail(&self) -> &Fail {
+        self.imp.failure()
+    }
+
     /// Returns a reference to the underlying cause of this `Error`. Unlike the
     /// method on `Fail`, this does not return an `Option`. The `Error` type
     /// always has an underlying failure.
+    ///
+    /// This method has been deprecated in favor of the [Error::as_fail] method,
+    /// which does the same thing.
+    #[deprecated(since = "1.0.0", note = "please use 'as_fail()' method instead")]
     pub fn cause(&self) -> &Fail {
-        self.imp.failure()
+        self.as_fail()
     }
 
     /// Gets a reference to the `Backtrace` for this `Error`.
@@ -87,7 +97,7 @@ impl Error {
     /// Returns the "root cause" of this error - the last value in the
     /// cause chain which does not return an underlying `cause`.
     pub fn root_cause(&self) -> &Fail {
-        ::find_root_cause(self.cause())
+        ::find_root_cause(self.as_fail())
     }
 
     /// Attempts to downcast this `Error` to a particular `Fail` type by
@@ -110,7 +120,7 @@ impl Error {
     /// the failure returned by the `cause` method and ending with the failure
     /// returned by `root_cause`.
     pub fn causes(&self) -> Causes {
-        Causes { fail: Some(self.cause()) }
+        Causes { fail: Some(self.as_fail()) }
     }
 }
 
@@ -131,6 +141,12 @@ impl Debug for Error {
     }
 }
 
+impl AsRef<Fail> for Error {
+    fn as_ref(&self) -> &Fail {
+        self.as_fail()
+    }
+}
+
 #[cfg(test)]
 mod test {
     use std::io;
diff --git a/failure-1.X/src/lib.rs b/failure-1.X/src/lib.rs
index f53a57a..b4a241a 100644
--- a/failure-1.X/src/lib.rs
+++ b/failure-1.X/src/lib.rs
@@ -14,6 +14,7 @@
 //! their situation.
 #![cfg_attr(not(feature = "std"), no_std)]
 #![deny(missing_docs)]
+#![deny(warnings)]
 #![cfg_attr(feature = "small-error", feature(extern_types, allocator_api))]
 
 macro_rules! with_std { ($($i:item)*) => ($(#[cfg(feature = "std")]$i)*) }


Test patch: