[stdlib] Documentation revisions

- Make RawRepresentable Codable abstracts distinguishable
- Make the UnboundedRange example a little more user friendly
- Correct the RangeReplaceableCollection example description
- Revise CaseIterable discussion

Author: natecook1000

stdlib/public/core/Codable.swift.gyb

@@ -1767,7 +1767,8 @@ extension ${type} : Codable {
 }
 
 extension RawRepresentable where RawValue == ${type}, Self : Encodable {
-  /// Encodes this value into the given encoder.
+  /// Encodes this value into the given encoder, when the type's `RawValue`
+  /// is `${type}`.
   ///
   /// This function throws an error if any values are invalid for the given
   /// encoder's format.
@@ -1781,7 +1782,8 @@ extension RawRepresentable where RawValue == ${type}, Self : Encodable {
 }
 
 extension RawRepresentable where RawValue == ${type}, Self : Decodable {
-  /// Creates a new instance by decoding from the given decoder.
+  /// Creates a new instance by decoding from the given decoder, when the
+  /// type's `RawValue` is `${type}`.
   ///
   /// This initializer throws an error if reading from the decoder fails, or
   /// if the data read is corrupted or otherwise invalid.

stdlib/public/core/CollectionOfOne.swift

@@ -10,7 +10,9 @@
 //
 //===----------------------------------------------------------------------===//
 
-/// An iterator that produces one or fewer instances of `Element`.
+/// An iterator that produces one or zero instances of an element.
+///
+/// `IteratorOverOne` is the iterator for the `CollectionOfOne` type.
 @_fixed_layout // FIXME(sil-serialize-all)
 public struct IteratorOverOne<Element> {
   @usableFromInline // FIXME(sil-serialize-all)
@@ -31,8 +33,8 @@ extension IteratorOverOne: IteratorProtocol, Sequence {
   ///
   /// Once `nil` has been returned, all subsequent calls return `nil`.
   ///
-  /// - Precondition: `next()` has not been applied to a copy of `self`
-  ///   since the copy was made.
+  /// - Returns: The next element in the underlying sequence, if a next element
+  ///   exists; otherwise, `nil`.
   @inlinable // FIXME(sil-serialize-all)
   public mutating func next() -> Element? {
     let result = _elements
@@ -41,7 +43,17 @@ extension IteratorOverOne: IteratorProtocol, Sequence {
   }
 }
 
-/// A collection containing a single element of type `Element`.
+/// A collection containing a single element.
+///
+/// You can use a `CollectionOfOne` instance to efficiently represent a
+/// collection with only one element. For example, you can add a single element
+/// to an array by using a `CollectionOfOne` instance with the concatenation
+/// operator (`+`):
+///
+///     let a = [1, 2, 3, 4]
+///     let toAdd = 100
+///     let b = a + CollectionOfOne(toAdd)
+///     // b == [1, 2, 3, 4, 100]
 @_fixed_layout // FIXME(sil-serialize-all)
 public struct CollectionOfOne<Element> {
   @usableFromInline // FIXME(sil-serialize-all)
@@ -60,6 +72,8 @@ extension CollectionOfOne: RandomAccessCollection, MutableCollection {
   public typealias Indices = Range<Int>
 
   /// The position of the first element.
+  ///
+  /// In a `CollectionOfOne` instance, `startIndex` is always `0`.
   @inlinable // FIXME(sil-serialize-all)
   public var startIndex: Int {
     return 0
@@ -68,38 +82,45 @@ extension CollectionOfOne: RandomAccessCollection, MutableCollection {
   /// The "past the end" position---that is, the position one greater than the
   /// last valid subscript argument.
   ///
-  /// In a `CollectionOfOne` instance, `endIndex` is always identical to
-  /// `index(after: startIndex)`.
+  /// In a `CollectionOfOne` instance, `endIndex` is always `1`.
   @inlinable // FIXME(sil-serialize-all)
   public var endIndex: Int {
     return 1
   }
 
-  /// Always returns `endIndex`.
+  /// 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 value immediately after `i`.
   @inlinable // FIXME(sil-serialize-all)
   public func index(after i: Int) -> Int {
     _precondition(i == startIndex)
     return endIndex
   }
 
-  /// Always returns `startIndex`.
+  /// 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 value immediately before `i`.
   @inlinable // FIXME(sil-serialize-all)
   public func index(before i: Int) -> Int {
     _precondition(i == endIndex)
     return startIndex
   }
 
-  /// Returns an iterator over the elements of this sequence.
+  /// Returns an iterator over the elements of this collection.
   ///
-  /// - Complexity: O(1).
+  /// - Complexity: O(1)
   @inlinable // FIXME(sil-serialize-all)
   public func makeIterator() -> IteratorOverOne<Element> {
     return IteratorOverOne(_elements: _element)
   }
 
   /// Accesses the element at `position`.
   ///
-  /// - Precondition: `position == 0`.
+  /// The only valid position in a `CollectionOfOne` instance is `0`.
   @inlinable // FIXME(sil-serialize-all)
   public subscript(position: Int) -> Element {
     get {
@@ -129,15 +150,15 @@ extension CollectionOfOne: RandomAccessCollection, MutableCollection {
     }
   }
 
-  /// The number of elements (always one).
+  /// The number of elements in the collection, which is always one.
   @inlinable // FIXME(sil-serialize-all)
   public var count: Int {
     return 1
   }
 }
 
 extension CollectionOfOne : CustomDebugStringConvertible {
-  /// A textual representation of `self`, suitable for debugging.
+  /// A textual representation of the collection, suitable for debugging.
   @inlinable // FIXME(sil-serialize-all)
   public var debugDescription: String {
     return "CollectionOfOne(\(String(reflecting: _element)))"

stdlib/public/core/CompilerProtocols.swift

@@ -178,37 +178,42 @@ public func != <T : Equatable>(lhs: T, rhs: T) -> Bool
   return lhs.rawValue != rhs.rawValue
 }
 
-/// A type that can produce a collection of all of its values.
+/// A type that provides a collection of all of its values.
 ///
-/// Simple Enumerations
-/// ===================
+/// Types that conform to the `CaseIterable` protocol are typically
+/// enumerations without associated values. When using a `CaseIterable` type,
+/// you can access a collection of all of the type's cases by using the type's
+/// `allCases` property.
 ///
-/// For any Swift enumeration where every case does not have an associated
-/// value, the Swift compiler can automatically fill out the `CaseIterable`
-/// conformance. When defining your own custom enumeration, specify a
-/// conformance to `CaseIterable` to take advantage of this automatic
-/// derivation.
+/// For example, the `CompassDirection` enumeration declared in this example
+/// conforms to `CaseIterable`. You access the number of cases and the cases
+/// themselves through `CompassDirection.allCases`.
 ///
-/// For example, every case of the `CardinalPoint` enumeration defined here
-/// does not have an associated value:
-///
-///     enum CardinalPoint: CaseIterable {
+///     enum CompassDirection: CaseIterable {
 ///         case north, south, east, west
 ///     }
 ///
-/// So the compiler automatically creates a conformance.
+///     print("There are \(CompassDirection.allCases.count) directions.")
+///     // Prints "There are 4 directions."
+///     let caseList = CompassDirection.allCases
+///                                    .map({ "\($0)" })
+///                                    .joined(separator: ", "))
+///     // caseList == "north, south, east, west"
 ///
-///     for cardinality in CardinalPoint.allCases {
-///         print(cardinality)
-///     }
-///     // Prints "north"
-///     // Prints "south"
-///     // Prints "east"
-///     // Prints "west"
+/// Conforming to the CaseIterable Protocol
+/// =======================================
+///
+/// The compiler can automatically provide an implementation of the
+/// `CaseIterable` requirements for any enumeration without associated values.
+/// To take advantage of this automatic synthesis when defining your own custom
+/// enumeration, specify conformance to the `CaseIterable` protocol in the
+/// original declaration.
 public protocol CaseIterable {
+  /// A type that can represent a collection of all values of this type.
   associatedtype AllCases: Collection
     where AllCases.Element == Self
-  /// Returns a collection of all values of this type.
+  
+  /// A collection of all values of this type.
   static var allCases: AllCases { get }
 }
 

stdlib/public/core/Range.swift

@@ -606,18 +606,29 @@ extension PartialRangeFrom: Sequence
 {
   public typealias Element = Bound
 
+  /// The iterator for a `PartialRangeFrom` instance.
   @_fixed_layout
   public struct Iterator: IteratorProtocol {
     @usableFromInline
     internal var _current: Bound
     @inlinable
     public init(_current: Bound) { self._current = _current }
+
+    /// Advances to the next element and returns it, or `nil` if no next
+    /// element exists.
+    ///
+    /// Once `nil` has been returned, all subsequent calls return `nil`.
+    ///
+    /// - Returns: The next element in the underlying sequence, if a next
+    ///   element exists; otherwise, `nil`.
     @inlinable
     public mutating func next() -> Bound? {
       defer { _current = _current.advanced(by: 1) }
       return _current
     }
   }
+
+  /// Returns an iterator for this sequence.
   @inlinable
   public func makeIterator() -> Iterator { 
     return Iterator(_current: lowerBound) 
@@ -739,30 +750,33 @@ extension Comparable {
 /// unbounded range is essentially a conversion of a collection instance into
 /// its slice type.
 ///
-/// For example, the following code declares `levenshteinDistance(_:_:)`, a
-/// function that calculates the number of changes required to convert one
-/// string into another. `levenshteinDistance(_:_:)` uses `Substring`, a
-/// string's slice type, for its parameters.
+/// For example, the following code declares `countLetterChanges(_:_:)`, a
+/// function that finds the number of changes required to change one
+/// word or phrase into another. The function uses a recursive approach to
+/// perform the same comparisons on smaller and smaller pieces of the original
+/// strings. In order to use recursion without making copies of the strings at
+/// each step, `countLetterChanges(_:_:)` uses `Substring`, a string's slice
+/// type, for its parameters.
 ///
-///     func levenshteinDistance(_ s1: Substring, _ s2: Substring) -> Int {
+///     func countLetterChanges(_ s1: Substring, _ s2: Substring) -> Int {
 ///         if s1.isEmpty { return s2.count }
 ///         if s2.isEmpty { return s1.count }
 ///
 ///         let cost = s1.first == s2.first ? 0 : 1
 ///
 ///         return min(
-///             levenshteinDistance(s1.dropFirst(), s2) + 1,
-///             levenshteinDistance(s1, s2.dropFirst()) + 1,
-///             levenshteinDistance(s1.dropFirst(), s2.dropFirst()) + cost)
+///             countLetterChanges(s1.dropFirst(), s2) + 1,
+///             countLetterChanges(s1, s2.dropFirst()) + 1,
+///             countLetterChanges(s1.dropFirst(), s2.dropFirst()) + cost)
 ///     }
 ///
-/// To call `levenshteinDistance(_:_:)` with two strings, use an unbounded
-/// range in each string's subscript to convert it to a `Substring`.
+/// To call `countLetterChanges(_:_:)` with two strings, use an unbounded
+/// range in each string's subscript.
 ///
 ///     let word1 = "grizzly"
 ///     let word2 = "grisly"
-///     let distance = levenshteinDistance(word1[...], word2[...])
-///     // distance == 2
+///     let changes = countLetterChanges(word1[...], word2[...])
+///     // changes == 2
 @_frozen // FIXME(sil-serialize-all)
 public enum UnboundedRange_ {
   // FIXME: replace this with a computed var named `...` when the language makes

stdlib/public/core/RangeReplaceableCollection.swift

@@ -553,7 +553,7 @@ extension RangeReplaceableCollection {
   /// Removes the elements in the specified subrange from the collection.
   ///
   /// All the elements following the specified position are moved to close the
-  /// gap. This example removes two elements from the middle of an array of
+  /// gap. This example removes three elements from the middle of an array of
   /// measurements.
   ///
   ///     var measurements = [1.2, 1.5, 2.9, 1.2, 1.5]
@@ -754,7 +754,7 @@ extension RangeReplaceableCollection {
   /// Removes the elements in the specified subrange from the collection.
   ///
   /// All the elements following the specified position are moved to close the
-  /// gap. This example removes two elements from the middle of an array of
+  /// gap. This example removes three elements from the middle of an array of
   /// measurements.
   ///
   ///     var measurements = [1.2, 1.5, 2.9, 1.2, 1.5]