[stdlib] Additional stdlib comment revisions

Author: natecook1000

stdlib/public/core/HashedCollections.swift.gyb

@@ -996,8 +996,8 @@ 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 in only one or the other are left out of the result of
-  /// the intersection.
+  /// Elements that are in either one or the other, but not both, are left out
+  /// of the result of the intersection.
   ///
   ///     let employees: Set = ["Alicia", "Bethany", "Chris", "Diana", "Eric"]
   ///     let neighbors = ["Bethany", "Eric", "Forlani", "Greta"]
@@ -5227,8 +5227,8 @@ 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 in only one or the other are left out of the result of
-  /// the intersection.
+  /// Elements that are in either one or the other, but not both, are left out
+  /// of the result of the intersection.
   ///
   ///     let employees: Set = ["Alicia", "Bethany", "Chris", "Diana", "Eric"]
   ///     let neighbors: Set = ["Bethany", "Eric", "Forlani", "Greta"]

stdlib/public/core/RangeReplaceableCollection.swift.gyb

@@ -100,7 +100,7 @@ public protocol RangeReplaceableIndexable : Indexable {
   /// Inserts a new element into the collection at the specified position.
   ///
   /// The new element is inserted before the element currently at the specified
-  /// index. If you pass the collection's `endIndex` property as the `index`
+  /// index. If you pass the collection's `endIndex` property as the `i`
   /// parameter, the new element is appended to the collection.
   ///
   ///     var numbers = [1, 2, 3, 4, 5]
@@ -115,7 +115,7 @@ public protocol RangeReplaceableIndexable : Indexable {
   ///
   /// - Parameters:
   ///   - newElement: The new element to insert into the collection.
-  ///   - i: The position at which to insert the new element. `index` must be a
+  ///   - i: The position at which to insert the new element. `i` must be a
   ///     valid index into the collection.
   ///
   /// - Complexity: O(*n*), where *n* is the length of the collection.
@@ -126,7 +126,7 @@ public protocol RangeReplaceableIndexable : Indexable {
   ///
   /// The new elements are inserted before the element currently at the
   /// specified index. If you pass the collection's `endIndex` property as the
-  /// `index` parameter, the new elements are appended to the collection.
+  /// `i` parameter, the new elements are appended to the collection.
   ///
   /// Here's an example of inserting a range of integers into an array of the
   /// same type:
@@ -141,8 +141,8 @@ public protocol RangeReplaceableIndexable : Indexable {
   ///
   /// - Parameters:
   ///   - newElements: The new elements to insert into the collection.
-  ///   - i: The position at which to insert the new elements. `index` must be
-  ///     a valid index of the collection.
+  ///   - i: The position at which to insert the new elements. `i` must be a
+  ///     valid index of the collection.
   ///
   /// - Complexity: O(*m*), where *m* is the combined length of the collection
   ///   and `newElements`. If `i` is equal to the collection's `endIndex`
@@ -166,9 +166,9 @@ public protocol RangeReplaceableIndexable : Indexable {
   /// Calling this method may invalidate any existing indices for use with this
   /// collection.
   ///
-  /// - Parameter i: The position of the element to remove. `index` must be
-  ///   a valid index of the collection that is not equal to the collection's
-  ///   end index.
+  /// - Parameter i: The position of the element to remove. `i` must be a valid
+  ///   index of the collection that is not equal to the collection's end
+  ///   index.
   /// - Returns: The removed element.
   ///
   /// - Complexity: O(*n*), where *n* is the length of the collection.
@@ -374,8 +374,7 @@ public protocol RangeReplaceableCollection
     where S.Iterator.Element == Iterator.Element
   */
 
-  /// Adds the elements of a sequence or collection to the end of this
-  /// collection.
+  /// Adds the elements of a sequence to the end of this collection.
   ///
   /// The collection being appended to allocates any additional necessary
   /// storage to hold the new elements.
@@ -397,10 +396,9 @@ public protocol RangeReplaceableCollection
 
   /// Inserts a new element into the collection at the specified position.
   ///
-  /// The new element is inserted before the element currently at the
-  /// specified index. If you pass the collection's `endIndex` property as
-  /// the `index` parameter, the new element is appended to the
-  /// collection.
+  /// The new element is inserted before the element currently at the specified
+  /// index. If you pass the collection's `endIndex` property as the `i`
+  /// parameter, the new element is appended to the collection.
   ///
   ///     var numbers = [1, 2, 3, 4, 5]
   ///     numbers.insert(100, at: 3)
@@ -413,8 +411,8 @@ public protocol RangeReplaceableCollection
   /// collection.
   ///
   /// - Parameter newElement: The new element to insert into the collection.
-  /// - Parameter i: The position at which to insert the new element.
-  ///   `index` must be a valid index into the collection.
+  /// - Parameter i: The position at which to insert the new element. `i` must
+  ///   be a valid index into the collection.
   ///
   /// - Complexity: O(*n*), where *n* is the length of the collection.
   mutating func insert(_ newElement: Iterator.Element, at i: Index)
@@ -424,7 +422,7 @@ public protocol RangeReplaceableCollection
   ///
   /// The new elements are inserted before the element currently at the
   /// specified index. If you pass the collection's `endIndex` property as the
-  /// `index` parameter, the new elements are appended to the collection.
+  /// `i` parameter, the new elements are appended to the collection.
   ///
   /// Here's an example of inserting a range of integers into an array of the
   /// same type:
@@ -438,8 +436,8 @@ public protocol RangeReplaceableCollection
   /// collection.
   ///
   /// - Parameter newElements: The new elements to insert into the collection.
-  /// - Parameter i: The position at which to insert the new elements. `index`
-  ///   must be a valid index of the collection.
+  /// - Parameter i: The position at which to insert the new elements. `i` must
+  ///   be a valid index of the collection.
   ///
   /// - Complexity: O(*m*), where *m* is the combined length of the collection
   ///   and `newElements`. If `i` is equal to the collection's `endIndex`
@@ -462,9 +460,9 @@ public protocol RangeReplaceableCollection
   /// Calling this method may invalidate any existing indices for use with this
   /// collection.
   ///
-  /// - Parameter i: The position of the element to remove. `index` must be
-  ///   a valid index of the collection that is not equal to the collection's
-  ///   end index.
+  /// - Parameter i: The position of the element to remove. `i` must be a valid
+  ///   index of the collection that is not equal to the collection's end
+  ///   index.
   /// - Returns: The removed element.
   ///
   /// - Complexity: O(*n*), where *n* is the length of the collection.
@@ -591,8 +589,7 @@ extension RangeReplaceableCollection {
     insert(newElement, at: endIndex)
   }
 
-  /// Adds the elements of a sequence or collection to the end of this
-  /// collection.
+  /// Adds the elements of a sequence to the end of this collection.
   ///
   /// The collection being appended to allocates any additional necessary
   /// storage to hold the new elements.
@@ -622,10 +619,9 @@ extension RangeReplaceableCollection {
 
   /// Inserts a new element into the collection at the specified position.
   ///
-  /// The new element is inserted before the element currently at the
-  /// specified index. If you pass the collection's `endIndex` property as
-  /// the `index` parameter, the new element is appended to the
-  /// collection.
+  /// The new element is inserted before the element currently at the specified
+  /// index. If you pass the collection's `endIndex` property as the `i`
+  /// parameter, the new element is appended to the collection.
   ///
   ///     var numbers = [1, 2, 3, 4, 5]
   ///     numbers.insert(100, at: 3)
@@ -638,8 +634,8 @@ extension RangeReplaceableCollection {
   /// collection.
   ///
   /// - Parameter newElement: The new element to insert into the collection.
-  /// - Parameter i: The position at which to insert the new element.
-  ///   `index` must be a valid index into the collection.
+  /// - Parameter i: The position at which to insert the new element. `i` must
+  ///   be a valid index into the collection.
   ///
   /// - Complexity: O(*n*), where *n* is the length of the collection.
   public mutating func insert(
@@ -653,7 +649,7 @@ extension RangeReplaceableCollection {
   ///
   /// The new elements are inserted before the element currently at the
   /// specified index. If you pass the collection's `endIndex` property as the
-  /// `index` parameter, the new elements are appended to the collection.
+  /// `i` parameter, the new elements are appended to the collection.
   ///
   /// Here's an example of inserting a range of integers into an array of the
   /// same type:
@@ -667,8 +663,8 @@ extension RangeReplaceableCollection {
   /// collection.
   ///
   /// - Parameter newElements: The new elements to insert into the collection.
-  /// - Parameter i: The position at which to insert the new elements. `index`
-  ///   must be a valid index of the collection.
+  /// - Parameter i: The position at which to insert the new elements. `i` must
+  ///   be a valid index of the collection.
   ///
   /// - Complexity: O(*m*), where *m* is the combined length of the collection
   ///   and `newElements`. If `i` is equal to the collection's `endIndex`

stdlib/public/core/SetAlgebra.swift

@@ -124,8 +124,8 @@ public protocol SetAlgebra : Equatable, ExpressibleByArrayLiteral {
   ///
   /// 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 in only one or the other are left out of the result of
-  /// the intersection.
+  /// Elements that are in either one or the other, but not both, are left out
+  /// of the result of the intersection.
   ///
   ///     let employees: Set = ["Alicia", "Bethany", "Chris", "Diana", "Eric"]
   ///     let neighbors: Set = ["Bethany", "Eric", "Forlani", "Greta"]