Clarifying that .map() returns None if None.

1 files changed, 4 insertions, 2 deletions

diff --git a/library/core/src/option.rs b/library/core/src/option.rs
index c43b728022d..f485763b234 100644
--- a/library/core/src/option.rs
+++ b/library/core/src/option.rs
@@ -943,7 +943,7 @@ impl<T> Option<T> {
     // Transforming contained values
     /////////////////////////////////////////////////////////////////////////
 
-    /// Maps an `Option<T>` to `Option<U>` by applying a function to a contained value.
+    /// Maps an `Option<T>` to `Option<U>` by applying a function to a contained value (if `Some`) or return `None` (if `None`).
     ///
     /// # Examples
     ///
@@ -955,8 +955,10 @@ impl<T> Option<T> {
     /// let maybe_some_string = Some(String::from("Hello, World!"));
     /// // `Option::map` takes self *by value*, consuming `maybe_some_string`
     /// let maybe_some_len = maybe_some_string.map(|s| s.len());
-    ///
     /// assert_eq!(maybe_some_len, Some(13));
+    ///
+    /// let x: Option<&str> = None;
+    /// assert_eq!(x.map(|s| s.len()), None);
     /// ```
     #[inline]
     #[stable(feature = "rust1", since = "1.0.0")]