[WIP] Revise documentation for Swift 5 stdlib additions

stdlib/public/core/CompilerProtocols.swift

@@ -709,39 +709,39 @@ public protocol ExpressibleByDictionaryLiteral {
 ///     print(message)
 ///     // Prints "One cookie: $2, 3 cookies: $6."
 /// 
-/// Extending default interpolation behavior
-/// ========================================
+/// Extending the Default Interpolation Behavior
+/// ============================================
 /// 
-/// Clients which want to add new interpolation behavior to existing types
-/// should extend `DefaultStringInterpolation`, the type which implements
-/// interpolation for types like `String` and `Substring`, to add an overload of
-/// `appendInterpolation(_:)` with their new behavior. See the
-/// `DefaultStringInterpolation` and `StringInterpolationProtocol` documentation
-/// for more details.
+/// Add new interpolation behavior to existing types by extending
+/// `DefaultStringInterpolation`, the type which implements interpolation for
+/// types like `String` and `Substring` to add an overload of
+/// `appendInterpolation(_:)` with their new behavior.
+///
+/// For more information, see the `DefaultStringInterpolation` and
+/// `StringInterpolationProtocol` documentation.
 /// 
-/// Creating a type which supports default string interpolation
-/// ===========================================================
+/// Creating a Type That Supports the Default String Interpolation
+/// ==============================================================
 /// 
-/// Clients which want to create new types supporting string literals and
-/// interpolation, but which do not need any custom behavior, should conform
-/// their type to `ExpressibleByStringInterpolation` and implement an
-/// `init(stringLiteral: String)` method. Swift will automatically use
+/// To create a new type that supports string literals and interpolation, but
+/// that doesn't need any custom behavior, conform the type to
+/// `ExpressibleByStringInterpolation` and implement an
+/// `init(stringLiteral: String)` initializer. Swift will automatically use
 /// `DefaultStringInterpolation` and provide an `init(stringInterpolation:)`
 /// implementation which passes the interpolated literal's contents to
-/// `init(stringLiteral:)`, so you won't need to implement anything special.
+/// `init(stringLiteral:)`, so you don't need to implement anything special.
 ///
-/// Creating a type which supports custom string interpolation
-/// ==========================================================
-/// 
-/// If a conforming type wants to differentiate between literal and interpolated
-/// segments, restrict the types which can be interpolated into it, support
-/// different interpolators from the ones on `String`, or avoid constructing a
-/// `String` containing the data, it must specify a custom `StringInterpolation`
-/// associated type. This type must conform to `StringInterpolationProtocol` and
-/// must have a matching `StringLiteralType`.
-///
-/// See the `StringLiteralProtocol` documentation for more details about how to
-/// do this.
+/// Creating a Type That Supports Custom String Interpolation
+/// =========================================================
+///
+/// If you want a conforming type to differentiate between literal and
+/// interpolated segments, restrict the types that can be interpolated into it,
+/// support different interpolators from the ones on `String`, or avoid
+/// constructing a `String` containing the data, the type must specify a custom
+/// `StringInterpolation` associated type. This type must conform to
+/// `StringInterpolationProtocol` and have a matching `StringLiteralType`.
+///
+/// For more information, see the `StringLiteralProtocol` documentation.
 public protocol ExpressibleByStringInterpolation
   : ExpressibleByStringLiteral {
 
@@ -770,7 +770,7 @@ extension ExpressibleByStringInterpolation
 
   /// Creates a new instance from an interpolated string literal.
   /// 
-  /// Do not call this initializer directly. It is used by the compiler when
+  /// Don't call this initializer directly. It's used by the compiler when
   /// you create a string using string interpolation. Instead, use string
   /// interpolation to create a new string by including values, literals,
   /// variables, or expressions enclosed in parentheses, prefixed by a
@@ -789,7 +789,7 @@ extension ExpressibleByStringInterpolation
   }
 }
 
-/// Represents the contents of a string literal with interpolations while it is
+/// Represents the contents of a string literal with interpolations while it's
 /// being built up.
 /// 
 /// Each `ExpressibleByStringInterpolation` type has an associated
@@ -809,54 +809,57 @@ extension ExpressibleByStringInterpolation
 /// The `StringInterpolation` type is responsible for collecting the segments
 /// passed to its `appendLiteral(_:)` and `appendInterpolation` methods and
 /// assembling them into a whole, converting as necessary. Once all of the
-/// segments have been appended, the interpolation will be passed to an
+/// segments are appended, the interpolation is passed to an
 /// `init(stringInterpolation:)` initializer on the type being created, which
 /// must extract the accumulated data from the `StringInterpolation`.
 /// 
