Update animation docs.

2 files changed, 75 insertions, 19 deletions

diff --git a/doc/src/declarative/animation.qdoc b/doc/src/declarative/animation.qdoc
index ba45d81..1314493 100644
--- a/doc/src/declarative/animation.qdoc
+++ b/doc/src/declarative/animation.qdoc
@@ -81,6 +81,22 @@ Rectangle {
 
 \image propanim.gif
 
+When you assign an animation as a value source, you do not need to specify \c property
+or \c target; they are automatically selected for you. You do, however, need to specify \c to, and explicitly
+start the animation (usually via the \c running property).
+
+\qml
+Rectangle {
+    id: rect
+    width: 200; height: 200;
+    Rectangle {
+        color: "red"
+        width: 50; height: 50
+        x: NumberAnimation { to: 50; running: true }
+    }
+}
+\endqml
+
 A property animation can also be specified as a resource that is manipulated from script.
 
 \qml
@@ -100,12 +116,16 @@ Image {
 }
 \endqml
 
+As can be seen, when an animation is used like this (as opposed to as a value source) you will need
+to explicitly set the \c target and \c property to animate.
+
 Animations can be joined into a group using SequentialAnimation and ParallelAnimation.
 
 \target state-transitions
 \section1 Transitions
 
-QML transitions describe animations to perform when \l{qmlstates}{state} changes occur.
+QML transitions describe animations to perform when \l{qmlstates}{state} changes occur. A transition
+can only be triggered by a state change.
 
 For example, a transition could describe how an item moves from its initial position to its new position:
 
@@ -123,11 +143,11 @@ transitions: [
 
 As you can see from the above example, transitions make use of the same basic animation classes introduced
 above. However, you generally use a different set of properties when working with transitions. In the example,
-no target or property has been specified. Instead, we have specified matchProperties, which acts as a selector to
-determine which property changes to animate; in this case, we will animate any x,y properties that have
-changed on any objects.
+no \c target or \c property has been specified. Instead, we have specified \c matchProperties,
+which (along with \c matchTargets) acts as a selector to determine which property changes to animate;
+in this case, we will animate any x,y properties that have changed on any objects.
 
-QML transitions also selectors to determine which state changes a transition should apply to:
+QML transitions also have selectors to determine which state changes a transition should apply to:
 
 \code
 Transition {
@@ -137,7 +157,9 @@ Transition {
 }
 \endcode
 
-Transitions can happen in parallel, in sequence, or in any combination of the two:
+Transitions can happen in parallel, in sequence, or in any combination of the two. By default, the top-level
+animations in a transition will happen in parallel. The following example shows a rather complex transition
+making use of both sequential and parallel animations:
 
 \code
 Transition {
@@ -145,13 +167,8 @@ Transition {
     to: "MyState"
     reversible: true
     SequentialAnimation {
-        ColorAnimation {
-            property: "color"
-            duration: 1000
-        }
-        PauseAnimation {
-            duration: 1000
-        }
+        ColorAnimation { duration: 1000 }
+        PauseAnimation { duration: 1000 }
         ParallelAnimation {
             NumberAnimation {
                 duration: 1000
@@ -169,9 +186,37 @@ Transition {
 }
 \endcode
 
+To insert an explicit animation into your transition, you can use \target and \property as normal.
+
+\code
+Transition {
+    from: "*"
+    to: "MyState"
+    reversible: true
+    SequentialAnimation {
+        NumberAnimation {
+            duration: 1000
+            easing: "easeOutBounce"
+            // animate myItem's x and y if they have changed in the state
+            matchTargets: myItem
+            matchProperties: "x,y"
+        }
+        NumberAnimation {
+            duration: 1000
+            // animate myItem2's y to 200, regardless of what happens in the state
+            target: myItem2
+            property: "y"
+            to: 200
+        }
+    }
+}
+\endcode
+
 \section1 Property Behaviors
 
-A property behavior specifies a default animation to run whenever the property's value changes.
+A property behavior specifies a default animation to run whenever the property's value changes, regardless
+of what caused the change. Unlike Transition, Behavior doesn't provide a way to indicate that a Behavior
+should only apply under certain circumstances.
 
 In the following snippet, we specify that we want the x position of redRect to be animated
 whenever it changes. The animation will last 300 milliseconds and use an InOutQuad easing curve.
@@ -185,6 +230,9 @@ Rectangle {
 }
 \endqml
 
+Like using an animation as a value source, when used in a Behavior and animation does not need to specify
+a \c target or \c property.
+
 To trigger this behavior, we could:
 \list
 \o Enter a state that changes x
diff --git a/src/declarative/util/qmlanimation.cpp b/src/declarative/util/qmlanimation.cpp
index 7c5bc50..94cdadf 100644
--- a/src/declarative/util/qmlanimation.cpp
+++ b/src/declarative/util/qmlanimation.cpp
@@ -1507,6 +1507,8 @@ void QmlPropertyAnimationPrivate::convertVariant(QVariant &variant, int type)
     \code
     VariantAnimation { property: "size"; to: "20x20"; duration: 200 }
     \endcode
+
+    \a qmlanimation.html
 */
 
 QmlPropertyAnimation::QmlPropertyAnimation(QObject *parent)
@@ -1795,16 +1797,20 @@ void QmlPropertyAnimation::setEasing(const QString &e)
     \qmlproperty Object PropertyAnimation::target
     This property holds an explicit target object to animate.
 
-    The exact effect of the \c target property depends on how the animation
-    is being used.  Refer to the \l animation documentation for details.
+    target is used in conjunction with property to determine
+    what property should be animated.
+
+    \sa property matchTargets
 */
 
 /*!
     \qmlproperty string PropertyAnimation::property
-    This property holds an explicit property to animated.
+    This property holds an explicit property name to animate.
 
-    The exact effect of the \c property property depends on how the animation
-    is being used.  Refer to the \l animation documentation for details.
+    property is used in conjunction with target to determine
+    what property should be animated.
+
+    \sa target matchProperties
 */
 
 /*!
@@ -1833,6 +1839,8 @@ void QmlPropertyAnimation::setEasing(const QString &e)
     This property is typically used for an animation appearing as part of a Transition.
 
     By default, no property names will be matched.
+
+    \sa matchTargets PropertyAction::matchTargets
 */
 QString QmlPropertyAnimation::properties() const
 {