Improve docs on QML Animation page and associated elements

Task-number: QTBUG-12666

7 files changed, 67 insertions, 26 deletions

diff --git a/src/declarative/util/qdeclarativeanimation.cpp b/src/declarative/util/qdeclarativeanimation.cpp
index 6a9cf95..b901bb3 100644
--- a/src/declarative/util/qdeclarativeanimation.cpp
+++ b/src/declarative/util/qdeclarativeanimation.cpp
@@ -645,12 +645,13 @@ QAbstractAnimation *QDeclarativePauseAnimation::qtAnimation()
 
     Like any other animation element, a ColorAnimation can be applied in a
     number of ways, including transitions, behaviors and property value 
-    sources. The \l PropertyAnimation documentation shows a variety of methods
+    sources. The \l {QML Animation} documentation shows a variety of methods
     for creating animations.
 
-    When used in a transition, ColorAnimation will by default animate
-    all properties of type color that have changed. If a \l{PropertyAnimation::}{property} 
-    or \l{PropertyAnimation::}{properties} are explicitly set for the animation, 
+    For convenience, when a ColorAnimation is used in a \l Transition, it will 
+    animate any \c color properties that have been modified during the state 
+    change. If a \l{PropertyAnimation::}{property} or 
+    \l{PropertyAnimation::}{properties} are explicitly set for the animation, 
     then those are used instead.
 
     \sa {QML Animation}, {declarative/animation/basics}{Animation basics example}
