RwLock: refine documentation to emphasize non-reentrancy guarantees
This addresses the need for clarification brought up in rust-lang/rust#149693. Specifically, it notes that some implementations may choose to panic if they detect deadlock situations during recursive locking attempts for both `read()` and `write()` calls.
* Provide an example highlighting that multiple read locks can be held across different threads simultaneously.
* Remove the example that shows a situation that can potentially deadlock. (as demonstrated in the very same documentation a few paragraphs above)
* Improve documentation regarding the possibility of panics during recursive read or write lock attempts.
Issues: https://github.com/rust-lang/rust/issues/149693
Jonathan Brouwer
5964330d29