Revise some documentation comments.

Author: natecook1000

stdlib/public/core/Result.swift

@@ -10,8 +10,8 @@
 //
 //===----------------------------------------------------------------------===//
 
-/// A value that represents either a success or failure, capturing associated
-/// values in both cases.
+/// A value that represents either a success or a failure, including an
+/// associated value in each case.
 @_frozen
 public enum Result<Success, Failure: Error> {
   /// A success, storing a `Success` value.
@@ -20,13 +20,24 @@ public enum Result<Success, Failure: Error> {
   /// A failure, storing a `Failure` value.
   case failure(Failure)
 
-  /// Evaluates the given closure when this `Result` instance is `.success`,
-  /// passing the success value as a parameter.
+  /// Returns a new result, mapping any success value using the given
+  /// transformation.
   ///
-  /// - Parameter transform: A closure that takes the success value of the
+  /// Use this method when you need to transform the value of a `Result`
+  /// instance when it represents a success. The following example transforms
+  /// the integer success value of a result into a string:
+  ///
+  ///     func getNextInteger() -> Result<Int, Error> { ... }
+  ///
+  ///     let integerResult = getNextInteger()
+  ///     // integerResult == .success(5)
+  ///     let stringResult = integerResult.map({ String($0) })
+  ///     // stringResult == .success("5")
+  ///
+  /// - Parameter transform: A closure that takes the success value of this
   ///   instance.
-  /// - Returns: A `Result` instance with the result of evaluating the given 
-  ///   closure as the new success value if this instance is `.success`.
+  /// - Returns: A `Result` instance with the result of evaluating `transform`
+  ///   as the new success value if this instance represents a success.
   public func map<NewSuccess>(
     _ transform: (Success) -> NewSuccess
   ) -> Result<NewSuccess, Failure> {
@@ -38,13 +49,32 @@ public enum Result<Success, Failure: Error> {
     }
   }
 
-  /// Evaluates the given closure when this `Result` instance is `.failure`,
-  /// passing the failure value as a parameter.
+  /// Returns a new result, mapping any failure value using the given
+  /// transformation.
+  ///
+  /// Use this method when you need to transform the value of a `Result`
+  /// instance when it represents a failure. The following example transforms
+  /// the error value of a result by wrapping it in a custom `Error` type:
+  ///
+  ///     struct DatedError: Error {
+  ///         var error: Error
+  ///         var date: Date
+  ///
+  ///         init(_ error: Error) {
+  ///             self.error = error
+  ///             self.date = Date()
+  ///         }
+  ///     }
+  ///
+  ///     let result: Result<Int, Error> = ...
+  ///     // result == .failure(<error value>)
+  ///     let resultWithDatedError = result.mapError({ e in DatedError(e) })
+  ///     // result == .failure(DatedError(error: <error value>, date: <date>))
   ///
   /// - Parameter transform: A closure that takes the failure value of the
   ///   instance.
-  /// - Returns: A `Result` instance with the result of evaluating the given
-  ///   closure as the new failure value if this instance is `.failure`.
+  /// - Returns: A `Result` instance with the result of evaluating `transform`
+  ///   as the new failure value if this instance represents a failure.
   public func mapError<NewFailure>(
     _ transform: (Failure) -> NewFailure
   ) -> Result<Success, NewFailure> {
@@ -56,13 +86,13 @@ public enum Result<Success, Failure: Error> {
     }
   }
 
-  /// Evaluates the given closure when this `Result` instance is `.success`,
-  /// passing the success value as a parameter.
+  /// Returns a new result, mapping any success value using the given
+  /// transformation and unwrapping the produced result.
   ///
   /// - Parameter transform: A closure that takes the success value of the
   ///   instance.
-  /// - Returns: A`Result` instance, either from the closure or the previous 
-  ///   `.failure`.
+  /// - Returns: A `Result` instance with the result of evaluating `transform`
+  ///   as the new failure value if this instance represents a failure.
   public func flatMap<NewSuccess>(
     _ transform: (Success) -> Result<NewSuccess, Failure>
   ) -> Result<NewSuccess, Failure> {
@@ -74,8 +104,8 @@ public enum Result<Success, Failure: Error> {
     }
   }
 
-  /// Evaluates the given closure when this `Result` instance is `.failure`,
-  /// passing the failure value as a parameter.
+  /// Returns a new result, mapping any failure value using the given
+  /// transformation and unwrapping the produced result.
   ///
   /// - Parameter transform: A closure that takes the failure value of the
   ///   instance.
@@ -92,10 +122,22 @@ public enum Result<Success, Failure: Error> {
     }
   }
 
-  /// Get the success value as a throwing expression.
+  /// Returns the success value as a throwing expression.
+  ///
+  /// Use this method to retrieve the value of this result if it represents a
+  /// success, or to catch the value if it represents a failure.
+  ///
+  ///     let integerResult: Result<Int, Error> = .success(5)
+  ///     do {
+  ///         let value = try integerResult.get()
+  ///         print("The value is \(value).")
+  ///     } catch error {
+  ///         print("Error retrieving the value: \(error)")
+  ///     }
+  ///     // Prints "The value is 5."
   ///
-  /// - Returns: The success value, if the instance is `.success`.
-  /// - Throws:  The failure value, if the instance is `.failure`.
+  /// - Returns: The success value, if the instance represent a success.
+  /// - Throws: The failure value, if the instance represents a failure.
   public func get() throws -> Success {
     switch self {
     case let .success(success):
@@ -107,10 +149,10 @@ public enum Result<Success, Failure: Error> {
 }
 
 extension Result where Failure == Swift.Error {
-  /// Create an instance by evaluating a throwing closure, capturing the 
-  /// returned value as a `.success` or any thrown error as `.failure`.
+  /// Creates a new result by evaluating a throwing closure, capturing the
+  /// returned value as a success, or any thrown error as a failure.
   ///
-  /// - Parameter catching: A throwing closure to evaluate.
+  /// - Parameter body: A throwing closure to evaluate.
   @_transparent
   public init(catching body: () throws -> Success) {
     do {