@@ -1143,7 +1144,7 @@ void QDeclarativePropertyAction::transition(QDeclarativeStateActions &actions,
 
     Like any other animation element, a NumberAnimation can be applied in a
     number of ways, including transitions, behaviors and property value 
-    sources. The \l PropertyAnimation documentation shows a variety of methods
+    sources. The \l {QML Animation} documentation shows a variety of methods
     for creating animations.
 
     Note that NumberAnimation may not animate smoothly if there are irregular
@@ -1244,6 +1245,11 @@ void QDeclarativeNumberAnimation::setTo(qreal t)
     Vector3dAnimation is a specialized PropertyAnimation that defines an 
     animation to be applied when a Vector3d value changes.
 
+    Like any other animation element, a Vector3dAnimation can be applied in a
+    number of ways, including transitions, behaviors and property value 
+    sources. The \l {QML Animation} documentation shows a variety of methods
+    for creating animations.
+
     \sa {QML Animation}, {declarative/animation/basics}{Animation basics example}
 */
 
@@ -1323,7 +1329,7 @@ void QDeclarativeVector3dAnimation::setTo(QVector3D t)
 
     \snippet doc/src/snippets/declarative/rotationanimation.qml 0
     
-    Notice the RotationAnimation did not need to set a \l {RotationAnimation::}{target}
+    Notice the RotationAnimation did not need to set a \l {PropertyAnimation::}{target}
     value. As a convenience, when used in a transition, RotationAnimation will rotate all
     properties named "rotation" or "angle". You can override this by providing
     your own properties via \l {PropertyAnimation::properties}{properties} or 
@@ -1331,7 +1337,7 @@ void QDeclarativeVector3dAnimation::setTo(QVector3D t)
 
     Like any other animation element, a RotationAnimation can be applied in a
     number of ways, including transitions, behaviors and property value 
-    sources. The \l PropertyAnimation documentation shows a variety of methods
+    sources. The \l {QML Animation} documentation shows a variety of methods
     for creating animations.
 
     \sa {QML Animation}, {declarative/animation/basics}{Animation basics example}
@@ -1554,7 +1560,7 @@ QDeclarativeListProperty<QDeclarativeAbstractAnimation> QDeclarativeAnimationGro
 
     Like any other animation element, a SequentialAnimation can be applied in a
     number of ways, including transitions, behaviors and property value 
-    sources. The \l PropertyAnimation documentation shows a variety of methods
+    sources. The \l {QML Animation} documentation shows a variety of methods
     for creating animations.
 
     \note Once an animation has been grouped into a SequentialAnimation or 
@@ -1623,7 +1629,7 @@ void QDeclarativeSequentialAnimation::transition(QDeclarativeStateActions &actio
 
     Like any other animation element, a ParallelAnimation can be applied in a
     number of ways, including transitions, behaviors and property value 
-    sources. The \l PropertyAnimation documentation shows a variety of methods
+    sources. The \l {QML Animation} documentation shows a variety of methods
     for creating animations.
 
     \note Once an animation has been grouped into a SequentialAnimation or 
@@ -2396,8 +2402,7 @@ void QDeclarativePropertyAnimation::transition(QDeclarativeStateActions &actions
     \inherits Animation
     \brief The ParentAnimation element animates changes in parent values.
 
-    ParentAnimation defines an animation to applied when a ParentChange
-    occurs. This allows parent changes to be smoothly animated.
+    ParentAnimation is used to animate a parent change for an \l Item.
 
     For example, the following ParentChange changes \c blueRect to become
     a child of \c redRect when it is clicked. The inclusion of the 
@@ -2415,10 +2420,16 @@ void QDeclarativePropertyAnimation::transition(QDeclarativeStateActions &actions
     to animate the parent change via another item that does not have clipping
     enabled. Such an item can be set using the \l via property.
 
-    By default, when used in a transition, ParentAnimation animates all parent 
-    changes. This can be overridden by setting a specific target item using the
+    For convenience, when a ParentAnimation is used in a \l Transition, it will 
+    animate any ParentChange that has occurred during the state change. 
+    This can be overridden by setting a specific target item using the
     \l target property.
 
+    Like any other animation element, a ParentAnimation can be applied in a
+    number of ways, including transitions, behaviors and property value 
+    sources. The \l {QML Animation} documentation shows a variety of methods
+    for creating animations.
+
     \sa {QML Animation}, {declarative/animation/basics}{Animation basics example}
 */
 
@@ -2750,14 +2761,23 @@ QAbstractAnimation *QDeclarativeParentAnimation::qtAnimation()
     \inherits Animation
     \brief The AnchorAnimation element animates changes in anchor values.
 
-    AnchorAnimation is used to animate an AnchorChange. It will anchor all
-    anchor changes specified in a \l State.
+    AnchorAnimation is used to animate an anchor change. 
 
     In the following snippet we animate the addition of a right anchor to a \l Rectangle:
 
     \snippet doc/src/snippets/declarative/anchoranimation.qml 0
 
-    \sa AnchorChanges
+    For convenience, when an AnchorAnimation is used in a \l Transition, it will 
+    animate any AnchorChanges that have occurred during the state change. 
+    This can be overridden by setting a specific target item using the
+    \l target property.
+
+    Like any other animation element, an AnchorAnimation can be applied in a
+    number of ways, including transitions, behaviors and property value 
+    sources. The \l {QML Animation} documentation shows a variety of methods
+    for creating animations.
+
+    \sa {QML Animation}, AnchorChanges
 */
 
 QDeclarativeAnchorAnimation::QDeclarativeAnchorAnimation(QObject *parent)
diff --git a/src/declarative/util/qdeclarativebehavior.cpp b/src/declarative/util/qdeclarativebehavior.cpp
index fadb2ae..1e7f81a 100644
--- a/src/declarative/util/qdeclarativebehavior.cpp
+++ b/src/declarative/util/qdeclarativebehavior.cpp
@@ -84,12 +84,15 @@ public:
 
     \snippet doc/src/snippets/declarative/behavior.qml 0
 
-    To run multiple animations within a Behavior, use ParallelAnimation or
+    Note that a property cannot have more than one assigned Behavior. To provide
+    multiple animations within a Behavior, use ParallelAnimation or
     SequentialAnimation.
 
-    Note that a property cannot have more than one assigned Behavior.
+    If a \l{QML States}{state change} has a \l Transition that matches the same property as a
+    Behavior, the \l Transition animation overrides the Behavior for that
+    state change.
 
-    \sa {Property Behaviors}, {declarative/animation/behaviors}{Behavior example}, QtDeclarative
+    \sa {QML Animation}, {declarative/animation/behaviors}{Behavior example}, QtDeclarative
 */
 
 
diff --git a/src/declarative/util/qdeclarativesmoothedanimation.cpp b/src/declarative/util/qdeclarativesmoothedanimation.cpp
index 727f427..30e1491 100644
--- a/src/declarative/util/qdeclarativesmoothedanimation.cpp
+++ b/src/declarative/util/qdeclarativesmoothedanimation.cpp
@@ -287,7 +287,7 @@ void QSmoothedAnimation::init()
 
     Like any other animation element, a SmoothedAnimation can be applied in a
     number of ways, including transitions, behaviors and property value 
-    sources. The \l PropertyAnimation documentation shows a variety of methods
+    sources. The \l {QML Animation} documentation shows a variety of methods
     for creating animations.
 
     \sa SpringAnimation, NumberAnimation, {QML Animation}, {declarative/animation/basics}{Animation basics example}
diff --git a/src/declarative/util/qdeclarativespringanimation.cpp b/src/declarative/util/qdeclarativespringanimation.cpp
index cfc7b8e..6f4ac51 100644
--- a/src/declarative/util/qdeclarativespringanimation.cpp
+++ b/src/declarative/util/qdeclarativespringanimation.cpp
@@ -228,6 +228,7 @@ void QDeclarativeSpringAnimationPrivate::updateMode()
 
 /*!
     \qmlclass SpringAnimation QDeclarativeSpringAnimation
+    \inherits Animation
     \since 4.7
 
     \brief The SpringAnimation element allows a property to track a value in a spring-like motion.
@@ -246,7 +247,7 @@ void QDeclarativeSpringAnimationPrivate::updateMode()
 
     Like any other animation element, a SpringAnimation can be applied in a
     number of ways, including transitions, behaviors and property value 
-    sources. The \l PropertyAnimation documentation shows a variety of methods
+    sources. The \l {QML Animation} documentation shows a variety of methods
     for creating animations.
 
     \sa SmoothedAnimation, {QML Animation}, {declarative/animation/basics}{Animation basics example}, {declarative/toys/clocks}{Clocks example}
diff --git a/src/declarative/util/qdeclarativestate.cpp b/src/declarative/util/qdeclarativestate.cpp
index 0d43d21..7a78a2b 100644
--- a/src/declarative/util/qdeclarativestate.cpp
+++ b/src/declarative/util/qdeclarativestate.cpp
@@ -154,7 +154,7 @@ QDeclarativeStateOperation::QDeclarativeStateOperation(QObjectPrivate &dd, QObje
 
     Notice the default state is referred to using an empty string ("").
 
-    States are commonly used together with \l {state-transitions}{Transitions} to provide
+    States are commonly used together with \l {Transitions} to provide
     animations when state changes occur.
 
     \note Setting the state of an object from within another state of the same object is
diff --git a/src/declarative/util/qdeclarativestategroup.cpp b/src/declarative/util/qdeclarativestategroup.cpp
index 67cd12e..1c1e964 100644
--- a/src/declarative/util/qdeclarativestategroup.cpp
+++ b/src/declarative/util/qdeclarativestategroup.cpp
@@ -112,7 +112,7 @@ public:
    }
    \endqml
 
-   \sa {qmlstate}{States} {state-transitions}{Transitions}, {QtDeclarative}
+   \sa {qmlstate}{States} {Transitions}, {QtDeclarative}
 */
 
 QDeclarativeStateGroup::QDeclarativeStateGroup(QObject *parent)
@@ -204,7 +204,7 @@ void QDeclarativeStateGroupPrivate::clear_states(QDeclarativeListProperty<QDecla
   }
   \endqml
 
-  \sa {state-transitions}{Transitions}
+  \sa {Transitions}
 */
 QDeclarativeListProperty<QDeclarativeTransition> QDeclarativeStateGroup::transitionsProperty()
 {
diff --git a/src/declarative/util/qdeclarativetransition.cpp b/src/declarative/util/qdeclarativetransition.cpp
index 582191b..7042d0c 100644
--- a/src/declarative/util/qdeclarativetransition.cpp
+++ b/src/declarative/util/qdeclarativetransition.cpp
@@ -60,12 +60,25 @@ QT_BEGIN_NAMESPACE
 
     For example, the following \l Rectangle has two states: the default state, and
     an added "moved" state. In the "moved state, the rectangle's position changes 
-    to (50, 50).  The added \l Transition specifies that when the rectangle
+    to (50, 50).  The added Transition specifies that when the rectangle
     changes between the default and the "moved" state, any changes
     to the \c x and \c y properties should be animated, using an \c Easing.InOutQuad.
    
     \snippet doc/src/snippets/declarative/transition.qml 0
 
+    Notice the example does not require \l{PropertyAnimation::}{to} and 
+    \l{PropertyAnimation::}{from} values for the NumberAnimation. As a convenience,
+    these properties are automatically set to the values of \c x and \c y before
+    and after the state change; the \c from values are provided by
+    the current values of \c x and \c y, and the \c to values are provided by
+    the PropertyChanges object. If you wish, you can provide \l{PropertyAnimation::}{to} and 
+    \l{PropertyAnimation::}{from} values anyway to override the default values.
+
+    By default, a Transition's animations are applied for any state change in the 
+    parent item. The  Transition \l {Transition::}{from} and \l {Transition::}{to} 
+    values can be set to restrict the animations to only be applied when changing 
+    from one particular state to another.
+
     To define multiple transitions, specify \l Item::transitions as a list:
 
     \qml
@@ -78,7 +91,11 @@ QT_BEGIN_NAMESPACE
     }
     \endqml
 
-    \sa {declarative/animation/states}{states example}, {qmlstates}{States}, {state-transitions}{Transitions}, {QtDeclarative}
+    If a state change has a Transition that matches the same property as a
+    \l Behavior, the Transition animation overrides the \l Behavior for that
+    state change.
+
+    \sa {QML Animation}, {declarative/animation/states}{states example}, {qmlstates}{States}, {QtDeclarative}
 */
 
 /*!