doc: a more complete explanation, and a better example

diff --git a/src/libcore/cell.rs b/src/libcore/cell.rs
index ea480f38947f982b9804ac8418be117ef6605e78..e75401f6ce031de718093fcb549c3019b31eba17 100644 (file)
--- a/src/libcore/cell.rs
+++ b/src/libcore/cell.rs
@@ -391,17 +391,17 @@ pub fn swap(&self, other: &Self) {
         }
     }
 
-    /// Replaces the contained value.
+    /// Replaces the contained value, and returns it.
     ///
     /// # Examples
     ///
     /// ```
     /// use std::cell::Cell;
     ///
-    /// let c = Cell::new(5);
-    /// let old = c.replace(10);
-    ///
-    /// assert_eq!(5, old);
+    /// let cell = Cell::new(5);
+    /// assert_eq!(cell.get(), 5);
+    /// assert_eq!(cell.replace(10), 5);
+    /// assert_eq!(cell.get(), 10);
     /// ```
     #[stable(feature = "move_cell", since = "1.17.0")]
     pub fn replace(&self, val: T) -> T {