[stdlib] Documentation revisions and expansions

- Adding docs for unbounded ranges
- Filling in missing docs for range-expression subscripts
- Equality operators for arrays
- Fix issues with range discussions
- Fill in missing integer docs

Author: natecook1000

stdlib/public/core/Arrays.swift.gyb

@@ -491,8 +491,20 @@ public struct ${Self}<Element>: _DestructorSafeContainer {
 }
 
 extension ${Self}: RandomAccessCollection, MutableCollection {
+  /// The index type for arrays, `Int`.
+  %if Self == 'ArraySlice':
+  ///
+  /// `ArraySlice` instances are not always indexed from zero. Use `startIndex`
+  /// and `endIndex` as the bounds for any element access, instead of `0` and
+  /// `count`.
+  %end
   public typealias Index = Int
+
+  /// The type that represents the indices that are valid for subscripting an
+  /// array, in ascending order.
   public typealias Indices = Range<Int>
+
+  /// The type that allows iteration over an array's elements.
   public typealias Iterator = IndexingIterator<${Self}>
 
 %if Self == 'ArraySlice':
@@ -541,6 +553,11 @@ extension ${Self}: RandomAccessCollection, MutableCollection {
 %end
   }
 
+  /// Returns the position immediately after the given index.
+  ///
+  /// - Parameter i: A valid index of the collection. `i` must be less than
+  ///   `endIndex`.
+  /// - Returns: The index immediately after `i`.
   @_inlineable
   public func index(after i: Int) -> Int {
     // NOTE: this is a manual specialization of index movement for a Strideable
@@ -551,6 +568,10 @@ extension ${Self}: RandomAccessCollection, MutableCollection {
     return i + 1
   }
 
+  /// Replaces the given index with its successor.
+  ///
+  /// - Parameter i: A valid index of the collection. `i` must be less than
+  ///   `endIndex`.
   @_inlineable
   public func formIndex(after i: inout Int) {
     // NOTE: this is a manual specialization of index movement for a Strideable
@@ -561,6 +582,11 @@ extension ${Self}: RandomAccessCollection, MutableCollection {
     i += 1
   }
 
+  /// Returns the position immediately before the given index.
+  ///
+  /// - Parameter i: A valid index of the collection. `i` must be greater than
+  ///   `startIndex`.
+  /// - Returns: The index immediately before `i`.
   @_inlineable
   public func index(before i: Int) -> Int {
     // NOTE: this is a manual specialization of index movement for a Strideable
@@ -571,6 +597,10 @@ extension ${Self}: RandomAccessCollection, MutableCollection {
     return i - 1
   }
 
+  /// Replaces the given index with its predecessor.
+  ///
+  /// - Parameter i: A valid index of the collection. `i` must be greater than
+  ///   `startIndex`.
   @_inlineable
   public func formIndex(before i: inout Int) {
     // NOTE: this is a manual specialization of index movement for a Strideable
@@ -2200,7 +2230,15 @@ extension _ArrayBufferProtocol {
 % for (Self, a_Self) in arrayTypes:
 
 extension ${Self} : Equatable where Element : Equatable {
-  /// Returns `true` if these arrays contain the same elements.
+  /// Returns a Boolean value indicating whether two arrays contain the same
+  /// elements in the same order.
+  ///
+  /// You can use the equal-to operator (`==`) to compare any two arrays
+  /// that store the same, `Equatable`-conforming element type.
+  ///
+  /// - Parameters:
+  ///   - lhs: An array to compare.
+  ///   - rhs: Another array to compare.
   @_inlineable
   public static func ==(lhs: ${Self}<Element>, rhs: ${Self}<Element>) -> Bool {
     let lhsCount = lhs.count
@@ -2243,7 +2281,15 @@ extension ${Self} : Equatable where Element : Equatable {
     return true
   }
 
-  /// Returns `true` if the arrays do not contain the same elements.
+  /// Returns a Boolean value indicating whether two arrays are not equal.
+  ///
+  /// Two arrays are equal if they contain the same elements in the same order.
+  /// You can use the not-equal-to operator (`!=`) to compare any two arrays
+  /// that store the same, `Equatable`-conforming element type.
+  ///
+  /// - Parameters:
+  ///   - lhs: An array to compare.
+  ///   - rhs: Another array to compare.
   @_inlineable
   public static func !=(lhs: ${Self}<Element>, rhs: ${Self}<Element>) -> Bool {
     return !(lhs == rhs)

stdlib/public/core/ClosedRange.swift

@@ -13,7 +13,7 @@
 // FIXME: swift-3-indexing-model: Generalize all tests to check both
 // [Closed]Range.
 
-/// A closed range that forms a collection of consecutive values.
+/// An interval from a lower bound up to, and including, an upper bound.
 ///
 /// You create a `ClosedRange` instance by using the closed range
 /// operator (`...`).
@@ -23,51 +23,49 @@
 /// A `ClosedRange` instance contains both its lower bound and its
 /// upper bound.
 ///
-///     print(throughFive.contains(3))      // Prints "true"
-///     print(throughFive.contains(10))     // Prints "false"
-///     print(throughFive.contains(5))      // Prints "true"
+///     throughFive.contains(3)
+///     // true
+///     throughFive.contains(10)
+///     // false
+///     throughFive.contains(5)
+///     // true
 ///
 /// Because a closed range includes its upper bound, a closed range whose lower
-/// bound is equal to the upper bound contains one element. Therefore, a
+/// bound is equal to the upper bound contains that value. Therefore, a
 /// `ClosedRange` instance cannot represent an empty range.
 ///
 ///     let zeroInclusive = 0...0
-///     print(zeroInclusive.isEmpty)
-///     // Prints "false"
-///     print(zeroInclusive.count)
-///     // Prints "1"
+///     zeroInclusive.contains(0)
+///     // true
+///     zeroInclusive.isEmpty
+///     // false
 ///
-/// You can use a `for`-`in` loop or any sequence or collection method with a
-/// countable range. The elements of the range are the consecutive values from
-/// its lower bound up to, and including, its upper bound.
+/// Using a Closed Range as a Collection of Consecutive Values
+/// ----------------------------------------------------------
 ///
-///     for n in throughFive.suffix(3) {
+/// When a closed range uses integers as its lower and upper bounds, or any
+/// other type that conforms to the `Strideable` protocol with an integer
+/// stride, you can use that range in a `for`-`in` loop or with any sequence or
+/// collection method. The elements of the range are the consecutive values
+/// from its lower bound up to, and including, its upper bound.
+///
+///     for n in 3...5 {
 ///         print(n)
 ///     }
 ///     // Prints "3"
 ///     // Prints "4"
 ///     // Prints "5"
 ///
-/// You can create a countable range over any type that conforms to the
-/// `Strideable` protocol and uses an integer as its associated `Stride` type.
-/// By default, Swift's integer and pointer types are usable as the bounds of
-/// a countable range.
-///
 /// Because floating-point types such as `Float` and `Double` are their own
 /// `Stride` types, they cannot be used as the bounds of a countable range. If
-/// you need to test whether values are contained within a closed interval
-/// bound by floating-point values, see the `ClosedRange` type. If you need to
-/// iterate over consecutive floating-point values, see the
+/// you need to iterate over consecutive floating-point values, see the
 /// `stride(from:through:by:)` function.
 @_fixed_layout
 public struct ClosedRange<Bound: Comparable> {
   /// The range's lower bound.
   public let lowerBound: Bound
 
   /// The range's upper bound.
-  ///
-  /// `upperBound` is always reachable from `lowerBound` by zero or
-  /// more applications of `index(after:)`.
   public let upperBound: Bound
 
   /// Creates an instance with the given bounds.

stdlib/public/core/Collection.swift

@@ -69,11 +69,11 @@ public typealias Indexable = Collection
 ///         }
 ///     }
 ///
-/// The `CollectionOfTwo` type uses the default iterator type,
-/// `IndexingIterator`, because it doesn't define its own `makeIterator()`
-/// method or `Iterator` associated type. This example shows how a
-/// `CollectionOfTwo` instance can be created holding the values of a point,
-/// and then iterated over using a `for`-`in` loop.
+/// Because `CollectionOfTwo` doesn't define its own `makeIterator()`
+/// method or `Iterator` associated type, it uses the default iterator type,
+/// `IndexingIterator`. This example shows how a `CollectionOfTwo` instance
+/// can be created holding the values of a point, and then iterated over
+/// using a `for`-`in` loop.
 ///
 ///     let point = CollectionOfTwo(15.0, 20.0)
 ///     for element in point {
@@ -426,22 +426,35 @@ public protocol Collection: Sequence where SubSequence: Collection {
 
   /// Accesses a contiguous subrange of the collection's elements.
   ///
-  /// The accessed slice uses the same indices for the same elements as the
-  /// original collection uses. Always use the slice's `startIndex` property
-  /// instead of assuming that its indices start at a particular value.
-  ///
-  /// This example demonstrates getting a slice of an array of strings, finding
-  /// the index of one of the strings in the slice, and then using that index
-  /// in the original array.
+  /// For example, using a `PartialRangeFrom` range expression with an array
+  /// accesses the subrange from the start of the range expression until the
+  /// end of the array.
   ///
   ///     let streets = ["Adams", "Bryant", "Channing", "Douglas", "Evarts"]
-  ///     let streetsSlice = streets[2 ..< streets.endIndex]
+  ///     let streetsSlice = streets[2..<5]
   ///     print(streetsSlice)
-  ///     // Prints "["Channing", "Douglas", "Evarts"]"
+  ///     // ["Channing", "Douglas", "Evarts"]
   ///
-  ///     let index = streetsSlice.index(of: "Evarts")    // 4
-  ///     print(streets[index!])
-  ///     // Prints "Evarts"
+  /// The accessed slice uses the same indices for the same elements as the
+  /// original collection. This example searches `streetsSlice` for one of the
+  /// strings in the slice, and then uses that index in the original array.
+  ///
+  ///     let index = streetsSlice.index(of: "Evarts")!    // 4
+  ///     print(streets[index])
+  ///     // "Evarts"
+  ///
+  /// Always use the slice's `startIndex` property instead of assuming that its
+  /// indices start at a particular value. Attempting to access an element by
+  /// using an index outside the bounds of the slice may result in a runtime
+  /// error, even if that index is valid for the original collection.
+  ///
+  ///     print(streetsSlice.startIndex)
+  ///     // 2
+  ///     print(streetsSlice[2])
+  ///     // "Channing"
+  ///
+  ///     print(streetsSlice[0])
+  ///     // error: Index out of bounds
   ///
   /// - Parameter bounds: A range of the collection's indices. The bounds of
   ///   the range must be valid indices of the collection.
@@ -1044,7 +1057,7 @@ extension Collection where SubSequence == Slice<Self> {
   /// Accesses a contiguous subrange of the collection's elements.
   ///
   /// The accessed slice uses the same indices for the same elements as the
-  /// original collection uses. Always use the slice's `startIndex` property
+  /// original collection. Always use the slice's `startIndex` property
   /// instead of assuming that its indices start at a particular value.
   ///
   /// This example demonstrates getting a slice of an array of strings, finding

stdlib/public/core/Integers.swift.gyb

@@ -1585,12 +1585,18 @@ ${assignmentOperatorComment(x.nonMaskingOperator, False)}
 }
 
 extension BinaryInteger {
+  /// Creates a new value equal to zero.
   @_inlineable // FIXME(sil-serialize-all)
   @_transparent
   public init() {
     self = 0
   }
 
+  /// Returns `-1` if this value is negative and `1` if it's positive;
+  /// otherwise, `0`.
+  ///
+  /// - Returns: The sign of this number, expressed as an integer of the same
+  ///   type.
   @_inlineable // FIXME(sil-serialize-all)
   @_transparent
   public func signum() -> Self {
@@ -1835,6 +1841,7 @@ extension Int {
     return other - self
   }
 
+  // FIXME(ABI): using Int as the parameter type is wrong.
   /// Returns a value that is offset the specified distance from this value.
   ///
   /// Use the `advanced(by:)` method in generic code to offset a value by a
@@ -1846,7 +1853,6 @@ extension Int {
   ///
   /// - Parameter n: The distance to advance this value.
   /// - Returns: A value that is offset from this value by `n`.
-  // FIXME(ABI): using Int as the parameter type is wrong.
   @_inlineable // FIXME(sil-serialize-all)
   @_transparent
   public func advanced(by n: Int) -> Int {
@@ -3000,6 +3006,7 @@ public struct ${Self}
   : FixedWidthInteger, ${Unsigned}Integer,
     _ExpressibleByBuiltinIntegerLiteral {
 
+  /// A type that represents an integer literal.
   public typealias IntegerLiteralType = ${Self}