Rollup merge of rust-lang#33831 - diwic:patch-1, r=aturon

panic.rs: fix docs (recover -> catch_unwind)

The current docs are a bit inconsistent. First, change all references of "recover" to "catch_unwind" because the function was renamed. Second, consistently use the term "unwind safe" instead of "panic safe", "exception safe" and "recover safe" (all these terms were used previously).

Author: Manishearth

src/libstd/panic.rs

@@ -39,14 +39,14 @@ pub fn take_handler() -> Box<Fn(&PanicInfo) + 'static + Sync + Send> {
     take_hook()
 }
 
-/// A marker trait which represents "panic safe" types in Rust.
+/// A marker trait which represents "unwind safe" types in Rust.
 ///
 /// This trait is implemented by default for many types and behaves similarly in
 /// terms of inference of implementation to the `Send` and `Sync` traits. The
-/// purpose of this trait is to encode what types are safe to cross a `recover`
-/// boundary with no fear of panic safety.
+/// purpose of this trait is to encode what types are safe to cross a `catch_unwind`
+/// boundary with no fear of unwind safety.
 ///
-/// ## What is panic safety?
+/// ## What is unwind safety?
 ///
 /// In Rust a function can "return" early if it either panics or calls a
 /// function which transitively panics. This sort of control flow is not always
@@ -59,62 +59,62 @@ pub fn take_handler() -> Box<Fn(&PanicInfo) + 'static + Sync + Send> {
 ///
 /// Typically in Rust, it is difficult to perform step (2) because catching a
 /// panic involves either spawning a thread (which in turns makes it difficult
-/// to later witness broken invariants) or using the `recover` function in this
+/// to later witness broken invariants) or using the `catch_unwind` function in this
 /// module. Additionally, even if an invariant is witnessed, it typically isn't a
-/// problem in Rust because there's no uninitialized values (like in C or C++).
+/// problem in Rust because there are no uninitialized values (like in C or C++).
 ///
 /// It is possible, however, for **logical** invariants to be broken in Rust,
-/// which can end up causing behavioral bugs. Another key aspect of panic safety
+/// which can end up causing behavioral bugs. Another key aspect of unwind safety
 /// in Rust is that, in the absence of `unsafe` code, a panic cannot lead to
 /// memory unsafety.
 ///
-/// That was a bit of a whirlwind tour of panic safety, but for more information
-/// about panic safety and how it applies to Rust, see an [associated RFC][rfc].
+/// That was a bit of a whirlwind tour of unwind safety, but for more information
+/// about unwind safety and how it applies to Rust, see an [associated RFC][rfc].
 ///
 /// [rfc]: https://github.com/rust-lang/rfcs/blob/master/text/1236-stabilize-catch-panic.md
 ///
 /// ## What is `UnwindSafe`?
 ///
-/// Now that we've got an idea of what panic safety is in Rust, it's also
+/// Now that we've got an idea of what unwind safety is in Rust, it's also
 /// important to understand what this trait represents. As mentioned above, one
-/// way to witness broken invariants is through the `recover` function in this
+/// way to witness broken invariants is through the `catch_unwind` function in this
 /// module as it allows catching a panic and then re-using the environment of
 /// the closure.
 ///
 /// Simply put, a type `T` implements `UnwindSafe` if it cannot easily allow
-/// witnessing a broken invariant through the use of `recover` (catching a
+/// witnessing a broken invariant through the use of `catch_unwind` (catching a
 /// panic). This trait is a marker trait, so it is automatically implemented for
-/// many types, and it is also structurally composed (e.g. a struct is recover
-/// safe if all of its components are recover safe).
+/// many types, and it is also structurally composed (e.g. a struct is unwind
+/// safe if all of its components are unwind safe).
 ///
 /// Note, however, that this is not an unsafe trait, so there is not a succinct
 /// contract that this trait is providing. Instead it is intended as more of a
-/// "speed bump" to alert users of `recover` that broken invariants may be
+/// "speed bump" to alert users of `catch_unwind` that broken invariants may be
 /// witnessed and may need to be accounted for.
 ///
 /// ## Who implements `UnwindSafe`?
 ///
 /// Types such as `&mut T` and `&RefCell<T>` are examples which are **not**
-/// recover safe. The general idea is that any mutable state which can be shared
-/// across `recover` is not recover safe by default. This is because it is very
-/// easy to witness a broken invariant outside of `recover` as the data is
+/// unwind safe. The general idea is that any mutable state which can be shared
+/// across `catch_unwind` is not unwind safe by default. This is because it is very
+/// easy to witness a broken invariant outside of `catch_unwind` as the data is
 /// simply accessed as usual.
 ///
