catch_unwind should NOT be undefined for foreign exceptions; also document possible abort in JoinHandle

Author: BatmanAoD

library/std/src/panic.rs

@@ -311,18 +311,19 @@ where
 ///
 /// # Notes
 ///
-/// This function **might not catch all panics** in Rust. A panic in Rust is not
-/// always implemented via unwinding, but can be implemented by aborting the
-/// process as well. This function *only* catches unwinding panics, not those
-/// that abort the process.
+/// This function **cannot** catch panics when `panic=abort`, or with a manually written panic
+/// handler that aborts the process.
 ///
 /// If a custom panic hook has been set, it will be invoked before the panic is
 /// caught, before unwinding.
 ///
 /// Although unwinding into Rust code with a foreign exception (e.g. an
-/// exception thrown from C++ code) via an appropriate ABI (e.g. `"C-unwind"`)
-/// is permitted, catching such an exception using this function is undefined
-/// behavior.
+/// exception thrown from C++ code, or a `panic!` in Rust code compiled or linked with a different
+/// runtime) via an appropriate ABI (e.g. `"C-unwind"`) is permitted, catching such an exception
+/// using this function will have one of two behaviors, and it is unspecified which will occur:
+///
+/// * The process aborts.
+/// * The function returns a `Result::Err` containing an opaque type.
 ///
 /// Finally, be **careful in how you drop the result of this function**.
 /// If it is `Err`, it contains the panic payload, and dropping that may in turn panic!

library/std/src/thread/mod.rs

@@ -1739,7 +1739,7 @@ impl<T> JoinHandle<T> {
     /// operations that happen after `join` returns.
     ///
     /// If the associated thread panics, [`Err`] is returned with the parameter given
-    /// to [`panic!`].
+    /// to [`panic!`] (though see the Notes below).
     ///
     /// [`Err`]: crate::result::Result::Err
     /// [atomic memory orderings]: crate::sync::atomic
@@ -1761,6 +1761,16 @@ impl<T> JoinHandle<T> {
     /// }).unwrap();
     /// join_handle.join().expect("Couldn't join on the associated thread");
     /// ```
+    ///
+    /// # Notes
+    ///
+    /// This function has the same minimal guarantee regarding "foreign" unwinding operations (e.g.
+    /// an exception thrown from C++ code, or a `panic!` in Rust code compiled or linked with a
+    /// different runtime) as [`catch_unwind`]; namely, catching such an exception using this
+    /// function will have one of two behaviors, and it is unspecified which will occur:
+    ///
+    /// * The process aborts.
+    /// * The function returns a `Result::Err` containing an opaque type.
     #[stable(feature = "rust1", since = "1.0.0")]
     pub fn join(self) -> Result<T> {
         self.0.join()