catch_unwind docs are unclear about panic hook

[charles-r-earp]

Location

std::panic::catch_unwind

Summary

The docs for std::panic::catch_unwind notes section:

Notes

Note that 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.

Note that if a custom panic hook has been set, it will be invoked before the panic is caught, before unwinding.

Also note that unwinding into Rust code with a foreign exception (e.g. an exception thrown from C++ code) is undefined behavior.

The second paragraph says "if a custom panic hook has been set". This implies a simple program like the following will not print a panic message, but it does:

fn main() {
    let _ = std::panic::catch_unwind(|| panic!());
}
// output
thread 'main' panicked at src/main.rs:2:41:
explicit panic
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace

This is the default hook, there is no need to set a custom one.

The text could be changed to something like "if a panic hook is set", as well as further discussion of the panic hook, which is covered in the panic! docs, but none of the docs for panic!, set_hook, or take_hook mention catch_unwind. There's no discussion in the parent panic module.

In typical usage catch_unwind will involve set_hook and take_hook, so the docs should cover this.

[Psalmuel01]

i would like to be assigned this to work on the docs