Updated docs for pullback. (#155)

* Updated docs for pullback.

* update

* Update Sources/SnapshotTesting/Snapshotting.swift

Co-Authored-By: mbrandonw <[email protected]>

* Update Sources/SnapshotTesting/Snapshotting.swift

Co-Authored-By: mbrandonw <[email protected]>

* Update Sources/SnapshotTesting/Snapshotting.swift

Co-Authored-By: mbrandonw <[email protected]>

* Update Sources/SnapshotTesting/Snapshotting.swift

Co-Authored-By: mbrandonw <[email protected]>

* Update Sources/SnapshotTesting/Snapshotting.swift

Co-Authored-By: mbrandonw <[email protected]>

* update doc style

Author: mbrandonw

Sources/SnapshotTesting/Snapshotting.swift

@@ -46,8 +46,31 @@ public struct Snapshotting<Value, Format> {
     }
   }
 
+  /// Transforms a strategy on `Value`s into a strategy on `NewValue`s through a function `(NewValue) -> Value`.
+  ///
+  /// This is the most important operation for transforming existing strategies into new strategies. It allows you to transform a `Snapshotting<Value, Format>` into a `Snapshotting<NewValue, Format>` by pulling it back along a function `(NewValue) -> Value`. Notice that the function must go in in the direction `(NewValue) -> Value` even though we are transforming in the other direction `(Snapshotting<Value, Format>) -> Snapshotting<NewValue, Format>`.
+  ///
+  /// A simple example of this is to `pullback` the snapshot strategy on `UIView`s to work on `UIViewController`s:
+  ///
+  ///     let strategy = Snapshotting<UIView, UIImage>.image.pullback { (vc: UIViewController) in
+  ///       return vc.view
+  ///     }
+  ///
+  /// Here we took the strategy that snapshots `UIView`s as `UIImage`s and pulled it back to work on `UIViewController`s by using the function `(UIViewController) -> UIView` that simply plucks the view out of the controller.
+  ///
+  /// Nearly every snapshot strategy provided in this library is a pullback of some base strategy, which shows just how important this operation is.
+  ///
+  /// - Parameters:
+  ///   - transform: A transform function from `NewValue` into `Value`.
+  ///   - otherValue: A value to be transformed.
+  public func pullback<NewValue>(_ transform: @escaping (_ otherValue: NewValue) -> Value) -> Snapshotting<NewValue, Format> {
+    return self.asyncPullback { newValue in Async(value: transform(newValue)) }
+  }
+
   /// Transforms a strategy on `Value`s into a strategy on `NewValue`s through a function `(NewValue) -> Async<Value>`.
   ///
+  /// See the documention of `pullback` for a full description of how pullbacks works. This operation differs from `pullback` in that it allows you to use a transformation `(NewValue) -> Async<Value>`, which is necessary when your transformation needs to perform some asynchronous work.
+  ///
   /// - Parameters:
   ///   - transform: A transform function from `NewValue` into `Async<Value>`.
   ///   - otherValue: A value to be transformed.
@@ -67,15 +90,6 @@ public struct Snapshotting<Value, Format> {
         }
       }
   }
-
-  /// Transforms a strategy on `Value`s into a strategy on `NewValue`s through a function `(NewValue) -> Value`.
-  ///
-  /// - Parameters:
-  ///   - transform: A transform function from `NewValue` into `Value`.
-  ///   - otherValue: A value to be transformed.
-  public func pullback<NewValue>(_ transform: @escaping (_ otherValue: NewValue) -> Value) -> Snapshotting<NewValue, Format> {
-    return self.asyncPullback { newValue in Async(value: transform(newValue)) }
-  }
 }
 
 /// A snapshot strategy where the type being snapshot is also a diffable type.