---

yaml
---
r: 294271
b: refs/heads/tensorflow
c: 841eb4c
h: refs/heads/master
i:
  294269: db570fa
  294267: bc77be0
  294263: 9c6ae5e
  294255: 791f97f
  294239: 897bbe6
  294207: 00e11ba
  294143: 4e34cbd

Author: natecook1000

[refs]

@@ -816,7 +816,7 @@ refs/tags/swift-DEVELOPMENT-SNAPSHOT-2018-04-25-a: 22f738a831d43aff2b9c9773bcb65
 refs/tags/swift-DEVELOPMENT-SNAPSHOT-2018-05-08-a: 7d98cc16689baba5c8a3b90a9329bdcc1a12b4e9
 refs/heads/cherr42: a566ad54b073c2c56ac0a705d0a5bed9743135a5
 "refs/heads/codable_test_comment_fix": fc8f6824f7f347e1e8db55bff62db385c5728b5a
-refs/heads/tensorflow: 14a20eea03e9115e2c5cf91bccc86e6cd5334df9
+refs/heads/tensorflow: 841eb4cf5eaacaef70132db56f69441533a5127e
 refs/tags/swift-4.1-DEVELOPMENT-SNAPSHOT-2018-05-11-a: 8126fd7a652e2f70ad6d76505239e34fb2ef3e1a
 refs/tags/swift-4.1-DEVELOPMENT-SNAPSHOT-2018-05-12-a: b3fd3dd84df6717f2e2e9df58c6d7e99fed57086
 refs/tags/swift-4.1-DEVELOPMENT-SNAPSHOT-2018-05-13-a: 71135119579039dc321c5f65d870050fe36efda2

branches/tensorflow/stdlib/public/core/CollectionDifference.swift

@@ -10,19 +10,26 @@
 //
 //===----------------------------------------------------------------------===//
 
