diff -r 5dc02b23752f -r 3e2da88830cd src/declarative/util/qdeclarativeanimation.cpp
--- a/src/declarative/util/qdeclarativeanimation.cpp	Tue Jul 06 15:10:48 2010 +0300
+++ b/src/declarative/util/qdeclarativeanimation.cpp	Wed Aug 18 10:37:55 2010 +0300
@@ -142,6 +142,16 @@
     return d->running;
 }
 
+// the behavior calls this function
+void QDeclarativeAbstractAnimation::notifyRunningChanged(bool running)
+{
+    Q_D(QDeclarativeAbstractAnimation);
+    if (d->disableUserControl && d->running != running) {
+        d->running = running;
+        emit runningChanged(running);
+    }
+}
+
 //commence is called to start an animation when it is used as a
 //simple animation, and not as part of a transition
 void QDeclarativeAbstractAnimationPrivate::commence()
@@ -176,6 +186,8 @@
 {
     Q_D(QDeclarativeAbstractAnimation);
     if (!d->componentComplete) {
+        if (d->running && r == d->running)    //don't re-register
+            return;
         d->running = r;
         if (r == false)
             d->avoidPropertyValueSourceStart = true;
@@ -557,6 +569,8 @@
         NumberAnimation { ... duration: 200 }
     }
     \endcode
+
+    \sa {QML Animation}, {declarative/animation/basics}{Animation basics example}
 */
 /*!
     \internal
@@ -618,15 +632,28 @@
     \qmlclass ColorAnimation QDeclarativeColorAnimation
     \since 4.7
     \inherits PropertyAnimation
-    \brief The ColorAnimation element allows you to animate color changes.
-
-    \code
-    ColorAnimation { from: "white"; to: "#c0c0c0"; duration: 100 }
-    \endcode
+    \brief The ColorAnimation element animates changes in color values.
+
+    ColorAnimation is a specialized PropertyAnimation that defines an 
+    animation to be applied when a color value changes.
+
+    Here is a ColorAnimation applied to the \c color property of a \l Rectangle 
+    as a property value source. It animates the \c color property's value from 
+    its current value to a value of "red", over 1000 milliseconds:
+
+    \snippet doc/src/snippets/declarative/coloranimation.qml 0
+
+    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
+    for creating animations.
 
     When used in a transition, ColorAnimation will by default animate
-    all properties of type color that are changing. If a property or properties
-    are explicitly set for the animation, then those will be used instead.
+    all properties of type color that have changed. 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}
 */
 /*!
     \internal
@@ -648,7 +675,24 @@
 
 /*!
     \qmlproperty color ColorAnimation::from
-    This property holds the starting color.
+    This property holds the color value at which the animation should begin.
+
+    For example, the following animation is not applied until a color value
+    has reached "#c0c0c0":
+
+    \qml
+    Item {
+        states: [ ... ]
+
+        transition: Transition {
+            NumberAnimation { from: "#c0c0c0"; duration: 2000 }
+        }
+    }
+    \endqml
+
+    If this value is not set and the ColorAnimation is defined within
+    a \l Transition, it defaults to the value defined in the starting 
+    state of the \l Transition.
 */
 QColor QDeclarativeColorAnimation::from() const
 {
@@ -663,7 +707,12 @@
 
 /*!
     \qmlproperty color ColorAnimation::to
-    This property holds the ending color.
+
+    This property holds the color value at which the animation should end.
+
+    If this value is not set and the ColorAnimation is defined within
+    a \l Transition or \l Behavior, it defaults to the value defined in the end 
+    state of the \l Transition or \l Behavior.
 */
 QColor QDeclarativeColorAnimation::to() const
 {
@@ -832,18 +881,27 @@
     \inherits Animation
     \brief The PropertyAction element allows immediate property changes during animation.
 
-    Explicitly set \c theimage.smooth=true during a transition:
+    PropertyAction is used to specify an immediate property change
+    during an animation. The property change is not animated.
+
+    For example, to explicitly set \c {theImage.smooth = true} during a \l Transition:
     \code
-    PropertyAction { target: theimage; property: "smooth"; value: true }
+    transitions: Transition {
+        ...
+        PropertyAction { target: theImage; property: "smooth"; value: true }
+        ...
+    }
     \endcode
 
-    Set \c thewebview.url to the value set for the destination state:
+    Or, to set \c theWebView.url to the value set for the destination state:
     \code
-    PropertyAction { target: thewebview; property: "url" }
+    transitions: Transition {
+        ...
+        PropertyAction { target: theWebView; property: "url" }
+        ...
+    }
     \endcode
 
-    The PropertyAction is immediate -
-    the target property is not animated to the selected value in any way.
 
     \sa QtDeclarative
 */
@@ -869,14 +927,6 @@
     QDeclarative_setParent_noEvent(spa, q);
 }
 
-/*!
-    \qmlproperty Object PropertyAction::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 {QML Animation} documentation for details.
-*/
-
 QObject *QDeclarativePropertyAction::target() const
 {
     Q_D(const QDeclarativePropertyAction);
@@ -908,12 +958,12 @@
 }
 
 /*!
+    \qmlproperty Object PropertyAction::target
     \qmlproperty list<Object> PropertyAction::targets
     \qmlproperty string PropertyAction::property
     \qmlproperty string PropertyAction::properties
-    \qmlproperty Object PropertyAction::target
-
-    These properties are used as a set to determine which properties should be
+
+    These properties determine the items and their properties that are
     affected by this action.
 
     The details of how these properties are interpreted in different situations
@@ -945,7 +995,7 @@
 
 /*!
     \qmlproperty list<Object> PropertyAction::exclude
-    This property holds the objects not to be affected by this animation.
+    This property holds the objects that should not be affected by this action.
 
     \sa targets
 */
@@ -1080,13 +1130,27 @@
     \qmlclass NumberAnimation QDeclarativeNumberAnimation
     \since 4.7
     \inherits PropertyAnimation
-    \brief The NumberAnimation element allows you to animate changes in properties of type qreal.
-
-    Animate a set of properties over 200ms, from their values in the start state to
-    their values in the end state of the transition:
-    \code
-    NumberAnimation { properties: "x,y,scale"; duration: 200 }
-    \endcode
+    \brief The NumberAnimation element animates changes in qreal-type values.
+
+    NumberAnimation is a specialized PropertyAnimation that defines an 
+    animation to be applied when a numerical value changes.
+
+    Here is a NumberAnimation applied to the \c x property of a \l Rectangle 
+    as a property value source. It animates the \c x value from its current 
+    value to a value of 50, over 1000 milliseconds:
+
+    \snippet doc/src/snippets/declarative/numberanimation.qml 0
+
+    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
+    for creating animations.
+
+    Note that NumberAnimation may not animate smoothly if there are irregular
+    changes in the number value that it is tracking. If this is the case, use
+    SmoothedAnimation instead.
+
+    \sa {QML Animation}, {declarative/animation/basics}{Animation basics example}
 */
 
 /*!
@@ -1119,9 +1183,26 @@
 
 /*!
     \qmlproperty real NumberAnimation::from
-    This property holds the starting value.
-    If not set, then the value defined in the start state of the transition.
+    This property holds the starting number value.
+
+    For example, the following animation is not applied until the \c x value
+    has reached 100:
+
+    \qml
+    Item {
+        states: [ ... ]
+
+        transition: Transition {
+            NumberAnimation { properties: "x"; from: 100; duration: 200 }
+        }
+    }
+    \endqml
+
+    If this value is not set and the NumberAnimation is defined within
+    a \l Transition, it defaults to the value defined in the start 
+    state of the \l Transition.
 */
+
 qreal QDeclarativeNumberAnimation::from() const
 {
     Q_D(const QDeclarativePropertyAnimation);
@@ -1135,8 +1216,11 @@
 
 /*!
     \qmlproperty real NumberAnimation::to
-    This property holds the ending value.
-    If not set, then the value defined in the end state of the transition or Behavior.
+    This property holds the ending number value.
+
+    If this value is not set and the NumberAnimation is defined within
+    a \l Transition or \l Behavior, it defaults to the value defined in the end 
+    state of the \l Transition or \l Behavior.
 */
 qreal QDeclarativeNumberAnimation::to() const
 {
@@ -1155,7 +1239,12 @@
     \qmlclass Vector3dAnimation QDeclarativeVector3dAnimation
     \since 4.7
     \inherits PropertyAnimation
-    \brief The Vector3dAnimation element allows you to animate changes in properties of type QVector3d.
+    \brief The Vector3dAnimation element animates changes in QVector3d values.
+
+    Vector3dAnimation is a specialized PropertyAnimation that defines an 
+    animation to be applied when a Vector3d value changes.
+
+    \sa {QML Animation}, {declarative/animation/basics}{Animation basics example}
 */
 
 /*!
@@ -1179,7 +1268,9 @@
 /*!
     \qmlproperty real Vector3dAnimation::from
     This property holds the starting value.
-    If not set, then the value defined in the start state of the transition.
+
+    If this value is not set, it defaults to the value defined in the start 
+    state of the \l Transition.
 */
 QVector3D QDeclarativeVector3dAnimation::from() const
 {
@@ -1195,7 +1286,9 @@
 /*!
     \qmlproperty real Vector3dAnimation::to
     This property holds the ending value.
-    If not set, then the value defined in the end state of the transition or Behavior.
+
+    If this value is not set, it defaults to the value defined in the end 
+    state of the \l Transition or \l Behavior.
 */
 QVector3D QDeclarativeVector3dAnimation::to() const
 {
@@ -1214,30 +1307,34 @@
     \qmlclass RotationAnimation QDeclarativeRotationAnimation
     \since 4.7
     \inherits PropertyAnimation
-    \brief The RotationAnimation element allows you to animate rotations.
+    \brief The RotationAnimation element animates changes in rotation values.
 
     RotationAnimation is a specialized PropertyAnimation that gives control
-    over the direction of rotation. By default, it will rotate in the direction
+    over the direction of rotation during an animation. 
+
+    By default, it rotates in the direction
     of the numerical change; a rotation from 0 to 240 will rotate 220 degrees
     clockwise, while a rotation from 240 to 0 will rotate 220 degrees
-    counterclockwise.
-
-    When used in a transition RotationAnimation will rotate all
-    properties named "rotation" or "angle". You can override this by providing
-    your own properties via \c properties or \c property.
+    counterclockwise. The \l direction property can be set to specify the
+    direction in which the rotation should occur.
 
     In the following example we use RotationAnimation to animate the rotation
-    between states via the shortest path.
-    \qml
-    states: {
-        State { name: "180"; PropertyChanges { target: myItem; rotation: 180 } }
-        State { name: "90"; PropertyChanges { target: myItem; rotation: 90 } }
-        State { name: "-90"; PropertyChanges { target: myItem; rotation: -90 } }
-    }
-    transition: Transition {
-        RotationAnimation { direction: RotationAnimation.Shortest }
-    }
-    \endqml
+    between states via the shortest path:
+
+    \snippet doc/src/snippets/declarative/rotationanimation.qml 0
+    
+    Notice the RotationAnimation did not need to set a \l {RotationAnimation::}{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 
+    \l {PropertyAnimation::property}{property}.
+
+    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
+    for creating animations.
+
+    \sa {QML Animation}, {declarative/animation/basics}{Animation basics example}
 */
 
 /*!
@@ -1297,8 +1394,23 @@
 
 /*!
     \qmlproperty real RotationAnimation::from
-    This property holds the starting value.
-    If not set, then the value defined in the start state of the transition.
+    This property holds the starting number value.
+
+    For example, the following animation is not applied until the \c angle value
+    has reached 100:
+
+    \qml
+    Item {
+        states: [ ... ]
+
+        transition: Transition {
+            RotationAnimation { properties: "angle"; from: 100; duration: 2000 }
+        }
+    }
+    \endqml
+
+    If this value is not set, it defaults to the value defined in the start 
+    state of the \l Transition.
 */
 qreal QDeclarativeRotationAnimation::from() const
 {
@@ -1314,7 +1426,9 @@
 /*!
     \qmlproperty real RotationAnimation::to
     This property holds the ending value.
-    If not set, then the value defined in the end state of the transition or Behavior.
+
+    If this value is not set, it defaults to the value defined in the end 
+    state of the \l Transition or \l Behavior.
 */
 qreal QDeclarativeRotationAnimation::to() const
 {
@@ -1329,28 +1443,18 @@
 
 /*!
     \qmlproperty enumeration RotationAnimation::direction
-    The direction in which to rotate.
+    This property holds the direction of the rotation.
 
     Possible values are:
 
-    \table
-    \row
-        \o RotationAnimation.Numerical
-        \o Rotate by linearly interpolating between the two numbers.
+    \list
+    \o RotationAnimation.Numerical (default) - Rotate by linearly interpolating between the two numbers.
            A rotation from 10 to 350 will rotate 340 degrees clockwise.
-    \row
-        \o RotationAnimation.Clockwise
-        \o Rotate clockwise between the two values
-    \row
-        \o RotationAnimation.Counterclockwise
-        \o Rotate counterclockwise between the two values
-    \row
-        \o RotationAnimation.Shortest
-        \o Rotate in the direction that produces the shortest animation path.
+    \o RotationAnimation.Clockwise - Rotate clockwise between the two values
+    \o RotationAnimation.Counterclockwise - Rotate counterclockwise between the two values
+    \o RotationAnimation.Shortest - Rotate in the direction that produces the shortest animation path.
            A rotation from 10 to 350 will rotate 20 degrees counterclockwise.
-    \endtable
-
-    The default direction is RotationAnimation.Numerical.
+    \endlist
 */
 QDeclarativeRotationAnimation::RotationDirection QDeclarativeRotationAnimation::direction() const
 {
@@ -1432,21 +1536,28 @@
     \qmlclass SequentialAnimation QDeclarativeSequentialAnimation
     \since 4.7
     \inherits Animation
-    \brief The SequentialAnimation element allows you to run animations sequentially.
-
-    Animations controlled in SequentialAnimation will be run one after the other.
-
-    The following example chains two numeric animations together.  The \c MyItem
-    object will animate from its current x position to 100, and then back to 0.
-
-    \code
-    SequentialAnimation {
-        NumberAnimation { target: MyItem; property: "x"; to: 100 }
-        NumberAnimation { target: MyItem; property: "x"; to: 0 }
-    }
-    \endcode
-
-    \sa ParallelAnimation
+    \brief The SequentialAnimation element allows animations to be run sequentially.
+
+    The SequentialAnimation and ParallelAnimation elements allow multiple
+    animations to be run together. Animations defined in a SequentialAnimation
+    are run one after the other, while animations defined in a ParallelAnimation
+    are run at the same time.
+
+    The following example runs two number animations in a sequence.  The \l Rectangle
+    animates to a \c x position of 50, then to a \c y position of 50.
+
+    \snippet doc/src/snippets/declarative/sequentialanimation.qml 0
+
+    Animations defined within a \l Transition are automatically run in parallel,
+    so SequentialAnimation can be used to enclose the animations in a \l Transition
+    if this is the preferred behavior.
+
+    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
+    for creating animations.
+
+    \sa ParallelAnimation, {QML Animation}, {declarative/animation/basics}{Animation basics example}
 */
 
 QDeclarativeSequentialAnimation::QDeclarativeSequentialAnimation(QObject *parent) :
@@ -1494,21 +1605,24 @@
     \qmlclass ParallelAnimation QDeclarativeParallelAnimation
     \since 4.7
     \inherits Animation
-    \brief The ParallelAnimation element allows you to run animations in parallel.
-
-    Animations contained in ParallelAnimation will be run at the same time.
-
-    The following animation demonstrates animating the \c MyItem item
-    to (100,100) by animating the x and y properties in parallel.
-
-    \code
-    ParallelAnimation {
-        NumberAnimation { target: MyItem; property: "x"; to: 100 }
-        NumberAnimation { target: MyItem; property: "y"; to: 100 }
-    }
-    \endcode
-
-    \sa SequentialAnimation
+    \brief The ParallelAnimation element allows animations to be run in parallel.
+
+    The SequentialAnimation and ParallelAnimation elements allow multiple
+    animations to be run together. Animations defined in a SequentialAnimation
+    are run one after the other, while animations defined in a ParallelAnimation
+    are run at the same time.
+
+    The following animation runs two number animations in parallel. The \l Rectangle
+    moves to (50,50) by animating its \c x and \c y properties at the same time.
+
+    \snippet doc/src/snippets/declarative/parallelanimation.qml 0
+
+    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
+    for creating animations.
+
+    \sa SequentialAnimation, {QML Animation}, {declarative/animation/basics}{Animation basics example}
 */
 /*!
     \internal
@@ -1605,58 +1719,61 @@
     \qmlclass PropertyAnimation QDeclarativePropertyAnimation
     \since 4.7
     \inherits Animation
-    \brief The PropertyAnimation element allows you to animate property changes.
-
-    PropertyAnimation provides a way to animate changes to a property's value. It can
-    be used in many different situations:
+    \brief The PropertyAnimation element animates changes in property values.
+
+    PropertyAnimation provides a way to animate changes to a property's value. 
+
+    It can be used to define animations in a number of ways:
+   
     \list
-    \o In a Transition
-
-    Animate any objects that have changed their x or y properties in the target state using
-    an InOutQuad easing curve:
-    \qml
-    Transition { PropertyAnimation { properties: "x,y"; easing.type: Easing.InOutQuad } }
-    \endqml
-    \o In a Behavior
-
-    Animate all changes to a rectangle's x property.
-    \qml
-    Rectangle {
-        Behavior on x { PropertyAnimation {} }
-    }
-    \endqml
+    \o In a \l Transition
+
+    For example, to animate any objects that have changed their \c x or \c y properties 
+    as a result of a state change, using an \c InOutQuad easing curve:
+
+    \snippet doc/src/snippets/declarative/propertyanimation.qml transition
+
+
+    \o In a \l Behavior
+
+    For example, to animate all changes to a rectangle's \c x property:
+
+    \snippet doc/src/snippets/declarative/propertyanimation.qml behavior
+
+
     \o As a property value source
 
-    Repeatedly animate the rectangle's x property.
-    \qml
-    Rectangle {
-        SequentialAnimation on x {
-            loops: Animation.Infinite
-            PropertyAnimation { to: 50 }
-            PropertyAnimation { to: 0 }
-        }
-    }
-    \endqml
+    For example, to repeatedly animate the rectangle's \c x property:
+
+    \snippet doc/src/snippets/declarative/propertyanimation.qml propertyvaluesource
+
+
     \o In a signal handler
 
-    Fade out \c theObject when clicked:
+    For example, to fade out \c theObject when clicked:
     \qml
     MouseArea {
         anchors.fill: theObject
         onClicked: PropertyAnimation { target: theObject; property: "opacity"; to: 0 }
     }
     \endqml
+
     \o Standalone
 
-    Animate \c theObject's size property over 200ms, from its current size to 20-by-20:
-    \qml
-    PropertyAnimation { target: theObject; property: "size"; to: "20x20"; duration: 200 }
-    \endqml
+    For example, to animate \c rect's \c width property over 500ms, from its current width to 30:
+
+    \snippet doc/src/snippets/declarative/propertyanimation.qml standalone
+
     \endlist
 
     Depending on how the animation is used, the set of properties normally used will be
     different. For more information see the individual property documentation, as well
     as the \l{QML Animation} introduction.
+
+    Note that PropertyAnimation inherits the abstract \l Animation element.
+    This includes additional properties and methods for controlling the animation.
+
+    \sa {QML Animation}, {declarative/animation/basics}{Animation basics example}
 */
 
 QDeclarativePropertyAnimation::QDeclarativePropertyAnimation(QObject *parent)
@@ -1734,7 +1851,7 @@
 /*!
     \qmlproperty real PropertyAnimation::to
     This property holds the ending value.
-    If not set, then the value defined in the end state of the transition or Behavior.
+    If not set, then the value defined in the end state of the transition or \l Behavior.
 */
 QVariant QDeclarativePropertyAnimation::to() const
 {
@@ -1761,7 +1878,7 @@
 
     To specify an easing curve you need to specify at least the type. For some curves you can also specify
     amplitude, period and/or overshoot (more details provided after the table). The default easing curve is
-    Linear.
+    \c Easing.Linear.
 
     \qml
     PropertyAnimation { properties: "y"; easing.type: Easing.InOutElastic; easing.amplitude: 2.0; easing.period: 1.5 }
@@ -1938,15 +2055,15 @@
         \o \inlineimage qeasingcurve-outinbounce.png
     \endtable
 
-    easing.amplitude is only applicable for bounce and elastic curves (curves of type
-    Easing.InBounce, Easing.OutBounce, Easing.InOutBounce, Easing.OutInBounce, Easing.InElastic,
-    Easing.OutElastic, Easing.InOutElastic or Easing.OutInElastic).
-
-    easing.overshoot is only applicable if type is: Easing.InBack, Easing.OutBack,
-    Easing.InOutBack or Easing.OutInBack.
-
-    easing.period is only applicable if type is: Easing.InElastic, Easing.OutElastic,
-    Easing.InOutElastic or Easing.OutInElastic.
+    \c easing.amplitude is only applicable for bounce and elastic curves (curves of type
+    \c Easing.InBounce, \c Easing.OutBounce, \c Easing.InOutBounce, \c Easing.OutInBounce, \c Easing.InElastic,
+    \c Easing.OutElastic, \c Easing.InOutElastic or \c Easing.OutInElastic).
+
+    \c easing.overshoot is only applicable if \c easing.type is: \c Easing.InBack, \c Easing.OutBack,
+    \c Easing.InOutBack or \c Easing.OutInBack.
+
+    \c easing.period is only applicable if easing.type is: \c Easing.InElastic, \c Easing.OutElastic,
+    \c Easing.InOutElastic or \c Easing.OutInElastic.
 
     See the \l {declarative/animation/easing}{easing} example for a demonstration of
     the different easing settings.
@@ -1954,17 +2071,16 @@
 QEasingCurve QDeclarativePropertyAnimation::easing() const
 {
     Q_D(const QDeclarativePropertyAnimation);
-    return d->easing;
+    return d->va->easingCurve();
 }
 
 void QDeclarativePropertyAnimation::setEasing(const QEasingCurve &e)
 {
     Q_D(QDeclarativePropertyAnimation);
-    if (d->easing == e)
+    if (d->va->easingCurve() == e)
         return;
 
-    d->easing = e;
-    d->va->setEasingCurve(d->easing);
+    d->va->setEasingCurve(e);
     emit easingChanged(e);
 }
 
@@ -2032,8 +2148,9 @@
     The singular forms are slightly optimized, so if you do have only a single target/property
     to animate you should try to use them.
 
-    In many cases these properties do not need to be explicitly specified -- they can be
-    inferred from the animation framework.
+    In many cases these properties do not need to be explicitly specified, as they can be
+    inferred from the animation framework:
+
     \table 80%
     \row
     \o Value Source / Behavior
@@ -2119,52 +2236,39 @@
     return d->va;
 }
 
-struct PropertyUpdater : public QDeclarativeBulkValueUpdater
+void QDeclarativeAnimationPropertyUpdater::setValue(qreal v)
 {
-    QDeclarativeStateActions actions;
-    int interpolatorType;       //for Number/ColorAnimation
-    int prevInterpolatorType;   //for generic
-    QVariantAnimation::Interpolator interpolator;
-    bool reverse;
-    bool fromSourced;
-    bool fromDefined;
-    bool *wasDeleted;
-    PropertyUpdater() : prevInterpolatorType(0), wasDeleted(0) {}
-    ~PropertyUpdater() { if (wasDeleted) *wasDeleted = true; }
-    void setValue(qreal v)
-    {
-        bool deleted = false;
-        wasDeleted = &deleted;
-        if (reverse)    //QVariantAnimation sends us 1->0 when reversed, but we are expecting 0->1
-            v = 1 - v;
-        for (int ii = 0; ii < actions.count(); ++ii) {
-            QDeclarativeAction &action = actions[ii];
-
-            if (v == 1.)
-                QDeclarativePropertyPrivate::write(action.property, action.toValue, QDeclarativePropertyPrivate::BypassInterceptor | QDeclarativePropertyPrivate::DontRemoveBinding);
-            else {
-                if (!fromSourced && !fromDefined) {
-                    action.fromValue = action.property.read();
-                    if (interpolatorType)
-                        QDeclarativePropertyAnimationPrivate::convertVariant(action.fromValue, interpolatorType);
+    bool deleted = false;
+    wasDeleted = &deleted;
+    if (reverse)    //QVariantAnimation sends us 1->0 when reversed, but we are expecting 0->1
+        v = 1 - v;
+    for (int ii = 0; ii < actions.count(); ++ii) {
+        QDeclarativeAction &action = actions[ii];
+
+        if (v == 1.)
+            QDeclarativePropertyPrivate::write(action.property, action.toValue, QDeclarativePropertyPrivate::BypassInterceptor | QDeclarativePropertyPrivate::DontRemoveBinding);
+        else {
+            if (!fromSourced && !fromDefined) {
+                action.fromValue = action.property.read();
+                if (interpolatorType)
+                    QDeclarativePropertyAnimationPrivate::convertVariant(action.fromValue, interpolatorType);
+            }
+            if (!interpolatorType) {
+                int propType = action.property.propertyType();
+                if (!prevInterpolatorType || prevInterpolatorType != propType) {
+                    prevInterpolatorType = propType;
+                    interpolator = QVariantAnimationPrivate::getInterpolator(prevInterpolatorType);
                 }
-                if (!interpolatorType) {
-                    int propType = action.property.propertyType();
-                    if (!prevInterpolatorType || prevInterpolatorType != propType) {
-                        prevInterpolatorType = propType;
-                        interpolator = QVariantAnimationPrivate::getInterpolator(prevInterpolatorType);
-                    }
-                }
-                if (interpolator)
-                    QDeclarativePropertyPrivate::write(action.property, interpolator(action.fromValue.constData(), action.toValue.constData(), v), QDeclarativePropertyPrivate::BypassInterceptor | QDeclarativePropertyPrivate::DontRemoveBinding);
             }
-            if (deleted)
-                return;
+            if (interpolator)
+                QDeclarativePropertyPrivate::write(action.property, interpolator(action.fromValue.constData(), action.toValue.constData(), v), QDeclarativePropertyPrivate::BypassInterceptor | QDeclarativePropertyPrivate::DontRemoveBinding);
         }
-        wasDeleted = 0;
-        fromSourced = true;
+        if (deleted)
+            return;
     }
-};
+    wasDeleted = 0;
+    fromSourced = true;
+}
 
 void QDeclarativePropertyAnimation::transition(QDeclarativeStateActions &actions,
                                      QDeclarativeProperties &modified,
@@ -2194,7 +2298,7 @@
         props << d->defaultProperties.split(QLatin1Char(','));
     }
 
-    PropertyUpdater *data = new PropertyUpdater;
+    QDeclarativeAnimationPropertyUpdater *data = new QDeclarativeAnimationPropertyUpdater;
     data->interpolatorType = d->interpolatorType;
     data->interpolator = d->interpolator;
     data->reverse = direction == Backward ? true : false;
@@ -2282,43 +2386,32 @@
     \qmlclass ParentAnimation QDeclarativeParentAnimation
     \since 4.7
     \inherits Animation
-    \brief The ParentAnimation element allows you to animate parent changes.
-
-    ParentAnimation is used in conjunction with NumberAnimation to smoothly
-    animate changing an item's parent. In the following example,
-    ParentAnimation wraps a NumberAnimation which animates from the
-    current position in the old parent to the new position in the new
-    parent.
-
-    \qml
-    ...
-    State {
-        //reparent myItem to newParent. myItem's final location
-        //should be 10,10 in newParent.
-        ParentChange {
-            target: myItem
-            parent: newParent
-            x: 10; y: 10
-        }
-    }
-    ...
-    Transition {
-        //smoothly reparent myItem and move into new position
-        ParentAnimation {
-            target: theItem
-            NumberAnimation { properties: "x,y" }
-        }
-    }
-    \endqml
-
-    ParentAnimation can wrap any number of animations -- those animations will
-    be run in parallel (like those in a ParallelAnimation group).
-
-    In some cases, such as reparenting between items with clipping, it's useful
-    to animate the parent change via another item with no clipping.
-
-    When used in a transition, ParentAnimation will by default animate
-    all ParentChanges.
+    \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.
+
+    For example, the following ParentChange changes \c blueRect to become
+    a child of \c redRect when it is clicked. The inclusion of the 
+    ParentAnimation, which defines a NumberAnimation to be applied during
+    the transition, ensures the item animates smoothly as it moves to
+    its new parent:
+
+    \snippet doc/src/snippets/declarative/parentanimation.qml 0
+
+    A ParentAnimation can contain any number of animations. These animations will
+    be run in parallel; to run them sequentially, define them within a
+    SequentialAnimation.
+
+    In some cases, such as when reparenting between items with clipping enabled, it is useful
+    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 overriden by setting a specific target item using the
+    \l target property.
+
+    \sa {QML Animation}, {declarative/animation/basics}{Animation basics example}
 */
 
 /*!
@@ -2353,8 +2446,8 @@
     \qmlproperty Item ParentAnimation::target
     The item to reparent.
 
-    When used in a transition, if no target is specified all
-    ParentChanges will be animated by the ParentAnimation.
+    When used in a transition, if no target is specified, all
+    ParentChange occurrences are animated by the ParentAnimation.
 */
 QDeclarativeItem *QDeclarativeParentAnimation::target() const
 {
@@ -2397,7 +2490,7 @@
 /*!
     \qmlproperty Item ParentAnimation::via
     The item to reparent via. This provides a way to do an unclipped animation
-    when both the old parent and new parent are clipped
+    when both the old parent and new parent are clipped.
 
     \qml
     ParentAnimation {
@@ -2647,28 +2740,14 @@
     \qmlclass AnchorAnimation QDeclarativeAnchorAnimation
     \since 4.7
     \inherits Animation
-    \brief The AnchorAnimation element allows you to animate anchor changes.
-
-    AnchorAnimation will animated any changes specified by a state's AnchorChanges.
-    In the following snippet we animate the addition of a right anchor to our item.
-    \qml
-    Item {
-        id: myItem
-        width: 100
-    }
-    ...
-    State {
-        AnchorChanges {
-            target: myItem
-            anchors.right: container.right
-        }
-    }
-    ...
-    Transition {
-        //smoothly reanchor myItem and move into new position
-        AnchorAnimation {}
-    }
-    \endqml
+    \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.
+
+    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
 */
@@ -2771,7 +2850,7 @@
 {
     Q_UNUSED(modified);
     Q_D(QDeclarativeAnchorAnimation);
-    PropertyUpdater *data = new PropertyUpdater;
+    QDeclarativeAnimationPropertyUpdater *data = new QDeclarativeAnimationPropertyUpdater;
     data->interpolatorType = QMetaType::QReal;
     data->interpolator = d->interpolator;