[stdlib] Documentation revisions

- Various edits
- Standardized complexity formatting

Author: natecook1000

stdlib/public/core/ArrayBuffer.swift

@@ -112,7 +112,7 @@ extension _ArrayBuffer {
 
   /// Convert to an NSArray.
   ///
-  /// O(1) if the element type is bridged verbatim, O(N) otherwise.
+  /// O(1) if the element type is bridged verbatim, O(*n*) otherwise.
   public func _asCocoaArray() -> _NSArrayCore {
     return _fastPath(_isNative) ? _native._asCocoaArray() : _nonNative
   }

stdlib/public/core/ArrayType.swift

@@ -61,7 +61,7 @@ protocol _ArrayProtocol
   ///
   /// - returns: The removed element.
   ///
-  /// - Complexity: Worst case O(N).
+  /// - Complexity: Worst case O(*n*).
   ///
   /// - Precondition: `count > index`.
   @discardableResult

stdlib/public/core/Arrays.swift.gyb

@@ -169,8 +169,8 @@ if True:
 ///
 /// Arrays are one of the most commonly used data types in an app. You use
 /// arrays to organize your app's data. Specifically, you use the `Array` type
-/// to hold elements of a single type, the array's `Element` type. An array's
-/// elements can be anything from an integer to a string to a class.
+/// to hold elements of a single type, the array's `Element` type. An array
+/// can store any kind of elements---from integers to strings to classes.
 ///
 /// Swift makes it easy to create arrays in your code using an array literal:
 /// simply surround a comma separated list of values with square brackets.
@@ -261,8 +261,8 @@ if True:
 ///     var students = ["Ben", "Ivy", "Jordell"]
 ///
 /// To add single elements to the end of an array, use the `append(_:)` method.
-/// Add multiple elements at once by passing another array or a sequence of
-/// any kind to the `append(contentsOf:)` method.
+/// Add multiple elements at the same time by passing another array or a
+/// sequence of any kind to the `append(contentsOf:)` method.
 ///
 ///     students.append("Maxime")
 ///     students.append(contentsOf: ["Shakia", "William"])
@@ -271,8 +271,8 @@ if True:
 /// You can add new elements in the middle of an array by using the
 /// `insert(_:at:)` method for single elements and by using
 /// `insert(contentsOf:at:)` to insert multiple elements from another
-/// collection or array literal. The elements at that index and later are
-/// shifted back to make room.
+/// collection or array literal. The elements at that index and later indices
+/// are shifted back to make room.
 ///
 ///     students.insert("Liam", at: 3)
 ///     // ["Ben", "Ivy", "Jordell", "Liam", "Maxime", "Shakia", "William"]
@@ -288,8 +288,8 @@ if True:
 ///     students.removeLast()
 ///     // ["Ivy", "Jordell", "Liam", "Maxime", "Shakia"]
 ///
-/// You can replace an existing element with a new value by assigning to the
-/// subscript.
+/// You can replace an existing element with a new value by assigning the new
+/// value to the subscript.
 ///
 ///     if let i = students.index(of: "Maxime") {
 ///         students[i] = "Max"
@@ -423,7 +423,7 @@ if True:
 ///
 /// Bridging from `Array` to `NSArray` takes O(1) time and O(1) space if the
 /// array's elements are already instances of a class or an `@objc` protocol;
-/// otherwise, it takes O(n) time and space.
+/// otherwise, it takes O(*n*) time and space.
 ///
 /// Bridging from `NSArray` to `Array` first calls the `copy(with:)`
 /// (`- copyWithZone:` in Objective-C) method on the array to get an immutable

stdlib/public/core/Collection.swift

@@ -528,7 +528,7 @@ public struct IndexingIterator<
 /// able to calculate its `count` property in O(1) time. Conversely, because a
 /// forward or bidirectional collection must traverse the entire collection to
 /// count the number of contained elements, accessing its `count` property is
-/// an O(N) operation.
+/// an O(*n*) operation.
 public protocol Collection : Indexable, Sequence {
   /// A type that can represent the number of steps between a pair of
   /// indices.
@@ -751,7 +751,7 @@ public protocol Collection : Indexable, Sequence {
   /// or `Optional(nil)` if an element was determined to be missing;
   /// otherwise, `nil`.
   ///
-  /// - Complexity: O(N).
+  /// - Complexity: O(*n*)
   func _customIndexOfEquatableElement(_ element: Iterator.Element) -> Index??
 
   /// The first element of the collection.
@@ -1209,7 +1209,7 @@ extension Collection {
   /// Customization point for `Collection.index(of:)`.
   ///
   /// Define this method if the collection can find an element in less than
-  /// O(N) by exploiting collection-specific knowledge.
+  /// O(*n*) by exploiting collection-specific knowledge.
   ///
   /// - Returns: `nil` if a linear search should be attempted instead,
   ///   `Optional(nil)` if the element was not found, or

stdlib/public/core/ContiguousArrayBuffer.swift

@@ -467,7 +467,7 @@ struct _ContiguousArrayBuffer<Element> : _ArrayBufferProtocol {
   ///
   /// - Precondition: `U` is a class or `@objc` existential.
   ///
-  /// - Complexity: O(N).
+  /// - Complexity: O(*n*)
   func storesOnlyElementsOfType<U>(
     _: U.Type
   ) -> Bool {

stdlib/public/core/Equatable.swift

@@ -191,7 +191,7 @@ public func != <T : Equatable>(lhs: T, rhs: T) -> Bool {
 /// same value. For value equality, see the equal-to operator (`==`) and the
 /// `Equatable` protocol.
 ///
-/// The following example defines an `IntegerRef` type; an integer type with
+/// The following example defines an `IntegerRef` type, an integer type with
 /// reference semantics.
 ///
 ///     class IntegerRef: Equatable {
@@ -218,7 +218,7 @@ public func != <T : Equatable>(lhs: T, rhs: T) -> Bool {
 ///     // Prints "true"
 ///
 /// The identical-to operator (`===`) returns `false` when comparing two
-/// references to different objects instances, even if the two instances have
+/// references to different object instances, even if the two instances have
 /// the same value.
 ///
 ///     let c = IntegerRef(10)

stdlib/public/core/ExistentialCollection.swift.gyb

@@ -928,7 +928,7 @@ public struct ${Self}<Element>
 
   /// The number of elements.
   ///
-  /// - Complexity: ${'O(1)' if Traversal == 'RandomAccess' else 'O(N)'}
+  /// - Complexity: ${'O(1)' if Traversal == 'RandomAccess' else 'O(*n*)'}
   public var count: IntMax {
     return _box._count
   }

stdlib/public/core/Filter.swift.gyb

@@ -202,7 +202,7 @@ public struct ${Self}<
   ///
   /// In an empty collection, `startIndex == endIndex`.
   ///
-  /// - Complexity: O(N), where N is the ratio between unfiltered and
+  /// - Complexity: O(*n*), where *n* is the ratio between unfiltered and
   ///   filtered collection counts.
   public var startIndex: Index {
     var index = _base.startIndex

stdlib/public/core/HashedCollections.swift.gyb

@@ -421,7 +421,7 @@ internal struct _UnmanagedAnyObjectArray {
 /// set's `Element` type is neither a class nor an `@objc` protocol, any
 /// required bridging of elements occurs at the first access of each element,
 /// so the first operation that uses the contents of the set (for example, a
-/// membership test) can take O(N).
+/// membership test) can take O(*n*).
 ///
 /// Bridging from `NSSet` to `Set` first calls the `copy(with:)` method
 /// (`- copyWithZone:` in Objective-C) on the set to get an immutable copy and
@@ -996,7 +996,7 @@ public struct Set<Element : Hashable> :
   ///
   /// In the following example, the `bothNeighborsAndEmployees` set is made up
   /// of the elements that are in *both* the `employees` and `neighbors` sets.
-  /// Elements that are only in one or the other are left out of the result of
+  /// Elements that are in only one or the other are left out of the result of
   /// the intersection.
   ///
   ///     let employees: Set = ["Alicia", "Bethany", "Chris", "Diana", "Eric"]
@@ -1748,7 +1748,7 @@ public struct Dictionary<Key : Hashable, Value> :
   ///   the dictionary; otherwise, `nil`.
   @inline(__always)
   public func index(forKey key: Key) -> Index? {
-    // Complexity: amortized O(1) for native storage, O(N) when wrapping an
+    // Complexity: amortized O(1) for native storage, O(*n*) when wrapping an
     // NSDictionary.
     return _variantStorage.index(forKey: key)
   }
@@ -5227,7 +5227,7 @@ extension Set {
   ///
   /// In the following example, the `bothNeighborsAndEmployees` set is made up
   /// of the elements that are in *both* the `employees` and `neighbors` sets.
-  /// Elements that are only in one or the other are left out of the result of
+  /// Elements that are in only one or the other are left out of the result of
   /// the intersection.
   ///
   ///     let employees: Set = ["Alicia", "Bethany", "Chris", "Diana", "Eric"]

stdlib/public/core/LazyCollection.swift.gyb

@@ -86,7 +86,7 @@ extension ${Self} : Sequence {
   /// Returns a value less than or equal to the number of elements in
   /// `self`, **nondestructively**.
   ///
-  /// - Complexity: O(N).
+  /// - Complexity: O(*n*)
   public var underestimatedCount: Int { return _base.underestimatedCount }
 
   public func _copyToContiguousArray()
@@ -158,7 +158,7 @@ extension ${Self} : ${TraversalCollection} {
   /// Returns the number of elements.
   ///
   /// - Complexity: O(1) if `Self` conforms to `RandomAccessCollection`;
-  ///   O(N) otherwise.
+  ///   O(*n*) otherwise.
   public var count: Base.IndexDistance {
     return _base.count
   }
@@ -169,7 +169,7 @@ extension ${Self} : ${TraversalCollection} {
   /// Returns `Optional(Optional(index))` if an element was found;
   /// `nil` otherwise.
   ///
-  /// - Complexity: O(N).
+  /// - Complexity: O(*n*)
   public func _customIndexOfEquatableElement(
     _ element: Base.Iterator.Element
   ) -> Index?? {