[stdlib] Clean up various documentation issues (#3804)

* [stdlib] Clean up some documentation formatting

* [stdlib] Update example code for SE-0103

* [stdlib] Fix UnsafeBufferPointer documentation typo

* [stdlib] Collection documentation cleanup

* [stdlib] Fix String.init?(_:UTF16View) description

* [stdlib] Documentation fixes for SE-0091

* [stdlib] Add param info for String(repeating:count:)

Author: natecook1000

stdlib/public/core/Collection.swift

@@ -188,9 +188,6 @@ public protocol Indexable : IndexableBase {
   ///   to `index(before:)`.
   ///
   /// - SeeAlso: `index(_:offsetBy:limitedBy:)`, `formIndex(_:offsetBy:)`
-  /// - Precondition:
-  ///   - If `n > 0`, `n <= self.distance(from: i, to: self.endIndex)`
-  ///   - If `n < 0`, `n >= self.distance(from: i, to: self.startIndex)`
   /// - Complexity: O(1) if the collection conforms to
   ///   `RandomAccessCollection`; otherwise, O(*n*), where *n* is the absolute
   ///   value of `n`.
@@ -234,9 +231,6 @@ public protocol Indexable : IndexableBase {
   ///   the method returns `nil`.
   ///
   /// - SeeAlso: `index(_:offsetBy:)`, `formIndex(_:offsetBy:limitedBy:)`
-  /// - Precondition:
-  ///   - If `n > 0`, `n <= self.distance(from: i, to: self.endIndex)`
-  ///   - If `n < 0`, `n >= self.distance(from: i, to: self.startIndex)`
   /// - Complexity: O(1) if the collection conforms to
   ///   `RandomAccessCollection`; otherwise, O(*n*), where *n* is the absolute
   ///   value of `n`.
@@ -256,9 +250,6 @@ public protocol Indexable : IndexableBase {
   ///     collection conforms to the `BidirectionalCollection` protocol.
   ///
   /// - SeeAlso: `index(_:offsetBy:)`, `formIndex(_:offsetBy:limitedBy:)`
-  /// - Precondition:
-  ///   - If `n > 0`, `n <= self.distance(from: i, to: self.endIndex)`
-  ///   - If `n < 0`, `n >= self.distance(from: i, to: self.startIndex)`
   /// - Complexity: O(1) if the collection conforms to
   ///   `RandomAccessCollection`; otherwise, O(*n*), where *n* is the absolute
   ///   value of `n`.
@@ -412,18 +403,18 @@ public struct IndexingIterator<
 /// A sequence whose elements can be traversed multiple times,
 /// nondestructively, and accessed by indexed subscript.
 ///
-/// Collections are used extensively throughout the standard library. When
-/// you use arrays, dictionaries, views of a string's contents and other
-/// types, you benefit from the operations that the `Collection` protocol
-/// declares and implements.
+/// Collections are used extensively throughout the standard library. When you
+/// use arrays, dictionaries, views of a string's contents and other types,
+/// you benefit from the operations that the `Collection` protocol declares
+/// and implements.
 ///
 /// In addition to the methods that collections inherit from the `Sequence`
 /// protocol, you gain access to methods that depend on accessing an element
 /// at a specific position when using a collection.
 ///
-/// For example, if you want to print only the first word in a string,
-/// search for the index of the first space, and then create a subsequence up
-/// to that position.
+/// For example, if you want to print only the first word in a string, search
+/// for the index of the first space and then create a subsequence up to that
+/// position.
 ///
 ///     let text = "Buffalo buffalo buffalo buffalo."
 ///     if let firstSpace = text.characters.index(of: " ") {
@@ -464,24 +455,24 @@ public struct IndexingIterator<
 ///     print(firstChar)
 ///     // Prints "B"
 ///
-/// The `Collection` protocol declares and provides default implementations
-/// for many operations that depend on elements being accessible by their
-/// subscript. For example, you can also access the first character of
-/// `text` using the `first` property, which has the value of the first
-/// element of the collection, or `nil` if the collection is empty.
+/// The `Collection` protocol declares and provides default implementations for
+/// many operations that depend on elements being accessible by their
+/// subscript. For example, you can also access the first character of `text`
+/// using the `first` property, which has the value of the first element of
+/// the collection, or `nil` if the collection is empty.
 ///
 ///     print(text.characters.first)
 ///     // Prints "Optional("B")"
 ///
-/// Traversing a Collection 
+/// Traversing a Collection
 /// =======================
 ///
-/// While a sequence may be consumed as it is traversed, a collection is
-/// guaranteed to be multi-pass: Any element may be repeatedly accessed by
-/// saving its index. Moreover, a collection's indices form a finite range
-/// of the positions of the collection's elements. This guarantees the
-/// safety of operations that depend on a sequence being finite, such as
-/// checking to see whether a collection contains an element.
+/// Although a sequence can be consumed as it is traversed, a collection is
+/// guaranteed to be multipass: Any element may be repeatedly accessed by
+/// saving its index. Moreover, a collection's indices form a finite range of
+/// the positions of the collection's elements. This guarantees the safety of
+/// operations that depend on a sequence being finite, such as checking to see
+/// whether a collection contains an element.
 ///
 /// Iterating over the elements of a collection by their positions yields the
 /// same elements in the same order as iterating over that collection using
@@ -498,7 +489,7 @@ public struct IndexingIterator<
 ///     // Prints "i"
 ///     // Prints "f"
 ///     // Prints "t"
-/// 
+///
 ///     for i in word.characters.indices {
 ///         print(word.characters[i])
 ///     }
@@ -508,26 +499,28 @@ public struct IndexingIterator<
 ///     // Prints "f"
 ///     // Prints "t"
 ///
-/// Conforming to the Collection Protocol 
+/// Conforming to the Collection Protocol
 /// =====================================
 ///
 /// If you create a custom sequence that can provide repeated access to its
-/// elements, conformance to the `Collection` protocol gives your custom type
-/// a more useful and more efficient interface for sequence and collection
-/// operations. To add `Collection` conformance to your type, declare
-/// `startIndex` and `endIndex` properties, a subscript that provides at least
-/// read-only access to your type's elements, and the `index(after:)` method
-/// for advancing your collection's indices.
+/// elements, make sure that its type conforms to the `Collection` protocol in
+/// order to give a more useful and more efficient interface for sequence and
+/// collection operations. To add `Collection` conformance to your type, you
+/// must declare at least the four following requirements:
+///
+/// - the `startIndex` and `endIndex` properties,
+/// - a subscript that provides at least read-only access to your type's
+///   elements, and
+/// - the `index(after:)` method for advancing an index into your collection.
 ///
 /// Expected Performance
 /// ====================
 ///
-/// Types that conform to `Collection` are expected to provide the
-/// `startIndex` and `endIndex` properties and subscript access to elements
-/// as O(1) operations. Types that are not able to guarantee that expected
-/// performance must document the departure, because many collection operations
-/// depend on O(1) subscripting performance for their own performance
-/// guarantees.
+/// Types that conform to `Collection` are expected to provide the `startIndex`
+/// and `endIndex` properties and subscript access to elements as O(1)
+/// operations. Types that are not able to guarantee that expected performance
+/// must document the departure, because many collection operations depend on
+/// O(1) subscripting performance for their own performance guarantees.
 ///
 /// The performance of some collection operations depends on the type of index
 /// that the collection provides. For example, a random-access collection,
@@ -696,7 +689,6 @@ public protocol Collection : Indexable, Sequence {
   ///   `start` must be a valid index of the collection.
   /// - Returns: A subsequence starting at the `start` position.
   ///
-  /// - Precondition: `start >= self.startIndex && start <= self.endIndex`
   /// - Complexity: O(1)
   func suffix(from start: Index) -> SubSequence
 
@@ -790,9 +782,6 @@ public protocol Collection : Indexable, Sequence {
   ///   to `index(before:)`.
   ///
   /// - SeeAlso: `index(_:offsetBy:limitedBy:)`, `formIndex(_:offsetBy:)`
-  /// - Precondition:
-  ///   - If `n > 0`, `n <= self.distance(from: i, to: self.endIndex)`
-  ///   - If `n < 0`, `n >= self.distance(from: i, to: self.startIndex)`
   /// - Complexity: O(1) if the collection conforms to
   ///   `RandomAccessCollection`; otherwise, O(*n*), where *n* is the absolute
   ///   value of `n`.
@@ -836,9 +825,6 @@ public protocol Collection : Indexable, Sequence {
   ///   the method returns `nil`.
   ///
   /// - SeeAlso: `index(_:offsetBy:)`, `formIndex(_:offsetBy:limitedBy:)`
-  /// - Precondition:
-  ///   - If `n > 0`, `n <= self.distance(from: i, to: self.endIndex)`
-  ///   - If `n < 0`, `n >= self.distance(from: i, to: self.startIndex)`
   /// - Complexity: O(1) if the collection conforms to
   ///   `RandomAccessCollection`; otherwise, O(*n*), where *n* is the absolute
   ///   value of `n`.
@@ -856,8 +842,8 @@ public protocol Collection : Indexable, Sequence {
   ///   - end: Another valid index of the collection. If `end` is equal to
   ///     `start`, the result is zero.
   /// - Returns: The distance between `start` and `end`. The result can be
-  ///   negative only if the collection conforms to the `BidirectionalCollection`
-  ///   protocol.
+  ///   negative only if the collection conforms to the
+  ///   `BidirectionalCollection` protocol.
   ///
   /// - Complexity: O(1) if the collection conforms to
   ///   `RandomAccessCollection`; otherwise, O(*n*), where *n* is the
@@ -926,9 +912,6 @@ extension Indexable {
   ///   to `index(before:)`.
   ///
   /// - SeeAlso: `index(_:offsetBy:limitedBy:)`, `formIndex(_:offsetBy:)`
-  /// - Precondition:
-  ///   - If `n > 0`, `n <= self.distance(from: i, to: self.endIndex)`
-  ///   - If `n < 0`, `n >= self.distance(from: i, to: self.startIndex)`
   /// - Complexity: O(1) if the collection conforms to
   ///   `RandomAccessCollection`; otherwise, O(*n*), where *n* is the absolute
   ///   value of `n`.
@@ -974,9 +957,6 @@ extension Indexable {
   ///   the method returns `nil`.
   ///
   /// - SeeAlso: `index(_:offsetBy:)`, `formIndex(_:offsetBy:limitedBy:)`
-  /// - Precondition:
-  ///   - If `n > 0`, `n <= self.distance(from: i, to: self.endIndex)`
-  ///   - If `n < 0`, `n >= self.distance(from: i, to: self.startIndex)`
   /// - Complexity: O(1) if the collection conforms to
   ///   `RandomAccessCollection`; otherwise, O(*n*), where *n* is the absolute
   ///   value of `n`.
@@ -998,9 +978,6 @@ extension Indexable {
   ///     collection conforms to the `BidirectionalCollection` protocol.
   ///
   /// - SeeAlso: `index(_:offsetBy:)`, `formIndex(_:offsetBy:limitedBy:)`
-  /// - Precondition:
-  ///   - If `n > 0`, `n <= self.distance(from: i, to: self.endIndex)`
-  ///   - If `n < 0`, `n >= self.distance(from: i, to: self.startIndex)`
   /// - Complexity: O(1) if the collection conforms to
   ///   `RandomAccessCollection`; otherwise, O(*n*), where *n* is the absolute
   ///   value of `n`.
@@ -1414,7 +1391,6 @@ extension Collection {
   ///   `end` must be a valid index of the collection.
   /// - Returns: A subsequence up to, but not including, the `end` position.
   ///
-  /// - Precondition: `end >= self.startIndex && end <= self.endIndex`
   /// - Complexity: O(1)
   /// - SeeAlso: `prefix(through:)`
   public func prefix(upTo end: Index) -> SubSequence {
@@ -1442,7 +1418,6 @@ extension Collection {
   ///   subsequence. `start` must be a valid index of the collection.
   /// - Returns: A subsequence starting at the `start` position.
   ///
-  /// - Precondition: `start >= self.startIndex && start <= self.endIndex`
   /// - Complexity: O(1)
   public func suffix(from start: Index) -> SubSequence {
     return self[start..<endIndex]

stdlib/public/core/Comparable.swift

@@ -63,12 +63,13 @@
 /// - `a < b` and `b < c` implies `a < c` (Transitivity)
 ///
 /// To add `Comparable` conformance to your custom types, define the `<` and
-/// `==` operators. The `==` operator is a requirement of the `Equatable`
-/// protocol, which `Comparable` extends---see that protocol's documentation
-/// for more information about equality in Swift. Because default
-/// implementations of the remainder of the relational operators are provided
-/// by the standard library, you'll be able to use `!=`, `>`, `<=`, and `>=`
-/// with instances of your type without any further code.
+/// `==` operators as static methods of your types. The `==` operator is a
+/// requirement of the `Equatable` protocol, which `Comparable` extends---see
+/// that protocol's documentation for more information about equality in
+/// Swift. Because default implementations of the remainder of the relational
+/// operators are provided by the standard library, you'll be able to use
+/// `!=`, `>`, `<=`, and `>=` with instances of your type without any further
+/// code.
 ///
 /// As an example, here's an implementation of a `Date` structure that stores
 /// the year, month, and day of a date:
@@ -92,7 +93,6 @@
 ///                 return lhs.day < rhs.day
 ///             }
 ///         }
-///     }
 ///
 /// This function uses the least specific nonmatching property of the date to
 /// determine the result of the comparison. For example, if the two `year`
@@ -102,9 +102,10 @@
 /// Next, implement the `==` operator function, the requirement inherited from
 /// the `Equatable` protocol.
 ///
-///     func == (lhs: Date, rhs: Date) -> Bool {
-///         return lhs.year == rhs.year && lhs.month == rhs.month
-///             && lhs.day == rhs.day
+///         static func == (lhs: Date, rhs: Date) -> Bool {
+///             return lhs.year == rhs.year && lhs.month == rhs.month
+///                 && lhs.day == rhs.day
+///         }
 ///     }
 ///
 /// Two `Date` instances are equal if each of their corresponding properties is

stdlib/public/core/CompilerProtocols.swift

@@ -262,7 +262,7 @@ public protocol _ExpressibleByBuiltinUnicodeScalarLiteral {
 ///     // Prints "ñ"
 ///
 /// Conforming to ExpressibleByUnicodeScalarLiteral
-/// =============================================
+/// ===============================================
 ///
 /// To add `ExpressibleByUnicodeScalarLiteral` conformance to your custom type,
 /// implement the required initializer.
@@ -305,7 +305,7 @@ public protocol _ExpressibleByBuiltinExtendedGraphemeClusterLiteral
 ///     // Prints "❄︎"
 ///
 /// Conforming to ExpressibleByExtendedGraphemeClusterLiteral
-/// =======================================================
+/// =========================================================
 ///
 /// To add `ExpressibleByExtendedGraphemeClusterLiteral` conformance to your
 /// custom type, implement the required initializer.
@@ -349,7 +349,7 @@ public protocol _ExpressibleByBuiltinUTF16StringLiteral
 ///     let picnicGuest = "Deserving porcupine"
 ///
 /// Conforming to ExpressibleByStringLiteral
-/// ======================================
+/// ========================================
 ///
 /// To add `ExpressibleByStringLiteral` conformance to your custom type,
 /// implement the required initializer.
@@ -456,7 +456,7 @@ public protocol ExpressibleByStringLiteral
 ///     // Prints "Zero integers: []"
 ///
 /// Conforming to ExpressibleByArrayLiteral
-/// =====================================
+/// =======================================
 ///
 /// Add the capability to be initialized with an array literal to your own
 /// custom types by declaring an `init(arrayLiteral:)` initializer. The
@@ -514,7 +514,7 @@ public protocol ExpressibleByArrayLiteral {
 ///   by assigning an instance of one of these types.
 ///
 /// Conforming to the ExpressibleByDictionaryLiteral Protocol
-/// =======================================================
+/// =========================================================
 ///
 /// To add the capability to be initialized with a dictionary literal to your
 /// own custom types, declare an `init(dictionaryLiteral:)` initializer. The
@@ -565,7 +565,7 @@ public protocol ExpressibleByDictionaryLiteral {
 ///     // Prints "One cookie: $2, 3 cookies: $6."
 ///
 /// Conforming to the ExpressibleByStringInterpolation Protocol
-/// =========================================================
+/// ===========================================================
 ///
 /// To use string interpolation to initialize instances of your custom type,
 /// implement the required initializers for `ExpressibleByStringInterpolation`

stdlib/public/core/Equatable.swift

@@ -48,10 +48,10 @@
 /// `Comparable` protocols, which allow more uses of your custom type, such as
 /// constructing sets or sorting the elements of a collection.
 ///
-/// To adopt the `Equatable` protocol, implement the equal-to operator (`==`).
-/// The standard library provides an implementation for the not-equal-to
-/// operator (`!=`) for any `Equatable` type, which calls the custom `==`
-/// function and negates its result.
+/// To adopt the `Equatable` protocol, implement the equal-to operator (`==`)
+/// as a static method of your type. The standard library provides an
+/// implementation for the not-equal-to operator (`!=`) for any `Equatable`
+/// type, which calls the custom `==` function and negates its result.
 ///
 /// As an example, consider a `StreetAddress` structure that holds the parts of
 /// a street address: a house or building number, the street name, and an
@@ -76,12 +76,12 @@
 /// `Equatable`.
 ///
 ///     extension StreetAddress: Equatable {
-///       static func == (lhs: StreetAddress, rhs: StreetAddress) -> Bool {
-///         return
-///             lhs.number == rhs.number &&
-///             lhs.street == rhs.street &&
-///             lhs.unit == rhs.unit
-///       }
+///         static func == (lhs: StreetAddress, rhs: StreetAddress) -> Bool {
+///             return
+///                 lhs.number == rhs.number &&
+///                 lhs.street == rhs.street &&
+///                 lhs.unit == rhs.unit
+///         }
 ///     }
 ///
 /// The `StreetAddress` type now conforms to `Equatable`. You can use `==` to

stdlib/public/core/HashedCollections.swift.gyb

@@ -368,7 +368,6 @@ internal struct _UnmanagedAnyObjectArray {
 ///     print(primes.intersection(favoriteNumbers))
 ///     // Prints "[5, 7]"
 ///
-///
 /// Sequence and Collection Operations
 /// ==================================
 ///

stdlib/public/core/LazySequence.swift

@@ -47,7 +47,7 @@
 ///       /// - Complexity: O(N)
 ///       func scan<ResultElement>(
 ///         _ initial: ResultElement,
-///         _ nextPartialResult: @noescape (ResultElement, Iterator.Element) -> ResultElement
+///         _ nextPartialResult: (ResultElement, Iterator.Element) -> ResultElement
 ///       ) -> [ResultElement] {
 ///         var result = [initial]
 ///         for x in self {