Move post-nil guarantee to separate line for Iterators' next()

Author: PatrickPijnappel

stdlib/public/core/Algorithm.swift

@@ -85,7 +85,9 @@ public struct EnumeratedIterator<
   public typealias Element = (offset: Int, element: Base.Element)
 
   /// 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`.
+  /// exists.
+  ///
+  /// Once `nil` has been returned, all subsequent calls return `nil`.
   public mutating func next() -> Element? {
     guard let b = _base.next() else { return nil }
     defer { _count += 1 }

stdlib/public/core/Collection.swift

@@ -296,11 +296,11 @@ public struct IndexingIterator<
   }
 
   /// 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`.
+  /// exists.
   ///
   /// Repeatedly calling this method returns all the elements of the underlying
-  /// sequence in order. As soon as the sequence has run out of elements, the
-  /// `next()` method returns `nil`.
+  /// sequence in order.  As soon as the sequence has run out of elements, all
+  /// subsequent calls return `nil`.
   ///
   /// This example shows how an iterator can be used explicitly to emulate a
   /// `for`-`in` loop. First, retrieve a sequence's iterator, and then call

stdlib/public/core/CollectionOfOne.swift

@@ -20,7 +20,9 @@ public struct IteratorOverOne<Element> : IteratorProtocol, Sequence {
   }
 
   /// 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`.
+  /// exists.
+  ///
+  /// 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.

stdlib/public/core/ExistentialCollection.swift.gyb

@@ -75,7 +75,9 @@ public struct AnyIterator<Element> : IteratorProtocol {
   }
 
   /// 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`.
+  /// exists.
+  ///
+  /// Once `nil` has been returned, all subsequent calls return `nil`.
   public func next() -> Element? {
     return _box.next()
   }
@@ -97,7 +99,9 @@ internal struct _ClosureBasedIterator<Element> : IteratorProtocol {
 
 internal class _AnyIteratorBoxBase<Element> : IteratorProtocol {
   /// 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`.
+  /// exists.
+  ///
+  /// Once `nil` has been returned, all subsequent calls return `nil`.
   ///
   /// - Note: Subclasses must override this method.
   internal func next() -> Element? { _abstract() }

stdlib/public/core/Filter.swift.gyb

@@ -27,7 +27,9 @@ public struct LazyFilterIterator<
   Base : IteratorProtocol
 > : IteratorProtocol, Sequence {
   /// 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`.
+  /// exists.
+  ///
+  /// 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.

stdlib/public/core/Flatten.swift.gyb

@@ -36,7 +36,9 @@ public struct FlattenIterator<
   }
 
   /// 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`.
+  /// exists.
+  ///
+  /// 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.

stdlib/public/core/HashedCollections.swift.gyb

@@ -4574,7 +4574,9 @@ public struct ${Self}Iterator<${TypeParametersDecl}> : IteratorProtocol {
   }
 
   /// 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`.
+  /// exists.
+  ///
+  /// Once `nil` has been returned, all subsequent calls return `nil`.
   @inline(__always)
   public mutating func next() -> ${Sequence}? {
     if _fastPath(_guaranteedNative) {

stdlib/public/core/Join.swift

@@ -37,7 +37,9 @@ public struct JoinedIterator<
   }
 
   /// 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`.
+  /// exists.
+  ///
+  /// Once `nil` has been returned, all subsequent calls return `nil`.
   public mutating func next() -> Base.Element.Iterator.Element? {
     repeat {
       switch _state {

stdlib/public/core/Map.swift.gyb

@@ -25,7 +25,9 @@ public struct LazyMapIterator<
   Base : IteratorProtocol, Element
 > : IteratorProtocol, Sequence {
   /// 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`.
+  /// exists.
+  ///
+  /// 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.

stdlib/public/core/Sequence.swift

@@ -182,8 +182,8 @@ public protocol IteratorProtocol {
   /// exists.  Once `nil` has been returned, all subsequent calls return `nil`.
   ///
   /// Repeatedly calling this method returns, in order, all the elements of the
-  /// underlying sequence. After the sequence has run out of elements, the
-  /// `next()` method returns `nil`.
+  /// underlying sequence.  As soon as the sequence has run out of elements, all
+  /// subsequent calls return `nil`.
   ///
   /// You must not call this method if any other copy of this iterator has been
   /// advanced with a call to its `next()` method.
@@ -1179,7 +1179,9 @@ public struct IteratorSequence<
   }
 
   /// 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`.
+  /// exists.
+  ///
+  /// 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.