update docs, test

library/alloc/src/vec/mod.rs

@@ -735,13 +735,9 @@ impl<T> Vec<T> {
         unsafe { Self::from_parts_in(ptr, length, capacity, Global) }
     }
 
-    /// Returns a mutable reference to the greatest item in the binary heap, or
+    /// Returns a mutable reference to the last item in the vector, or
     /// `None` if it is empty.
     ///
-    /// Note: If the `PeekMut` value is leaked, some heap elements might get
-    /// leaked along with it, but the remaining elements will remain a valid
-    /// heap.
-    ///
     /// # Examples
     ///
     /// Basic usage:

library/alloctests/tests/vec.rs

@@ -2708,6 +2708,8 @@ fn test_peek_mut() {
         assert_eq!(*p, 2);
         *p = 0;
         assert_eq!(*p, 0);
+        p.pop();
+        assert_eq!(vec.len(), 1);
     } else {
         unreachable!()
     }