-/// A type that represents the difference between two ordered collection states.
+/// A collection of insertions and removals that describe the difference 
+/// between two ordered collection states.
 @available(macOS 9999, iOS 9999, tvOS 9999, watchOS 9999, *) // FIXME(availability-5.1)
 public struct CollectionDifference<ChangeElement> {
-  /// A type that represents a single change to a collection.
-  ///
-  /// The `offset` of each `insert` refers to the offset of its `element` in
-  /// the final state after the difference is fully applied. The `offset` of
-  /// each `remove` refers to the offset of its `element` in the original
-  /// state. Non-`nil` values of `associatedWith` refer to the offset of the
-  /// complementary change.
+  /// A single change to a collection.
   @_frozen
   public enum Change {
+    /// An insertion.
+    ///
+    /// The `offset` value is the offset of the inserted element in the final
+    /// state of the collection after the difference is fully applied.
+    /// A non-`nil` `associatedWith` value is the offset of the complementary 
+    /// change.
     case insert(offset: Int, element: ChangeElement, associatedWith: Int?)
+    
+    /// A removal.
+    ///
+    /// The `offset` value is the offset of the element to be removed in the
+    /// original state of the collection. A non-`nil` `associatedWith` value is 
+    /// the offset of the complementary change.
     case remove(offset: Int, element: ChangeElement, associatedWith: Int?)
 
     // Internal common field accessors
@@ -58,10 +65,11 @@ public struct CollectionDifference<ChangeElement> {
     }
   }
 
-  /// The `.insert` changes contained by this difference, from lowest offset to highest
+  /// The insertions contained by this difference, from lowest offset to 
+  /// highest.
   public let insertions: [Change]
 
-  /// The `.remove` changes contained by this difference, from lowest offset to highest
+  /// The removals contained by this difference, from lowest offset to highest.
   public let removals: [Change]
 
   /// The public initializer calls this function to ensure that its parameter
@@ -117,20 +125,20 @@ public struct CollectionDifference<ChangeElement> {
     return removeOffsetToAssoc == insertAssocToOffset
   }
 
-  /// Creates an instance from a collection of changes.
+  /// Creates a new collection difference from a collection of changes.
   ///
-  /// For clients interested in the difference between two collections, see
-  /// `BidirectionalCollection.difference(from:)`.
+  /// To find the difference between two collections, use the 
+  /// `difference(from:)` method declared on the `BidirectionalCollection`
+  /// protocol.
   ///
-  /// To guarantee that instances are unambiguous and safe for compatible base
-  /// states, this initializer will fail unless its parameter meets to the
-  /// following requirements:
+  /// The collection of changes passed as `changes` must meet these 
+  /// requirements:
   ///
-  /// 1. All insertion offsets are unique
-  /// 2. All removal offsets are unique
-  /// 3. All associations between insertions and removals are symmetric
+  /// - All insertion offsets are unique
+  /// - All removal offsets are unique
+  /// - All associations between insertions and removals are symmetric
   ///
-  /// - Parameter c: A collection of changes that represent a transition
+  /// - Parameter changes: A collection of changes that represent a transition
   ///   between two states.
   ///
   /// - Complexity: O(*n* * log(*n*)), where *n* is the length of the
@@ -218,6 +226,7 @@ public struct CollectionDifference<ChangeElement> {
 extension CollectionDifference: Collection {
   public typealias Element = Change
 
+  /// The position of a collection difference.
   @_fixed_layout
   public struct Index {
     // Opaque index type is isomorphic to Int
@@ -305,12 +314,12 @@ extension CollectionDifference: Hashable where ChangeElement: Hashable {}
 
 @available(macOS 9999, iOS 9999, tvOS 9999, watchOS 9999, *) // FIXME(availability-5.1)
 extension CollectionDifference where ChangeElement: Hashable {
-  /// Infers which `ChangeElement`s have been both inserted and removed only
-  /// once and returns a new difference with those associations.
+  /// Returns a new collection difference with associations between individual
+  /// elements that have been removed and inserted only once.
   ///
-  /// - Returns: an instance with all possible moves inferred.
+  /// - Returns: An collection difference with all possible moves inferred.
   ///
-  /// - Complexity: O(*n*) where *n* is `self.count`
+  /// - Complexity: O(*n*) where *n* is the number of collection differences.
   public func inferringMoves() -> CollectionDifference<ChangeElement> {
     let uniqueRemovals: [ChangeElement:Int?] = {
       var result = [ChangeElement:Int?](minimumCapacity: Swift.min(removals.count, insertions.count))

branches/tensorflow/stdlib/public/core/Diffing.swift

@@ -54,7 +54,7 @@ extension CollectionDifference {
 }
 
 extension RangeReplaceableCollection {
-  /// Applies a difference to a collection.
+  /// Applies the given difference to this collection.
   ///
   /// - Parameter difference: The difference to be applied.
   ///
@@ -112,23 +112,24 @@ extension RangeReplaceableCollection {
 // MARK: Definition of API
 
 extension BidirectionalCollection {
-  /// Returns the difference needed to produce the receiver's state from the
-  /// parameter's state, using the provided closure to establish equivalence
-  /// between elements.
+  /// Returns the difference needed to produce this collection's ordered 
+  /// elements from the given collection, using the given predicate as an 
+  /// equivalence test.
   ///
-  /// This function does not infer moves.
+  /// This function does not infer element moves. If you need to infer moves,
+  /// call the `inferringMoves()` method on the resulting difference.
   ///
   /// - Parameters:
   ///   - other: The base state.
-  ///   - areEquivalent: A closure that returns whether the two
-  ///     parameters are equivalent.
+  ///   - areEquivalent: A closure that returns a Boolean value indicating 
+  ///     whether two elements are equivalent.
   ///
   /// - Returns: The difference needed to produce the reciever's state from
   ///   the parameter's state.
   ///
-  /// - Complexity: For pathological inputs, worst case performance is
-  ///   O(`self.count` * `other.count`). Faster execution can be expected
-  ///   when the collections share many common elements.
+  /// - Complexity: Worst case performance is O(*n* * *m*), where *n* is the 
+  ///   count of this collection and *m* is `other.count`. You can expect 
+  ///   faster execution when the collections share many common elements.
   @available(macOS 9999, iOS 9999, tvOS 9999, watchOS 9999, *) // FIXME(availability-5.1)
   public func difference<C: BidirectionalCollection>(
     from other: C,
@@ -167,23 +168,22 @@ extension BidirectionalCollection {
 }
 
 extension BidirectionalCollection where Element : Equatable {
-  /// Returns the difference needed to produce the receiver's state from the
-  /// parameter's state, using equality to establish equivalence between
-  /// elements.
+  /// Returns the difference needed to produce this collection's ordered 
+  /// elements from the given collection.
   ///
-  /// This function does not infer element moves, but they can be computed
-  /// using `CollectionDifference.inferringMoves()` if desired.
+  /// This function does not infer element moves. If you need to infer moves,
+  /// call the `inferringMoves()` method on the resulting difference.
   ///
   /// - Parameters:
   ///   - other: The base state.
   ///
-  /// - Returns: The difference needed to produce the reciever's state from
-  ///   the parameter's state.
+  /// - Returns: The difference needed to produce this collection's ordered 
+  ///   elements from the given collection.
   ///
-  /// - Complexity: For pathological inputs, worst case performance is
-  ///   O(`self.count` * `other.count`). Faster execution can be expected
-  ///   when the collections share many common elements, or if `Element`
-  ///   also conforms to `Hashable`.
+  /// - Complexity: Worst case performance is O(*n* * *m*), where *n* is the 
+  ///   count of this collection and *m* is `other.count`. You can expect 
+  ///   faster execution when the collections share many common elements, or 
+  ///   if `Element` conforms to `Hashable`.
   @available(macOS 9999, iOS 9999, tvOS 9999, watchOS 9999, *) // FIXME(availability-5.1)
   public func difference<C: BidirectionalCollection>(
     from other: C