Document TransitionSpring.

Reviewers: O2 Material Motion, O4 Material Apple platform reviewers, #material_motion, chuga

Reviewed By: O4 Material Apple platform reviewers, chuga

Tags: #material_motion

Differential Revision: http://codereview.cc/D2872

src/interactions/TransitionSpring.swift

@@ -16,21 +16,50 @@
 
 import Foundation
 
-/** Attaches a position to a destination on either side of a transition using a spring. */
+/**
+ A transition spring pulls a value from one side of a transition to another.
+
+ A transition spring can be associated with many properties. Each property receives its own distinct
+ simulator that reads the property as the initial value and pulls the value towards the destination.
+ Configuration values are shared across all running instances.
+
+ **Directionality**
+
+ The terms `back` and `fore` are used here to refer to the backward and forward destinations,
+ respectively. View controller transitions move *forward* when being presented, and *backward* when
+ being dismissed. This consistency of directionality makes it easy to describe the goal states for
+ a transition in a consistent manner, regardless of the direction.
+
+ **Initial value**
+
+ When associated with a property, this interaction will assign an initial value to the property
+ corresponding to the initial direction's oposite destination. E.g. if transitioning forward, the
+ property will be initialized with the `back` value.
+
+ **Constraints**
+
+ T-value constraints may be applied to this interaction.
+ */
 public class TransitionSpring<T: Zeroable>: Spring<T> {
 
+  /**
+   The destination when the transition is moving backward.
+   */
   public let backwardDestination: T
+
+  /**
+   The destination when the transition is moving forward.
+   */
   public let forwardDestination: T
 
   /**
-   - parameter value: The property to be updated by the value stream.
-   - parameter back: The destination to which the spring will pull the view when transitioning
-                     backward.
-   - parameter fore: The destination to which the spring will pull the view when transitioning
-                     forward.
-   - parameter direction: The spring will change its destination in reaction to this property's
-                          changes.
-   - parameter system A function capable of creating a spring source.
+   Creates a transition spring with a given threshold and system.
+
+   - parameter back: The destination to which the spring will pull the view when transitioning backward.
+   - parameter fore: The destination to which the spring will pull the view when transitioning forward.
+   - parameter direction: The spring will change its destination in reaction to this property's changes.
+   - parameter threshold: The threshold of movement defining the completion of the spring simulation.
+   - parameter system: Often coreAnimation. Can be another system if a system support library is available.
    */
   public init(back backwardDestination: T,
               fore forwardDestination: T,