Improve comments in String.swift

Author: gribozavr

Diff for: stdlib/public/core/String.swift

@@ -12,6 +12,9 @@
 
 import SwiftShims
 
+// FIXME: complexity documentation for most of methods on String is ought to be
+// qualified with "amortized" at least, as Characters are variable-length.
+
 /// An arbitrary Unicode string value.
 ///
 /// Unicode-Correct
@@ -567,7 +570,7 @@ public func < (lhs: String.Index, rhs: String.Index) -> Bool {
 }
 
 extension String {
-  /// Access the characters in `bounds`.
+  /// Return the characters within the given `bounds`.
   ///
   /// - Complexity: O(1) unless bridging from Objective-C requires an
   ///   O(N) conversion.
@@ -654,7 +657,8 @@ extension Sequence where Iterator.Element == String {
 }
 
 extension String {
-  /// Replace the elements in `bounds` with `newElements`.
+  /// Replace the characters within `bounds` with the elements of
+  /// `replacement`.
   ///
   /// Invalidates all indices with respect to `self`.
   ///
@@ -670,7 +674,7 @@ extension String {
     }
   }
 
-  /// Replace the elements in `bounds` with `newElements`.
+  /// Replace the text in `bounds` with `replacement`.
   ///
   /// Invalidates all indices with respect to `self`.
   ///
@@ -682,7 +686,7 @@ extension String {
     replaceSubrange(bounds, with: newElements.characters)
   }
 
-  /// Insert `newElement` at index `i`.
+  /// Insert `newElement` at position `i`.
   ///
   /// Invalidates all indices with respect to `self`.
   ///
@@ -693,7 +697,7 @@ extension String {
     }
   }
 
-  /// Insert `newElements` at index `i`.
+  /// Insert `newElements` at position `i`.
   ///
   /// Invalidates all indices with respect to `self`.
   ///
@@ -706,7 +710,7 @@ extension String {
     }
   }
 
-  /// Remove and return the element at index `i`.
+  /// Remove and return the `Character` at position `i`.
   ///
   /// Invalidates all indices with respect to `self`.
   ///
@@ -728,7 +732,7 @@ extension String {
     }
   }
 
-  /// Remove all characters.
+  /// Replace `self` with the empty string.
   ///
   /// Invalidates all indices with respect to `self`.
   ///
@@ -823,6 +827,9 @@ extension String {
     }
   }
 
+  /// Return `self` converted to lower case.
+  ///
+  /// - Complexity: O(n)
   public var lowercaseString: String {
     if self._core.isASCII {
       let length = self._core.count
@@ -861,6 +868,9 @@ extension String {
 #endif
   }
 
+  /// Return `self` converted to upper case.
+  ///
+  /// - Complexity: O(n)
   public var uppercaseString: String {
     if self._core.isASCII {
       let length = self._core.count

Diff for: stdlib/public/core/StringCharacterView.swift

@@ -266,7 +266,7 @@ extension String.CharacterView : RangeReplaceableCollection {
     self.init("")
   }
 
-  /// Replace the elements in `bounds` with `newElements`.
+  /// Replace the characters within `bounds` with `newElements`.
   ///
   /// Invalidates all indices with respect to `self`.
   ///

Diff for: stdlib/public/core/StringUTF16.swift

@@ -99,8 +99,7 @@ extension String {
     }
 #endif
 
-    /// Access the elements delimited by the given half-open range of
-    /// indices.
+    /// Get the contiguous subrange of elements enclosed by `bounds`.
     ///
     /// - Complexity: O(1) unless bridging from Objective-C requires an
     ///   O(N) conversion.
@@ -139,9 +138,9 @@ extension String {
       return "StringUTF16(\(self.description.debugDescription))"
     }
 
-    var _offset: Int
-    var _length: Int
-    let _core: _StringCore
+    internal var _offset: Int
+    internal var _length: Int
+    internal let _core: _StringCore
   }
 
   /// A UTF-16 encoding of `self`.
@@ -207,7 +206,6 @@ public func < (
 // We can do some things more efficiently, even if we don't promise to
 // by conforming to RandomAccessIndex.
 
-/// Do not use this operator directly; call distance(start, end) instead.
 extension String.UTF16View.Index {
   @warn_unused_result
   public func distanceTo(end: String.UTF16View.Index)

Diff for: stdlib/public/core/StringUTF8.swift

@@ -221,8 +221,7 @@ extension String {
       return result
     }
 
-    /// Access the elements delimited by the given half-open range of
-    /// indices.
+    /// Access the contiguous subrange of elements enclosed by `bounds`.
     ///
     /// - Complexity: O(1) unless bridging from Objective-C requires an
     ///   O(N) conversion.

Diff for: stdlib/public/core/StringUnicodeScalarView.swift

@@ -129,8 +129,7 @@ extension String {
       }
     }
 
-    /// Access the elements delimited by the given half-open range of
-    /// indices.
+    /// Access the contiguous subrange of elements enclosed by `bounds`.
     ///
     /// - Complexity: O(1) unless bridging from Objective-C requires an
     ///   O(N) conversion.