[stdlib] Add flatMap example in Result.swift

stdlib/public/core/Result.swift

@@ -89,6 +89,25 @@ public enum Result<Success, Failure: Error> {
   /// Returns a new result, mapping any success value using the given
   /// transformation and unwrapping the produced result.
   ///
+  /// Use this method to avoid a nested result when your transformation
+  /// produces another `Result` type.
+  ///
+  /// In this example, note the difference in the result of using `map` and
+  /// `flatMap` with a transformation that returns an result type.
+  ///
+  ///     func getNextInteger() -> Result<Int, Error> {
+  ///         .success(4)
+  ///     }
+  ///     func getNextAfterInteger(_ n: Int) -> Result<Int, Error> {
+  ///         .success(n + 1)
+  ///     }
+  ///
+  ///     let result = getNextInteger().map({ getNextAfterInteger($0) })
+  ///     // result == .success(.success(5))
+  ///
+  ///     let result = getNextInteger().flatMap({ getNextAfterInteger($0) })
+  ///     // result == .success(5)
+  ///
   /// - Parameter transform: A closure that takes the success value of the
   ///   instance.
   /// - Returns: A `Result` instance with the result of evaluating `transform`