[stdlib] Propagate ForwardIndexType docs to models

200 undocumented public APIs remain in core

Swift SVN r22222

stdlib/core/Bit.swift

@@ -19,8 +19,9 @@
 public enum Bit : Int, RandomAccessIndexType, Reflectable {
   case Zero = 0, One = 1
 
-  /// Return the next consecutive value in a discrete sequence of
-  /// `Bit` values
+  /// Returns the next consecutive value after `self`.
+  ///
+  /// Requires: `self == .Zero`.
   public func successor() -> Bit {
     _precondition(self == .Zero, "Can't increment past one")
     return .One

stdlib/core/Concatenate.swift.gyb

@@ -145,7 +145,9 @@ struct ${Index}<
     return ${Index}(data, outer, nil)
   }
 
-  /// Return an index for the next position.
+  /// Returns the next consecutive value after `self`.
+  ///
+  /// Requires: the next value is representable.
   func successor() -> ${Index} {
     return ${Index}.adjustForward(_data, _outer, _inner!.successor())
   }

stdlib/core/Dictionary.swift

@@ -1521,6 +1521,9 @@ struct _NativeDictionaryIndex<Key : Hashable, Value> :
     return self
   }
 
+  /// Returns the next consecutive value after `self`.
+  ///
+  /// Requires: the next value is representable.
   func successor() -> NativeIndex {
     var i = offset + 1
     // FIXME: Can't write the simple code pending
@@ -1592,6 +1595,9 @@ struct _CocoaDictionaryIndex : BidirectionalIndexType, Comparable {
     return _CocoaDictionaryIndex(cocoaDictionary, allKeys, currentKeyIndex - 1)
   }
 
+  /// Returns the next consecutive value after `self`.
+  ///
+  /// Requires: the next value is representable.
   func successor() -> _CocoaDictionaryIndex {
     _precondition(
         currentKeyIndex < allKeys.value, "can not increment endIndex")
@@ -1687,6 +1693,9 @@ public struct DictionaryIndex<Key : Hashable, Value> :
     }
   }
 
+  /// Returns the next consecutive value after `self`.
+  ///
+  /// Requires: the next value is representable.
   public func successor() -> Index {
     if _fastPath(_guaranteedNative) {
       return ._Native(_nativeIndex.successor())

stdlib/core/Filter.swift.gyb

@@ -59,6 +59,9 @@ public struct FilterSequenceView<Base: SequenceType> : SequenceType {
 public struct FilterCollectionViewIndex<
   Base: CollectionType
 > : ForwardIndexType {
+  /// Returns the next consecutive value after `self`.
+  ///
+  /// Requires: the next value is representable.
   public func successor() -> FilterCollectionViewIndex {
     for nextPos in _pos.successor()..<_end {
       if _include(_base[nextPos]) {

stdlib/core/FixedPoint.swift.gyb

@@ -275,6 +275,9 @@ extension ${Self} : RandomAccessIndexType {
   // for details of how this works.
   typealias _DisabledRangeIndex = ${Self}
   
+  /// Returns the next consecutive value after `self`.
+  ///
+  /// Requires: the next value is representable.
   @transparent public
   func successor() -> ${Self} {
     return self &+ 1

stdlib/core/Reverse.swift.gyb

@@ -33,6 +33,9 @@ public struct ${Index}<I: ${IndexProtocol}> : ${IndexProtocol} {
 
   init(_ _base: I) { self._base = _base }
 
+  /// Returns the next consecutive value after `self`.
+  ///
+  /// Requires: the next value is representable.
   public func successor() -> ${Index} {
     return ${Index}(_base.predecessor())
   }

stdlib/core/String.swift

@@ -337,6 +337,9 @@ extension String : CollectionType {
       self._lengthUTF16 = _lengthUTF16
     }
 
+    /// Returns the next consecutive value after `self`.
+    ///
+    /// Requires: the next value is representable.
     public func successor() -> Index {
       _precondition(_base != _base._viewEndIndex, "can not increment endIndex")
       return Index(_endBase)

stdlib/core/StringUTF8.swift

@@ -93,6 +93,9 @@ extension String {
         _sanityCheck(_coreIndex <= _core.count)
       }
       
+      /// Returns the next consecutive value after `self`.
+      ///
+      /// Requires: the next value is representable.
       public func successor() -> Index {
         let newBuffer0 = (_buffer >> 8) | (
           0xFF << numericCast((sizeofValue(_buffer) &- 1) &* 8)

stdlib/core/StringUnicodeScalarView.swift

@@ -51,6 +51,9 @@ extension String {
         self._core = _core
       }
 
+      /// Returns the next consecutive value after `self`.
+      ///
+      /// Requires: the next value is representable.
       public func successor() -> Index {
         var scratch = _ScratchGenerator(_core, _position)
         var decoder = UTF16()

stdlib/core/UnsafePointer.swift.gyb

@@ -352,6 +352,9 @@ public struct ${Self}<T>
   public var hashValue: Int {
     return Int(Builtin.ptrtoint_Word(value))
   }
+  /// Returns the next consecutive value after `self`.
+  ///
+  /// Requires: the next value is representable.
   public func successor() -> ${Self} {
     return self + 1
   }

stdlib/unittest/LifetimeTracked.swift

@@ -30,6 +30,9 @@ public final class LifetimeTracked : ForwardIndexType, Printable {
     return value.description
   }
 
+  /// Returns the next consecutive value after `self`.
+  ///
+  /// Requires: the next value is representable.
   public func successor() -> LifetimeTracked {
     return LifetimeTracked(self.value.successor())
   }