[stdlib] Propagate GeneratorType docs to models

Swift SVN r22208

stdlib/core/Algorithm.swift

@@ -215,6 +215,7 @@ public func startsWith<
 public struct EnumerateGenerator<
   Base: GeneratorType
 > : GeneratorType, SequenceType {
+  /// The type of element returned by `next()`.
   public typealias Element = (index: Int, element: Base.Element)
   var base: Base
   var count: Int
@@ -225,8 +226,10 @@ public struct EnumerateGenerator<
     count = 0
   }
 
-  /// If all elements are exhausted, return `nil`.  Otherwise, advance
-  /// to the next element and return it.
+  /// Advance to the next element and return it, or `nil` if no next
+  /// element exists.
+  ///
+  /// Requires: no preceding call to `self.next()` has returned `nil`.
   public mutating func next() -> Element? {
     var b = base.next()
     if b == nil { return .None }

stdlib/core/Collection.swift

@@ -175,8 +175,10 @@ public struct IndexingGenerator<
     return self
   }
 
-  /// Return the next element of the underlying collection, or `nil`
-  /// if no next element exists.
+  /// Advance to the next element and return it, or `nil` if no next
+  /// element exists.
+  ///
+  /// Requires: no preceding call to `self.next()` has returned `nil`.
   public mutating func next() -> C._Element? {
     return _position == _elements.endIndex
     ? .None : .Some(_elements[_position++])
@@ -206,8 +208,13 @@ public struct PermutationGenerator<
   var seq : C
   var indices : Indices.Generator
 
+  /// The type of element returned by `next()`.
   public typealias Element = C.Generator.Element
 
+  /// Advance to the next element and return it, or `nil` if no next
+  /// element exists.
+  ///
+  /// Requires: no preceding call to `self.next()` has returned `nil`.
   public mutating func next() -> Element? {
     var result = indices.next()
     return result != nil ? seq[result!] : .None

stdlib/core/CollectionOfOne.swift

@@ -20,6 +20,12 @@ public struct GeneratorOfOne<T> : GeneratorType, SequenceType {
     return self
   }
   
+  /// Advance to the next element and return it, or `nil` if no next
+  /// element exists.
+  ///
+  /// Requires: `next()` has not been applied to a copy of `self`
+  /// since the copy was made, and no preceding call to `self.next()`
+  /// has returned `nil`.
   public mutating func next() -> T? {
     let result = elements
     elements = .None

stdlib/core/CompilerProtocols.swift

@@ -39,7 +39,7 @@ public protocol BooleanType {
 /// Also, the generators must be obtained by distinct calls to the
 /// *sequence's* `generate()` method, rather than by copying.
 public protocol GeneratorType { 
-  /// The type of element to be bound to the loop variable.
+  /// The type of element generated by `self`.
   typealias Element
 
   /// Advance to the next element and return it, or `nil` if no next
@@ -170,6 +170,12 @@ public struct GeneratorSequence<
     _base = base
   }
   
+  /// Advance to the next element and return it, or `nil` if no next
+  /// element exists.
+  ///
+  /// Requires: `next()` has not been applied to a copy of `self`
+  /// since the copy was made, and no preceding call to `self.next()`
+  /// has returned `nil`.
   public mutating func next() -> G.Element? {
     return _base.next()
   }

stdlib/core/Concatenate.swift.gyb

@@ -23,8 +23,12 @@ struct _ConcatenateSequenceGenerator<
     self._outer = outer
   }
 
-  /// Return the next element in the sequence, or `nil`` if none exists,
-  /// in either case advancing the generator.
+  /// Advance to the next element and return it, or `nil` if no next
+  /// element exists.
+  ///
+  /// Requires: `next()` has not been applied to a copy of `self`
+  /// since the copy was made, and no preceding call to `self.next()`
+  /// has returned `nil`.
   mutating func next() -> Outer.Element.Generator.Element? {
     do {
       if _fastPath(_inner != nil) {

stdlib/core/Dictionary.swift

@@ -1883,6 +1883,10 @@ public struct DictionaryGenerator<Key : Hashable, Value> : GeneratorType {
     }
   }
 
+  /// Advance to the next element and return it, or `nil` if no next
+  /// element exists.
+  ///
+  /// Requires: no preceding call to `self.next()` has returned `nil`.
   public mutating func next() -> (Key, Value)? {
     if _fastPath(_guaranteedNative) {
       return _nativeNext()

stdlib/core/EmptyCollection.swift

@@ -22,6 +22,7 @@ public struct EmptyGenerator<T> : GeneratorType, SequenceType {
     return self
   }
   
+  /// Return `nil`, indicating that there are no more elements.
   public mutating func next() -> T? {
     return nil
   }

stdlib/core/Existential.swift

@@ -26,6 +26,12 @@ public struct GeneratorOf<T> : GeneratorType, SequenceType {
     self._next = { self_.next() }
   }
   
+  /// Advance to the next element and return it, or `nil` if no next
+  /// element exists.
+  ///
+  /// Requires: `next()` has not been applied to a copy of `self`
+  /// since the copy was made, and no preceding call to `self.next()`
+  /// has returned `nil`.
   public mutating func next() -> T? {
     return _next()
   }

stdlib/core/Filter.swift.gyb

@@ -15,6 +15,12 @@
 public struct FilterGenerator<
   Base: GeneratorType
 > : GeneratorType, SequenceType {
+  /// Advance to the next element and return it, or `nil` if no next
+  /// element exists.
+  ///
+  /// Requires: `next()` has not been applied to a copy of `self`
+  /// since the copy was made, and no preceding call to `self.next()`
+  /// has returned `nil`.
   public mutating func next() -> Base.Element? {
     var n: Base.Element?
     for/*ever*/;; {

stdlib/core/Map.swift.gyb

@@ -16,6 +16,12 @@
 public struct MapSequenceGenerator<
   Base: GeneratorType, T
 >: GeneratorType, SequenceType {
+  /// Advance to the next element and return it, or `nil` if no next
+  /// element exists.
+  ///
+  /// Requires: `next()` has not been applied to a copy of `self`
+  /// since the copy was made, and no preceding call to `self.next()`
+  /// has returned `nil`.
   public mutating func next() -> T? {
     let x = _base.next()
     if x != nil {

stdlib/core/Range.swift

@@ -13,6 +13,7 @@
 public struct RangeGenerator<
   T: ForwardIndexType
 > : GeneratorType, SequenceType {
+  /// The type of element returned by `next()`.
   public typealias Element = T
 
   @transparent public
@@ -21,6 +22,8 @@ public struct RangeGenerator<
     self.endIndex = bounds.endIndex
   }
 
+  /// Advance to the next element and return it, or `nil` if no next
+  /// element exists.
   public mutating func next() -> Element? {
     if startIndex == endIndex {
       return .None

stdlib/core/Stride.swift

@@ -85,6 +85,8 @@ public struct StrideToGenerator<T: Strideable> : GeneratorType {
   let end: T
   let stride: T.Stride
 
+  /// Advance to the next element and return it, or `nil` if no next
+  /// element exists.
   public mutating func next() -> T? {
     if stride > 0 ? current >= end : current <= end {
       return nil
@@ -130,6 +132,8 @@ public struct StrideThroughGenerator<T: Strideable> : GeneratorType {
   let stride: T.Stride
   var done: Bool = false
   
+  /// Advance to the next element and return it, or `nil` if no next
+  /// element exists.
   public mutating func next() -> T? {
     if done {
       return nil

stdlib/core/StringUnicodeScalarView.swift

@@ -125,6 +125,11 @@ extension String {
         self._base = _base
       }
 
+      /// Advance to the next element and return it, or `nil` if no next
+      /// element exists.
+      ///
+      /// Requires: no preceding call to `self.next()` has returned
+      /// `nil`.
       public mutating func next() -> UnicodeScalar? {
         switch _decoder.decode(&self._base) {
         case .Result(let us):

stdlib/core/UnsafeBufferPointer.swift.gyb

@@ -13,6 +13,8 @@
 /// A generator for the elements in the buffer referenced by
 /// `UnsafeBufferPointer` or `UnsafeMutableBufferPointer`
 public struct UnsafeBufferPointerGenerator<T>: GeneratorType, SequenceType {
+  /// Advance to the next element and return it, or `nil` if no next
+  /// element exists.
   public mutating func next() -> T? {
     return position == end ? nil : (position++).memory
   }

stdlib/core/Zip.swift

@@ -13,12 +13,19 @@
 public struct ZipGenerator2<
   E0 : GeneratorType, E1 : GeneratorType
 > : GeneratorType {
+  /// The type of element returned by `next()`.
   public typealias Element = (E0.Element,E1.Element)
 
   public init(_ e0: E0, _ e1: E1) {
     baseStreams = (e0,e1)
   }
 
+  /// Advance to the next element and return it, or `nil` if no next
+  /// element exists.
+  ///
+  /// Requires: `next()` has not been applied to a copy of `self`
+  /// since the copy was made, and no preceding call to `self.next()`
+  /// has returned `nil`.
   public mutating func next() -> Element? {
     var e0 = baseStreams.0.next()
     if e0 == nil { return .None }