docs: demonstrate ownedrefmut outliving scoped borrow

README.md

@@ -53,6 +53,16 @@ fn main() {
     // This is the major hazard of using `OwnedRefCell`.
     let total: i32 = shared_map.borrow().values().sum();
     assert_eq!(total, 116089);
+
+    // Note that OwnedRefMut outlives the scoped borrow, which would not compile
+    // when using RefCell/RefMut.
+    let map_ref = {
+        let mut map = shared_map.borrow_mut();
+        map.insert("purple", 1);
+        map
+    };
+    let total: i32 = map_ref.values().sum();
+    assert_eq!(total, 116090);
 }
 ```
 

src/lib.rs

@@ -47,6 +47,16 @@
 //! // This is the major hazard of using `RefCell`.
 //! let total: i32 = shared_map.borrow().values().sum();
 //! assert_eq!(total, 116089);
+//!
+//! // Note that OwnedRefMut outlives the scoped borrow, which would not compile
+//! // when using RefCell/RefMut.
+//! let map_ref = {
+//!     let mut map = shared_map.borrow_mut();
+//!     map.insert("purple", 1);
+//!     map
+//! };
+//! let total: i32 = map_ref.values().sum();
+//! assert_eq!(total, 116090);
 //! ```
 //!
 //! This module also provides:
@@ -204,6 +214,14 @@ mod tests {
 
         let total: i32 = shared_map.borrow().values().sum();
         assert_eq!(total, 10);
+
+        let map_ref = {
+            let mut map = shared_map.borrow_mut();
+            map.insert("e", 5);
+            map
+        };
+        let total: i32 = map_ref.values().sum();
+        assert_eq!(total, 15);
     }
 
     #[test]