Merge pull request #3177 from natecook1000/nc-docs-split

[stdlib] Fix and clean up 'split' documentation

Author: natecook1000

stdlib/public/core/Collection.swift

@@ -1140,7 +1140,6 @@ extension Collection where SubSequence == Slice<Self> {
   }
 }
 
-// TODO: swift-3-indexing-model - review the following
 extension Collection where SubSequence == Self {
   /// Removes and returns the first element of the collection.
   ///
@@ -1149,6 +1148,7 @@ extension Collection where SubSequence == Self {
   ///
   /// - Complexity: O(1)
   public mutating func popFirst() -> Iterator.Element? {
+    // TODO: swift-3-indexing-model - review the following
     guard !isEmpty else { return nil }
     let element = first!
     self = self[index(after: startIndex)..<endIndex]
@@ -1196,21 +1196,22 @@ extension Collection {
     var i = makeIterator()
     return i.next()
   }
-// TODO: swift-3-indexing-model - uncomment and replace above ready (or should we still use the iterator one?)
+  
+  // TODO: swift-3-indexing-model - uncomment and replace above ready (or should we still use the iterator one?)
   /// Returns the first element of `self`, or `nil` if `self` is empty.
   ///
   /// - Complexity: O(1)
   //  public var first: Iterator.Element? {
   //    return isEmpty ? nil : self[startIndex]
   //  }
 
-// TODO: swift-3-indexing-model - review the following
   /// A value less than or equal to the number of elements in the collection.
   ///
   /// - Complexity: O(1) if the collection conforms to
   ///   `RandomAccessCollection`; otherwise, O(*n*), where *n* is the length
   ///   of the collection.
   public var underestimatedCount: Int {
+    // TODO: swift-3-indexing-model - review the following
     return numericCast(count)
   }
 
@@ -1223,7 +1224,7 @@ extension Collection {
     return distance(from: startIndex, to: endIndex)
   }
 
-// TODO: swift-3-indexing-model - rename the following to _customIndexOfEquatable(element)?
+  // TODO: swift-3-indexing-model - rename the following to _customIndexOfEquatable(element)?
   /// Customization point for `Collection.index(of:)`.
   ///
   /// Define this method if the collection can find an element in less than
@@ -1245,7 +1246,6 @@ extension Collection {
 //===----------------------------------------------------------------------===//
 
 extension Collection {
-// TODO: swift-3-indexing-model - review the following
   /// Returns an array containing the results of mapping the given closure
   /// over the sequence's elements.
   ///
@@ -1266,6 +1266,7 @@ extension Collection {
   public func map<T>(
     _ transform: @noescape (Iterator.Element) throws -> T
   ) rethrows -> [T] {
+    // TODO: swift-3-indexing-model - review the following
     let count: Int = numericCast(self.count)
     if count == 0 {
       return []
@@ -1470,10 +1471,12 @@ extension Collection {
     return prefix(upTo: index(after: position))
   }
 
-  // TODO: swift-3-indexing-model - review the following
-  /// Returns the longest possible subsequences of the sequence, in order, that
-  /// don't contain elements satisfying the given predicate. Elements that are
-  /// used to split the sequence are not returned as part of any subsequence.
+  /// Returns the longest possible subsequences of the collection, in order,
+  /// that don't contain elements satisfying the given predicate.
+  ///
+  /// The resulting array consists of at most `maxSplits + 1` subsequences.
+  /// Elements that are used to split the sequence are not returned as part of
+  /// any subsequence.
   ///
   /// The following examples show the effects of the `maxSplits` and
   /// `omittingEmptySubsequences` parameters when splitting a string using a
@@ -1483,7 +1486,7 @@ extension Collection {
   ///     let line = "BLANCHE:   I don't want realism. I want magic!"
   ///     print(line.characters.split(isSeparator: { $0 == " " })
   ///                          .map(String.init))
-  ///     // Prints "["BLANCHE:", "I", "don't", "want", "realism.", "I", "want", "magic!"]"
+  ///     // Prints "["BLANCHE:", "I", "don\'t", "want", "realism.", "I", "want", "magic!"]"
   ///
   /// The second example passes `1` for the `maxSplits` parameter, so the
   /// original string is split just once, into two new strings.
@@ -1501,24 +1504,28 @@ extension Collection {
   ///     // Prints "["BLANCHE:", "", "", "I", "don\'t", "want", "realism.", "I", "want", "magic!"]"
   ///
   /// - Parameters:
-  ///   - maxSplits: The maximum number of times to split the sequence, or one
-  ///     less than the number of subsequences to return. If `maxSplits + 1`
-  ///     subsequences are returned, the last one is a suffix of the original
-  ///     sequence containing the remaining elements. `maxSplits` must be
-  ///     greater than or equal to zero.
+  ///   - maxSplits: The maximum number of times to split the collection, or
+  ///     one less than the number of subsequences to return. If
+  ///     `maxSplits + 1` subsequences are returned, the last one is a suffix
+  ///     of the original collection containing the remaining elements.
+  ///     `maxSplits` must be greater than or equal to zero. The default value
+  ///     is `Int.max`.
   ///   - omittingEmptySubsequences: If `false`, an empty subsequence is
   ///     returned in the result for each pair of consecutive elements
   ///     satisfying the `isSeparator` predicate and for each element at the
-  ///     start or end of the sequence satisfying the `isSeparator` predicate.
+  ///     start or end of the collection satisfying the `isSeparator`
+  ///     predicate. The default value is `true`.
   ///   - isSeparator: A closure that takes an element as an argument and
-  ///     returns a Boolean value indicating whether the sequence should be
+  ///     returns a Boolean value indicating whether the collection should be
   ///     split at that element.
-  /// - Returns: An array of subsequences, split from this sequence's elements.
+  /// - Returns: An array of subsequences, split from this collection's
+  ///   elements.
   public func split(
     maxSplits: Int = Int.max,
     omittingEmptySubsequences: Bool = true,
     isSeparator: @noescape (Iterator.Element) throws -> Bool
   ) rethrows -> [SubSequence] {
+    // TODO: swift-3-indexing-model - review the following
     _precondition(maxSplits >= 0, "Must take zero or more splits")
 
     var result: [SubSequence] = []
@@ -1560,64 +1567,67 @@ extension Collection {
   }
 }
 
-// TODO: swift-3-indexing-model - review the following
 extension Collection where Iterator.Element : Equatable {
-  /// Returns the longest possible subsequences of the sequence, in order, that
-  /// don't contain elements satisfying the given predicate. Elements that are
-  /// used to split the sequence are not returned as part of any subsequence.
+  /// Returns the longest possible subsequences of the collection, in order,
+  /// around elements equal to the given element.
+  ///
+  /// The resulting array consists of at most `maxSplits + 1` subsequences.
+  /// Elements that are used to split the collection are not returned as part
+  /// of any subsequence.
   ///
   /// The following examples show the effects of the `maxSplits` and
-  /// `omittingEmptySubsequences` parameters when splitting a string using a
-  /// closure that matches spaces. The first use of `split` returns each word
-  /// that was originally separated by one or more spaces.
+  /// `omittingEmptySubsequences` parameters when splitting a string at each
+  /// space character (" "). The first use of `split` returns each word that
+  /// was originally separated by one or more spaces.
   ///
   ///     let line = "BLANCHE:   I don't want realism. I want magic!"
-  ///     print(line.characters.split(isSeparator: { $0 == " " })
+  ///     print(line.characters.split(separator: " ")
   ///                          .map(String.init))
-  ///     // Prints "["BLANCHE:", "I", "don't", "want", "realism.", "I", "want", "magic!"]"
+  ///     // Prints "["BLANCHE:", "I", "don\'t", "want", "realism.", "I", "want", "magic!"]"
   ///
   /// The second example passes `1` for the `maxSplits` parameter, so the
   /// original string is split just once, into two new strings.
   ///
-  ///     print(line.characters.split(maxSplits: 1, isSeparator: { $0 == " " })
+  ///     print(line.characters.split(separator: " ", maxSplits: 1)
   ///                           .map(String.init))
   ///     // Prints "["BLANCHE:", "  I don\'t want realism. I want magic!"]"
   ///
   /// The final example passes `false` for the `omittingEmptySubsequences`
   /// parameter, so the returned array contains empty strings where spaces
   /// were repeated.
   ///
-  ///     print(line.characters.split(omittingEmptySubsequences: false, isSeparator: { $0 == " " })
+  ///     print(line.characters.split(separator: " ", omittingEmptySubsequences: false)
   ///                           .map(String.init))
   ///     // Prints "["BLANCHE:", "", "", "I", "don\'t", "want", "realism.", "I", "want", "magic!"]"
   ///
   /// - Parameters:
-  ///   - maxSplits: The maximum number of times to split the sequence, or one
-  ///     less than the number of subsequences to return. If `maxSplits + 1`
-  ///     subsequences are returned, the last one is a suffix of the original
-  ///     sequence containing the remaining elements. `maxSplits` must be
-  ///     greater than or equal to zero.
+  ///   - separator: The element that should be split upon.
+  ///   - maxSplits: The maximum number of times to split the collection, or
+  ///     one less than the number of subsequences to return. If
+  ///     `maxSplits + 1` subsequences are returned, the last one is a suffix
+  ///     of the original collection containing the remaining elements.
+  ///     `maxSplits` must be greater than or equal to zero. The default value
+  ///     is `Int.max`.
   ///   - omittingEmptySubsequences: If `false`, an empty subsequence is
-  ///     returned in the result for each pair of consecutive elements
-  ///     satisfying the `isSeparator` predicate and for each element at the
-  ///     start or end of the sequence satisfying the `isSeparator` predicate.
-  ///   - isSeparator: A closure that takes an element as an argument and
-  ///     returns a Boolean value indicating whether the sequence should be
-  ///     split at that element.
-  /// - Returns: An array of subsequences, split from this sequence's elements.
+  ///     returned in the result for each consecutive pair of `separator`
+  ///     elements in the collection and for each instance of `separator` at
+  ///     the start or end of the collection. If `true`, only nonempty
+  ///     subsequences are returned. The default value is `true`.
+  /// - Returns: An array of subsequences, split from this collection's
+  ///   elements.
   public func split(
     separator: Iterator.Element,
     maxSplits: Int = Int.max,
     omittingEmptySubsequences: Bool = true
   ) -> [SubSequence] {
-  return split(
-    maxSplits: maxSplits,
-    omittingEmptySubsequences: omittingEmptySubsequences,
-    isSeparator: { $0 == separator })
+    // TODO: swift-3-indexing-model - review the following
+    return split(
+      maxSplits: maxSplits,
+      omittingEmptySubsequences: omittingEmptySubsequences,
+      isSeparator: { $0 == separator })
   }
 }
 
-// TODO: swift-3-indexing-model - review the following
 extension Collection where SubSequence == Self {
   /// Removes and returns the first element of the collection.
   ///
@@ -1629,6 +1639,7 @@ extension Collection where SubSequence == Self {
   /// - SeeAlso: `popFirst()`
   @discardableResult
   public mutating func removeFirst() -> Iterator.Element {
+    // TODO: swift-3-indexing-model - review the following
     _precondition(!isEmpty, "can't remove items from an empty collection")
     let element = first!
     self = self[index(after: startIndex)..<endIndex]

stdlib/public/core/Sequence.swift

@@ -510,8 +510,11 @@ public protocol Sequence {
   func suffix(_ maxLength: Int) -> SubSequence
 
   /// Returns the longest possible subsequences of the sequence, in order, that
-  /// don't contain elements satisfying the given predicate. Elements that are
-  /// used to split the sequence are not returned as part of any subsequence.
+  /// don't contain elements satisfying the given predicate.
+  ///
+  /// The resulting array consists of at most `maxSplits + 1` subsequences.
+  /// Elements that are used to split the sequence are not returned as part of
+  /// any subsequence.
   ///
   /// The following examples show the effects of the `maxSplits` and
   /// `omittingEmptySubsequences` parameters when splitting a string using a
@@ -521,7 +524,7 @@ public protocol Sequence {
   ///     let line = "BLANCHE:   I don't want realism. I want magic!"
   ///     print(line.characters.split(isSeparator: { $0 == " " })
   ///                          .map(String.init))
-  ///     // Prints "["BLANCHE:", "I", "don't", "want", "realism.", "I", "want", "magic!"]"
+  ///     // Prints "["BLANCHE:", "I", "don\'t", "want", "realism.", "I", "want", "magic!"]"
   ///
   /// The second example passes `1` for the `maxSplits` parameter, so the
   /// original string is split just once, into two new strings.
@@ -822,7 +825,7 @@ extension Sequence {
   ///     let line = "BLANCHE:   I don't want realism. I want magic!"
   ///     print(line.characters.split(isSeparator: { $0 == " " })
   ///                          .map(String.init))
-  ///     // Prints "["BLANCHE:", "I", "don't", "want", "realism.", "I", "want", "magic!"]"
+  ///     // Prints "["BLANCHE:", "I", "don\'t", "want", "realism.", "I", "want", "magic!"]"
   ///
   /// The second example passes `1` for the `maxSplits` parameter, so the
   /// original string is split just once, into two new strings.
@@ -988,8 +991,11 @@ extension Sequence {
 
 extension Sequence where Iterator.Element : Equatable {
   /// Returns the longest possible subsequences of the sequence, in order,
-  /// around elements equal to the given element. Elements that are used to
-  /// split the sequence are not returned as part of any subsequence.
+  /// around elements equal to the given element.
+  ///
+  /// The resulting array consists of at most `maxSplits + 1` subsequences.
+  /// Elements that are used to split the sequence are not returned as part of
+  /// any subsequence.
   ///
   /// The following examples show the effects of the `maxSplits` and
   /// `omittingEmptySubsequences` parameters when splitting a string at each
@@ -999,7 +1005,7 @@ extension Sequence where Iterator.Element : Equatable {
   ///     let line = "BLANCHE:   I don't want realism. I want magic!"
   ///     print(line.characters.split(separator: " ")
   ///                          .map(String.init))
-  ///     // Prints "["BLANCHE:", "I", "don't", "want", "realism.", "I", "want", "magic!"]"
+  ///     // Prints "["BLANCHE:", "I", "don\'t", "want", "realism.", "I", "want", "magic!"]"
   ///
   /// The second example passes `1` for the `maxSplits` parameter, so the
   /// original string is split just once, into two new strings.