-/// Types like `&Mutex<T>`, however, are recover safe because they implement
+/// Types like `&Mutex<T>`, however, are unwind safe because they implement
 /// poisoning by default. They still allow witnessing a broken invariant, but
 /// they already provide their own "speed bumps" to do so.
 ///
 /// ## When should `UnwindSafe` be used?
 ///
 /// Is not intended that most types or functions need to worry about this trait.
-/// It is only used as a bound on the `recover` function and as mentioned above,
+/// It is only used as a bound on the `catch_unwind` function and as mentioned above,
 /// the lack of `unsafe` means it is mostly an advisory. The `AssertUnwindSafe`
 /// wrapper struct in this module can be used to force this trait to be
-/// implemented for any closed over variables passed to the `recover` function
+/// implemented for any closed over variables passed to the `catch_unwind` function
 /// (more on this below).
 #[stable(feature = "catch_unwind", since = "1.9.0")]
 #[rustc_on_unimplemented = "the type {Self} may not be safely transferred \
-                            across a recover boundary"]
+                            across an unwind boundary"]
 pub trait UnwindSafe {}
 
 /// Deprecated, renamed to UnwindSafe
@@ -126,7 +126,7 @@ pub trait RecoverSafe {}
 impl<T: UnwindSafe> RecoverSafe for T {}
 
 /// A marker trait representing types where a shared reference is considered
-/// recover safe.
+/// unwind safe.
 ///
 /// This trait is namely not implemented by `UnsafeCell`, the root of all
 /// interior mutability.
@@ -136,31 +136,31 @@ impl<T: UnwindSafe> RecoverSafe for T {}
 #[stable(feature = "catch_unwind", since = "1.9.0")]
 #[rustc_on_unimplemented = "the type {Self} contains interior mutability \
                             and a reference may not be safely transferrable \
-                            across a recover boundary"]
+                            across a catch_unwind boundary"]
 pub trait RefUnwindSafe {}
 
-/// A simple wrapper around a type to assert that it is panic safe.
+/// A simple wrapper around a type to assert that it is unwind safe.
 ///
-/// When using `recover` it may be the case that some of the closed over
-/// variables are not panic safe. For example if `&mut T` is captured the
-/// compiler will generate a warning indicating that it is not panic safe. It
+/// When using `catch_unwind` it may be the case that some of the closed over
+/// variables are not unwind safe. For example if `&mut T` is captured the
+/// compiler will generate a warning indicating that it is not unwind safe. It
 /// may not be the case, however, that this is actually a problem due to the
-/// specific usage of `recover` if panic safety is specifically taken into
+/// specific usage of `catch_unwind` if unwind safety is specifically taken into
 /// account. This wrapper struct is useful for a quick and lightweight
-/// annotation that a variable is indeed panic safe.
+/// annotation that a variable is indeed unwind safe.
 ///
 /// # Examples
 ///
 /// One way to use `AssertUnwindSafe` is to assert that the entire closure
-/// itself is recover safe, bypassing all checks for all variables:
+/// itself is unwind safe, bypassing all checks for all variables:
 ///
 /// ```
 /// use std::panic::{self, AssertUnwindSafe};
 ///
 /// let mut variable = 4;
 ///
 /// // This code will not compile because the closure captures `&mut variable`
-/// // which is not considered panic safe by default.
+/// // which is not considered unwind safe by default.
 ///
 /// // panic::catch_unwind(|| {
 /// //     variable += 3;
@@ -239,7 +239,7 @@ impl<T> UnwindSafe for AssertUnwindSafe<T> {}
 impl<T> UnwindSafe for AssertRecoverSafe<T> {}
 
 // not covered via the Shared impl above b/c the inner contents use
-// Cell/AtomicUsize, but the usage here is recover safe so we can lift the
+// Cell/AtomicUsize, but the usage here is unwind safe so we can lift the
 // impl up one level to Arc/Rc itself
 #[stable(feature = "catch_unwind", since = "1.9.0")]
 impl<T: RefUnwindSafe + ?Sized> UnwindSafe for Rc<T> {}
@@ -352,9 +352,9 @@ impl<R, F: FnOnce() -> R> FnOnce<()> for AssertRecoverSafe<F> {
 /// that all captured variables are safe to cross this boundary. The purpose of
 /// this bound is to encode the concept of [exception safety][rfc] in the type
 /// system. Most usage of this function should not need to worry about this
-/// bound as programs are naturally panic safe without `unsafe` code. If it
+/// bound as programs are naturally unwind safe without `unsafe` code. If it
 /// becomes a problem the associated `AssertUnwindSafe` wrapper type in this
-/// module can be used to quickly assert that the usage here is indeed exception
+/// module can be used to quickly assert that the usage here is indeed unwind
 /// safe.
 ///
 /// [rfc]: https://github.com/rust-lang/rfcs/blob/master/text/1236-stabilize-catch-panic.md