New upstream version 1.49.0~beta.4+dfsg1

[rustc.git] / vendor / anyhow / src / macros.rs

diff --git a/vendor/anyhow/src/macros.rs b/vendor/anyhow/src/macros.rs
index 15a920810cf35ca168bf7a2fa48c96e58878b312..c4b4c80ea1581959547d60d64b34d54a13371142 100644 (file)
--- a/vendor/anyhow/src/macros.rs
+++ b/vendor/anyhow/src/macros.rs
@@ -1,6 +1,9 @@
 /// Return early with an error.
 ///
-/// This macro is equivalent to `return Err(From::from($err))`.
+/// This macro is equivalent to `return Err(`[`anyhow!($args...)`][anyhow!]`)`.
+///
+/// The surrounding function's or closure's return value is required to be
+/// `Result<_,`[`anyhow::Error`][crate::Error]`>`.
 ///
 /// # Example
 ///
@@ -50,19 +53,23 @@
 #[macro_export]
 macro_rules! bail {
     ($msg:literal $(,)?) => {
-        return $crate::private::Err($crate::anyhow!($msg));
+        return $crate::private::Err($crate::anyhow!($msg))
     };
     ($err:expr $(,)?) => {
-        return $crate::private::Err($crate::anyhow!($err));
+        return $crate::private::Err($crate::anyhow!($err))
     };
     ($fmt:expr, $($arg:tt)*) => {
-        return $crate::private::Err($crate::anyhow!($fmt, $($arg)*));
+        return $crate::private::Err($crate::anyhow!($fmt, $($arg)*))
     };
 }
 
 /// Return early with an error if a condition is not satisfied.
 ///
-/// This macro is equivalent to `if !$cond { return Err(From::from($err)); }`.
+/// This macro is equivalent to `if !$cond { return
+/// Err(`[`anyhow!($args...)`][anyhow!]`); }`.
+///
+/// The surrounding function's or closure's return value is required to be
+/// `Result<_,`[`anyhow::Error`][crate::Error]`>`.
 ///
 /// Analogously to `assert!`, `ensure!` takes a condition and exits the function
 /// if the condition fails. Unlike `assert!`, `ensure!` returns an `Error`
@@ -123,11 +130,17 @@ macro_rules! ensure {
     };
 }
 
-/// Construct an ad-hoc error from a string.
+/// Construct an ad-hoc error from a string or existing non-`anyhow` error
+/// value.
+///
+/// This evaluates to an [`Error`][crate::Error]. It can take either just a
+/// string, or a format string with arguments. It also can take any custom type
+/// which implements `Debug` and `Display`.
 ///
-/// This evaluates to an `Error`. It can take either just a string, or a format
-/// string with arguments. It also can take any custom type which implements
-/// `Debug` and `Display`.
+/// If called with a single argument whose type implements `std::error::Error`
+/// (in addition to `Debug` and `Display`, which are always required), then that
+/// Error impl's `source` is preserved as the `source` of the resulting
+/// `anyhow::Error`.
 ///
 /// # Example
 ///