[stdlib] Propagate RangeReplaceableCollectionType docs

240 undocumented public non-operator APIs remain in core

Swift SVN r22235

stdlib/core/StringUnicodeScalarView.swift

@@ -211,40 +211,70 @@ extension String.UnicodeScalarView : ExtensibleCollectionType {
 
 extension String.UnicodeScalarView : RangeReplaceableCollectionType {
 
-  /// Replace the given `subRange` of elements with `newValues`.
+  /// Replace the given `subRange` of elements with `newElements`.
+  ///
+  /// Invalidates all indices with respect to `self`.
+  ///
   /// Complexity: O(\ `countElements(subRange)`\ ) if `subRange.endIndex
-  /// == self.endIndex` and `isEmpty(newValues)`\ , O(N) otherwise.
+  /// == self.endIndex` and `isEmpty(newElements)`\ , O(N) otherwise.
   public mutating func replaceRange<
     C: CollectionType where C.Generator.Element == UnicodeScalar
   >(
-    subRange: Range<Index>, with newValues: C
+    subRange: Range<Index>, with newElements: C
   ) {
     _core.replaceRange(
       subRange.startIndex._position
       ..< subRange.endIndex._position,
       with:
-        _lazyConcatenate(lazy(newValues).map { $0.utf16 })
+        _lazyConcatenate(lazy(newElements).map { $0.utf16 })
     )
   }
 
+  /// Insert `newElement` at index `i`.
+  ///
+  /// Invalidates all indices with respect to `self`.
+  ///
+  /// Complexity: O(\ `countElements(self)`\ ).
   public mutating func insert(newElement: UnicodeScalar, atIndex i: Index) {
     Swift.insert(&self, newElement, atIndex: i)
   }
   
+  /// Insert `newElements` at index `i`
+  ///
+  /// Invalidates all indices with respect to `self`.
+  ///
+  /// Complexity: O(\ `countElements(self) + countElements(newElements)`\ ).
   public mutating func splice<
     S : CollectionType where S.Generator.Element == UnicodeScalar
-  >(newValues: S, atIndex i: Index) {
-    Swift.splice(&self, newValues, atIndex: i)
+  >(newElements: S, atIndex i: Index) {
+    Swift.splice(&self, newElements, atIndex: i)
   }
 
+  /// Remove the and return element at index `i`
+  ///
+  /// Invalidates all indices with respect to `self`.
+  ///
+  /// Complexity: O(\ `countElements(self)`\ ).
   public mutating func removeAtIndex(i: Index) -> UnicodeScalar {
     return Swift.removeAtIndex(&self, i)
   }
   
+  /// Remove the indicated `subRange` of elements
+  ///
+  /// Invalidates all indices with respect to `self`.
+  ///
+  /// Complexity: O(\ `countElements(self)`\ ).
   public mutating func removeRange(subRange: Range<Index>) {
     Swift.removeRange(&self, subRange)
   }
 
+  /// Remove all elements.
+  ///
+  /// Invalidates all indices with respect to `self`.
+  ///
+  /// :param: `keepCapacity`, if `true`, prevents the release of
+  ////   allocated storage, which can be a useful optimization
+  ///    when `self` is going to be grown again.
   public mutating func removeAll(keepCapacity: Bool = false) {
     Swift.removeAll(&self, keepCapacity: keepCapacity)
   }