-/// In simple cases, types conforming to `ExpressibleByStringInterpolation`
-/// can use `DefaultStringInterpolation` instead of writing their own. All they
-/// must do is conform to `ExpressibleByStringInterpolation` and implement
-/// `init(stringLiteral: String)`; interpolated string literals will then go
-/// through that initializer just as any other string literal would.
+/// In simple cases, you can use `DefaultStringInterpolation` for types that
+/// conform to `ExpressibleByStringInterpolation` instead of writing your own.
+/// To use the default interpolation, conform a type to
+/// `ExpressibleByStringInterpolation` and implement
+/// `init(stringLiteral: String)`; interpolated string literals pass through
+/// that initializer just as any other string literal would.
 /// 
-/// The `appendInterpolation` Method
+/// The appendInterpolation Method
 /// ================================
 /// 
 /// Each interpolated segment is translated into a call to a
 /// `StringInterpolationProtocol.appendInterpolation(...)` method, with the
 /// contents of the interpolation's parentheses treated as the call's argument
 /// list. That argument list can include multiple arguments and argument labels.
-/// For example:
-/// 
-/// | If you write... | Swift calls...                    |
-/// |---------------- | --------------------------------- |
-/// | `\(x)`          | `appendInterpolation(x)`          |
-/// | `\(x, y)`       | `appendInterpolation(x, y)`       |
-/// | `\(foo: x)`     | `appendInterpolation(foo: x)`     |
-/// | `\(x, foo: y)`  | `appendInterpolation(x, foo: y)`  |
-/// 
-/// `appendInterpolation` methods should return `Void` and should not be
-/// `static`. They otherwise support virtually all features of methods: they can
-/// have any number of parameters, can specify labels for any or all of them,
-/// can provide default values for parameters, can have variadic parameters, and
-/// can have parameters with generic types. Most importantly, they can be
-/// overloaded, so a `StringInterpolationProtocol`-conforming type can provide
-/// several different `appendInterpolation` methods with different behaviors.
-/// `appendInterpolation` methods can also throw; when a user uses one of these,
-/// they must mark the string literal with `try` or one of its variants.
+///
+/// The following examples show how string interpolations are translated into
+/// calls to `appendInterpolation`:
+///
+/// - `\(x)` translates to `appendInterpolation(x)`
+/// - `\(x, y)` translates to `appendInterpolation(x, y)`
+/// - `\(foo: x)` translates to `appendInterpolation(foo: x)`
+/// - `\(x, foo: y)` translates to `appendInterpolation(x, foo: y)`
+///
+/// The `appendInterpolation` methods you write should return `Void` and
+/// shouldn't be `static`. They otherwise support virtually all features of
+/// methods: they can have any number of parameters, can specify labels for any
+/// or all of them, can provide default values for parameters, can have variadic
+/// parameters, and can have parameters with generic types. Most importantly,
+/// they can be overloaded, so a type that conforms to
+/// `StringInterpolationProtocol` can provide several different
+/// `appendInterpolation` methods with different behaviors. The
+/// `appendInterpolation` methods can also throw; when a user calls one of these
+/// methods using string interpolation, they must mark the string literal with
+/// `try` or one of its variants.
 public protocol StringInterpolationProtocol {
   /// The type that should be used for literal segments.
   associatedtype StringLiteralType : _ExpressibleByBuiltinStringLiteral
 
   /// Creates an empty instance ready to be filled with string literal content.
   /// 
-  /// Do not call this initializer directly. Instead, initialize a variable or
+  /// Don't call this initializer directly. Instead, initialize a variable or
   /// constant using a string literal with interpolated expressions.
   /// 
   /// Swift passes this initializer a pair of arguments specifying the size of
   /// the literal segments and the number of interpolated segments. Use this
   /// information to estimate the amount of storage you will need and
-  /// pre-allocate it with a method like
+  /// preallocate it with a method like
   /// `RangeReplaceableCollection.reserveCapacity(_:)`.
   /// 
   /// - Parameter literalCapacity: The approximate size of all literal segments
@@ -870,12 +873,12 @@ public protocol StringInterpolationProtocol {
 
   /// Appends a literal segment to the interpolation.
   /// 
-  /// Do not call this method directly. Instead, initialize a variable or
+  /// Don't call this method directly. Instead, initialize a variable or
   /// constant using a string literal with interpolated expressions.
   /// 
-  /// Interpolated expressions do not pass through this method; instead, Swift
-  /// selects an overload of `appendInterpolation`. See the top-level
-  /// `StringInterpolationProtocol` documentation for more details.
+  /// Interpolated expressions don't pass through this method; instead, Swift
+  /// selects an overload of `appendInterpolation`. For more information, see
+  /// the top-level `StringInterpolationProtocol` documentation.
   /// 
   /// - Parameter literal: A string literal containing the characters
   ///             that appear next in the string literal.

stdlib/public/core/Dictionary.swift

@@ -921,10 +921,10 @@ extension Dictionary {
   }
 
   /// Returns a new dictionary containing only the key-value pairs that have
-  /// non-`nil` values as the result from the transform by the given closure.
+  /// non-`nil` values as the result of transformation by the given closure.
   ///
-  /// Use this method to receive a dictionary of non-optional values when your
-  /// transformation can produce an optional value.
+  /// Use this method to receive a dictionary with non-optional values when
+  /// your transformation produces optional values.
   ///
   /// In this example, note the difference in the result of using `mapValues`
   /// and `compactMapValues` with a transformation that returns an optional

stdlib/public/core/Integers.swift

@@ -27,12 +27,45 @@ extension ExpressibleByIntegerLiteral
 //===--- AdditiveArithmetic -----------------------------------------------===//
 //===----------------------------------------------------------------------===//
 
-// FIXME: Add doc comment.
+/// A type with values that support addition and subtraction.
+///
+/// The `AdditiveArithmetic` protocol provides a suitable basis for additive
+/// arithmetic on scalar values, such as integers and floating-point numbers,
+/// or vectors. You can write generic methods that operate on any numeric type
+/// in the standard library by using the `AdditiveArithmetic` protocol as a
+/// generic constraint.
+///
+/// The following code declares a method that calculates the total of any
+/// sequence with `Numeric` elements.
+///
+///     extension Sequence where Element: AdditiveArithmetic {
+///         func sum() -> Element {
+///             return reduce(.zero, +)
+///         }
+///     }
+///
+/// The `sum()` method is now available on any sequence with values that
+/// conform to `AdditiveArithmetic`, whether it is an array of `Double` or a
+/// range of `Int`.
+///
+///     let arraySum = [1.1, 2.2, 3.3, 4.4, 5.5].sum()
+///     // arraySum == 16.5
+///
+///     let rangeSum = (1..<10).sum()
+///     // rangeSum == 45
+///
+/// Conforming to the AdditiveArithmetic Protocol
+/// =============================================
+///
+/// To add `AdditiveArithmetic` protocol conformance to your own custom type,
+/// implement the required operators, and provide a static `zero` property
+/// using a type that can represent the magnitude of any value of your custom
+/// type.
 public protocol AdditiveArithmetic : Equatable {
   /// The zero value.
   ///
-  /// - Note: Zero is the identity element for addition; for any value,
-  ///   `x + .zero == x` and `.zero + x == x`.
+  /// Zero is the identity element for addition. For any value,
+  /// `x + .zero == x` and `.zero + x == x`.
   static var zero: Self { get }
 
   /// Adds two values and produces their sum.
@@ -96,6 +129,10 @@ public protocol AdditiveArithmetic : Equatable {
 }
 
 public extension AdditiveArithmetic where Self : ExpressibleByIntegerLiteral {
+  /// The zero value.
+  ///
+  /// Zero is the identity element for addition. For any value,
+  /// `x + .zero == x` and `.zero + x == x`.
   static var zero: Self {
     return 0
   }
@@ -105,41 +142,41 @@ public extension AdditiveArithmetic where Self : ExpressibleByIntegerLiteral {
 //===--- Numeric ----------------------------------------------------------===//
 //===----------------------------------------------------------------------===//
 
-// FIXME: Update comment based on the `AdditiveArithmetic` change.
-/// Declares methods backing binary arithmetic operators--such as `+`, `-` and
-/// `*`--and their mutating counterparts.
+/// A type with values that support multiplication.
 ///
 /// The `Numeric` protocol provides a suitable basis for arithmetic on
 /// scalar values, such as integers and floating-point numbers. You can write
 /// generic methods that operate on any numeric type in the standard library
 /// by using the `Numeric` protocol as a generic constraint.
 ///
-/// The following example declares a method that calculates the total of any
-/// sequence with `Numeric` elements.
+/// The following example extends `Seqeunce` with a method that returns an
+/// array with the sequence's values multiplied by two.
 ///
 ///     extension Sequence where Element: Numeric {
-///         func sum() -> Element {
-///             return reduce(0, +)
+///         func doublingAll() -> [Element] {
+///             return map { $0 * 2 }
 ///         }
 ///     }
 ///
-/// The `sum()` method is now available on any sequence or collection with
-/// numeric values, whether it is an array of `Double` or a countable range of
-/// `Int`.
+/// With this extension, any sequence with elements that conform to `Numeric`
+/// has the `doublingAll()` method. For example, you can double the elements of
+/// an array of doubles or a range of integers:
 ///
-///     let arraySum = [1.1, 2.2, 3.3, 4.4, 5.5].sum()
-///     // arraySum == 16.5
+///     let observations = [1.5, 2.0, 3.25, 4.875, 5.5]
+///     let doubledObservations = observations.doublingAll()
+///     // doubledObservations == [3.0, 4.0, 6.5, 9.75, 11.0]
 ///
-///     let rangeSum = (1..<10).sum()
-///     // rangeSum == 45
+///     let integers = 0..<8
+///     let doubledIntegers = integers.doublingAll()
+///     // doubledIntegers == [0, 2, 4, 6, 8, 10, 12, 14]
 ///
 /// Conforming to the Numeric Protocol
-/// =====================================
+/// ==================================
 ///
 /// To add `Numeric` protocol conformance to your own custom type, implement
-/// the required mutating methods. Extensions to `Numeric` provide default
-/// implementations for the protocol's nonmutating methods based on the
-/// mutating variants.
+/// the required initializer and operators, and provide a `magnitude` property
+/// using a type that can represent the magnitude of any value of your custom
+/// type.
 public protocol Numeric : AdditiveArithmetic, ExpressibleByIntegerLiteral {
   /// Creates a new instance from the given integer, if it can be represented
   /// exactly.
@@ -216,7 +253,7 @@ public protocol Numeric : AdditiveArithmetic, ExpressibleByIntegerLiteral {
 /// `Numeric` protocol to include a value's additive inverse.
 ///
 /// Conforming to the SignedNumeric Protocol
-/// ===========================================
+/// ========================================
 ///
 /// Because the `SignedNumeric` protocol provides default implementations of
 /// both of its required methods, you don't need to do anything beyond
@@ -1163,19 +1200,20 @@ public protocol BinaryInteger :
   func quotientAndRemainder(dividingBy rhs: Self)
     -> (quotient: Self, remainder: Self)
 
-  /// Returns true if this value is a multiple of `other`, and false otherwise.
+  /// Returns `true` if this value is a multiple of the given value, and `false`
+  /// otherwise.
   ///
-  /// For two integers a and b, a is a multiple of b if there exists a third
-  /// integer q such that a = q*b. For example, 6 is a multiple of 3, because
-  /// 6 = 2*3, and zero is a multiple of everything, because 0 = 0*x, for any
-  /// integer x.
+  /// For two integers *a* and *b*, *a* is a multiple of *b* if there exists a
+  /// third integer *q* such that _a = q*b_. For example, *6* is a multiple of
+  /// *3* because _6 = 2*3_. Zero is a multiple of everything because _0 = 0*x_
+  /// for any integer *x*.
   ///
   /// Two edge cases are worth particular attention:
   /// - `x.isMultiple(of: 0)` is `true` if `x` is zero and `false` otherwise.
   /// - `T.min.isMultiple(of: -1)` is `true` for signed integer `T`, even
-  ///   though the quotient `T.min / -1` is not representable in type `T`.
+  ///   though the quotient `T.min / -1` isn't representable in type `T`.
   ///
-  /// - Parameter other: the value to test.
+  /// - Parameter other: The value to test.
   func isMultiple(of other: Self) -> Bool
 
   /// Returns `-1` if this value is negative and `1` if it's positive;

stdlib/public/core/Result.swift

@@ -27,7 +27,7 @@ public enum Result<Success, Failure: Error> {
   /// 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> { ... }
+  ///     func getNextInteger() -> Result<Int, Error> { /* ... */ }
   ///
   ///     let integerResult = getNextInteger()
   ///     // integerResult == .success(5)
@@ -66,7 +66,7 @@ public enum Result<Success, Failure: Error> {
   ///         }
   ///     }
   ///
-  ///     let result: Result<Int, Error> = ...
+  ///     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>))
@@ -136,7 +136,7 @@ public enum Result<Success, Failure: Error> {
   ///     }
   ///     // Prints "The value is 5."
   ///
-  /// - Returns: The success value, if the instance represent a success.
+  /// - Returns: The success value, if the instance represents a success.
   /// - Throws: The failure value, if the instance represents a failure.
   public func get() throws -> Success {
     switch self {