Document unwind-safety without referencing an RFC

14c46d3
Opened by Simon Sapin at 2020-03-06 23:12:20

https://doc.rust-lang.org/std/panic/trait.UnwindSafe.html currently says:

for more information about unwind safety and how it applies to Rust, see an associated RFC.

While this RFC is very informative, much of it is dedicated to Rust as it was before the RFC was implemented, possible alternatives, and trade-offs. This can be a distraction for someone not involved in programming language design and who just wants to learn how to safely use FFI in today’s Rust. (Which is admittedly intrinsically hard.)

Perhaps the Nomicon would be an appropriate alternative?

https://doc.rust-lang.org/nomicon/unwinding.html https://doc.rust-lang.org/nomicon/exception-safety.html https://doc.rust-lang.org/nomicon/poisoning.html

  1. Triage: no changes. I think describing panicing in std::panic makes sense, but updating the nomicon and such would be good as well.

    Steve Klabnik at 2018-05-28 16:17:45

  2. @steveklabnik I can pick this up if you want? It's mainly adding references at the right places to the sources mentioned above right? Or are there other things that should be added?

    Christian Vayne at 2019-04-02 15:06:17

  3. That'd be great! yeah, basically, we need to re-write those docs to explain the concept directly. PRs for the other sources would be nice too :)

    Steve Klabnik at 2019-04-02 18:55:29

  4. @steveklabnik Alright! I'll put it on my todo list! I'll hope to have created a PR somewhere this week.

    Christian Vayne at 2019-04-03 10:09:54

  5. Sorry for the long delay! I scanned through the repository for any links to the RFC. And I found these:

    • https://doc.rust-lang.org/std/panic/fn.catch_unwind.html
    • https://doc.rust-lang.org/std/panic/trait.UnwindSafe.html

    Just to be sure that I understand correctly:

    I should probably update these docs and point them to the correct nomicon links provided earlier right? Or should other documentation be rewritten as well? I am not very knowledgable on panic and unwinding yet, but if that is the case I am willing to dig into it a bit!

    Christian Vayne at 2019-05-04 10:46:56

  6. Yes; pointing to the nomicon is the easy path; writing brand-new docs that explain everything is the hard path :)

    Steve Klabnik at 2019-05-16 12:27:41

  7. Sorry for the late reply! I have been busy with some things for the last couple of weeks, and I since I will start with my new job tomorrow I won't have time to work on this. Hopefully, someone else can pick this up!

    Christian Vayne at 2019-06-02 10:50:08