various doc improvements for animation elements

12 files changed, 445 insertions, 188 deletions

diff --git a/doc/src/snippets/declarative/behavior.qml b/doc/src/snippets/declarative/behavior.qml
new file mode 100644
index 0000000..420dfc4
--- /dev/null
+++ b/doc/src/snippets/declarative/behavior.qml
@@ -0,0 +1,59 @@
+/****************************************************************************
+**
+** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).
+** All rights reserved.
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** This file is part of the QtDeclarative module of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:LGPL$
+** No Commercial Usage
+** This file contains pre-release code and may not be distributed.
+** You may use this file in accordance with the terms and conditions
+** contained in the Technology Preview License Agreement accompanying
+** this package.
+**
+** GNU Lesser General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU Lesser
+** General Public License version 2.1 as published by the Free Software
+** Foundation and appearing in the file LICENSE.LGPL included in the
+** packaging of this file.  Please review the following information to
+** ensure the GNU Lesser General Public License version 2.1 requirements
+** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
+**
+** In addition, as a special exception, Nokia gives you certain additional
+** rights.  These rights are described in the Nokia Qt LGPL Exception
+** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
+**
+** If you have questions regarding the use of this file, please contact
+** Nokia at qt-info@nokia.com.
+**
+**
+**
+**
+**
+**
+**
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+//![0]
+import Qt 4.7
+
+Rectangle {
+    id: rect
+    width: 100; height: 100
+    color: "red"
+
+    Behavior on width {
+        NumberAnimation { duration: 1000 }
+    }
+
+    MouseArea {
+        anchors.fill: parent
+        onClicked: rect.width = 50
+    }
+}
+//![0]
diff --git a/doc/src/snippets/declarative/parallelanimation.qml b/doc/src/snippets/declarative/parallelanimation.qml
new file mode 100644
index 0000000..d823b4f
--- /dev/null
+++ b/doc/src/snippets/declarative/parallelanimation.qml
@@ -0,0 +1,57 @@
+/****************************************************************************
+**
+** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).
+** All rights reserved.
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** This file is part of the QtDeclarative module of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:LGPL$
+** No Commercial Usage
+** This file contains pre-release code and may not be distributed.
+** You may use this file in accordance with the terms and conditions
+** contained in the Technology Preview License Agreement accompanying
+** this package.
+**
+** GNU Lesser General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU Lesser
+** General Public License version 2.1 as published by the Free Software
+** Foundation and appearing in the file LICENSE.LGPL included in the
+** packaging of this file.  Please review the following information to
+** ensure the GNU Lesser General Public License version 2.1 requirements
+** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
+**
+** In addition, as a special exception, Nokia gives you certain additional
+** rights.  These rights are described in the Nokia Qt LGPL Exception
+** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
+**
+** If you have questions regarding the use of this file, please contact
+** Nokia at qt-info@nokia.com.
+**
+**
+**
+**
+**
+**
+**
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+//![0]
+import Qt 4.7
+
+Rectangle {
+    id: rect
+    width: 100; height: 100
+    color: "red"
+
+    ParallelAnimation {
+        running: true
+        NumberAnimation { target: rect; property: "x"; to: 50; duration: 1000 }
+        NumberAnimation { target: rect; property: "y"; to: 50; duration: 1000 }
+    }
+}
+//![0]
+
diff --git a/doc/src/snippets/declarative/parentchange.qml b/doc/src/snippets/declarative/parentchange.qml
index 7f5718a..ea50832 100644
--- a/doc/src/snippets/declarative/parentchange.qml
+++ b/doc/src/snippets/declarative/parentchange.qml
@@ -41,9 +41,8 @@
 //![0]
 import Qt 4.7
 
-Rectangle {
-    width: 200
-    height: 100
+Item {
+    width: 200; height: 100
 
     Rectangle { 
         id: redRect
diff --git a/doc/src/snippets/declarative/rotationanimation.qml b/doc/src/snippets/declarative/rotationanimation.qml
new file mode 100644
index 0000000..c81395a
--- /dev/null
+++ b/doc/src/snippets/declarative/rotationanimation.qml
@@ -0,0 +1,66 @@
+/****************************************************************************
+**
+** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).
+** All rights reserved.
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** This file is part of the QtDeclarative module of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:LGPL$
+** No Commercial Usage
+** This file contains pre-release code and may not be distributed.
+** You may use this file in accordance with the terms and conditions
+** contained in the Technology Preview License Agreement accompanying
+** this package.
+**
+** GNU Lesser General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU Lesser
+** General Public License version 2.1 as published by the Free Software
+** Foundation and appearing in the file LICENSE.LGPL included in the
+** packaging of this file.  Please review the following information to
+** ensure the GNU Lesser General Public License version 2.1 requirements
+** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
+**
+** In addition, as a special exception, Nokia gives you certain additional
+** rights.  These rights are described in the Nokia Qt LGPL Exception
+** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
+**
+** If you have questions regarding the use of this file, please contact
+** Nokia at qt-info@nokia.com.
+**
+**
+**
+**
+**
+**
+**
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+//![0]
+import Qt 4.7
+
+Item {
+    width: 300; height: 300
+
+    Rectangle {
+        id: rect
+        width: 150; height: 100; anchors.centerIn: parent
+        color: "red"
+        smooth: true
+
+        states: State { 
+            name: "rotated"; PropertyChanges { target: rect; rotation: 180 } 
+        }
+
+        transitions: Transition {
+            RotationAnimation { duration: 1000; direction: RotationAnimation.Counterclockwise }
+        }
+    }
+
+    MouseArea { anchors.fill: parent; onClicked: rect.state = "rotated" }
+}
+//![0]
+
diff --git a/doc/src/snippets/declarative/sequentialanimation.qml b/doc/src/snippets/declarative/sequentialanimation.qml
new file mode 100644
index 0000000..a15f7f3
--- /dev/null
+++ b/doc/src/snippets/declarative/sequentialanimation.qml
@@ -0,0 +1,57 @@
+/****************************************************************************
+**
+** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).
+** All rights reserved.
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** This file is part of the QtDeclarative module of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:LGPL$
+** No Commercial Usage
+** This file contains pre-release code and may not be distributed.
+** You may use this file in accordance with the terms and conditions
+** contained in the Technology Preview License Agreement accompanying
+** this package.
+**
+** GNU Lesser General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU Lesser
+** General Public License version 2.1 as published by the Free Software
+** Foundation and appearing in the file LICENSE.LGPL included in the
+** packaging of this file.  Please review the following information to
+** ensure the GNU Lesser General Public License version 2.1 requirements
+** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
+**
+** In addition, as a special exception, Nokia gives you certain additional
+** rights.  These rights are described in the Nokia Qt LGPL Exception
+** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
+**
+** If you have questions regarding the use of this file, please contact
+** Nokia at qt-info@nokia.com.
+**
+**
+**
+**
+**
+**
+**
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+//![0]
+import Qt 4.7
+
+Rectangle {
+    id: rect
+    width: 100; height: 100
+    color: "red"
+
+    SequentialAnimation {
+        running: true
+        NumberAnimation { target: rect; property: "x"; to: 50; duration: 1000 }
+        NumberAnimation { target: rect; property: "y"; to: 50; duration: 1000 }
+    }
+}
+//![0]
+
diff --git a/doc/src/snippets/declarative/springanimation.qml b/doc/src/snippets/declarative/springanimation.qml
index b73a9d2..8e810e1 100644
--- a/doc/src/snippets/declarative/springanimation.qml
+++ b/doc/src/snippets/declarative/springanimation.qml
@@ -41,7 +41,7 @@
 //![0]
 import Qt 4.7
 
-Rectangle {
+Item {
     width: 300; height: 300
 
     Rectangle {
@@ -56,8 +56,8 @@ Rectangle {
     MouseArea {
         anchors.fill: parent
         onClicked: {
-            rect.x = mouse.x
-            rect.y = mouse.y
+            rect.x = mouse.x - rect.width/2
+            rect.y = mouse.y - rect.height/2
         }
     }
 }
diff --git a/src/declarative/qml/qdeclarativeengine.cpp b/src/declarative/qml/qdeclarativeengine.cpp
index f2eb770..d1ba6ce 100644
--- a/src/declarative/qml/qdeclarativeengine.cpp
+++ b/src/declarative/qml/qdeclarativeengine.cpp
@@ -1080,13 +1080,20 @@ Here is an example. Notice it checks whether the component \l{Component::status}
 \c Component.Ready before calling \l {Component::createObject()}{createObject()}
 in case the QML file is loaded over a network and thus is not ready immediately.
 
-\snippet doc/src/snippets/declarative/componentCreation.js 0
+\snippet doc/src/snippets/declarative/componentCreation.js vars
 \codeline
-\snippet doc/src/snippets/declarative/componentCreation.js 1
+\snippet doc/src/snippets/declarative/componentCreation.js func
+\snippet doc/src/snippets/declarative/componentCreation.js remote
+\snippet doc/src/snippets/declarative/componentCreation.js func-end
+\codeline
+\snippet doc/src/snippets/declarative/componentCreation.js finishCreation
 
-If you are certain the files will be local, you could simplify to:
+If you are certain the QML file to be loaded is a local file, you could omit the \c finishCreation() 
+function and call \l {Component::createObject()}{createObject()} immediately:
 
-\snippet doc/src/snippets/declarative/componentCreation.js 2
+\snippet doc/src/snippets/declarative/componentCreation.js func
+\snippet doc/src/snippets/declarative/componentCreation.js local
+\snippet doc/src/snippets/declarative/componentCreation.js func-end
 
 To create a QML object from an arbitrary string of QML (instead of a file),
 use \l{QML:Qt::createQmlObject()}{Qt.createQmlObject()}.
diff --git a/src/declarative/util/qdeclarativeanimation.cpp b/src/declarative/util/qdeclarativeanimation.cpp
index 88ec5ba..3617031 100644
--- a/src/declarative/util/qdeclarativeanimation.cpp
+++ b/src/declarative/util/qdeclarativeanimation.cpp
@@ -632,17 +632,18 @@ QAbstractAnimation *QDeclarativePauseAnimation::qtAnimation()
     \qmlclass ColorAnimation QDeclarativeColorAnimation
     \since 4.7
     \inherits PropertyAnimation
-    \brief The ColorAnimation element allows you to animate color changes.
+    \brief The ColorAnimation element animates changes in color values.
 
-    ColorAnimation defines an animation to be applied when a color value 
-    changes.
+    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:
+    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 NumberAnimation can be applied in a
+    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.
@@ -674,11 +675,12 @@ QDeclarativeColorAnimation::~QDeclarativeColorAnimation()
 
 /*!
     \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: [ ... ]
 
@@ -686,6 +688,11 @@ QDeclarativeColorAnimation::~QDeclarativeColorAnimation()
             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
 {
@@ -700,7 +707,12 @@ void QDeclarativeColorAnimation::setFrom(const QColor &f)
 
 /*!
     \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
 {
@@ -869,18 +881,27 @@ QAbstractAnimation *QDeclarativeScriptAction::qtAnimation()
     \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
 */
@@ -906,14 +927,6 @@ void QDeclarativePropertyActionPrivate::init()
     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);
@@ -945,12 +958,12 @@ void QDeclarativePropertyAction::setProperty(const QString &n)
 }
 
 /*!
+    \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
@@ -982,7 +995,7 @@ QDeclarativeListProperty<QObject> QDeclarativePropertyAction::targets()
 
 /*!
     \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
 */
@@ -1117,13 +1130,14 @@ void QDeclarativePropertyAction::transition(QDeclarativeStateActions &actions,
     \qmlclass NumberAnimation QDeclarativeNumberAnimation
     \since 4.7
     \inherits PropertyAnimation
-    \brief The NumberAnimation element allows you to animate changes in properties of type qreal.
+    \brief The NumberAnimation element animates changes in qreal-type values.
 
-    NumberAnimation defines an animation to be applied when a numerical value 
-    changes.
+    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:
+    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
 
@@ -1174,6 +1188,7 @@ void QDeclarativeNumberAnimation::init()
     For example, the following animation is not applied until the \c x value
     has reached 100:
 
+    \qml
     Item {
         states: [ ... ]
 
@@ -1181,8 +1196,10 @@ void QDeclarativeNumberAnimation::init()
             NumberAnimation { properties: "x"; from: 100; duration: 200 }
         }
     }
+    \endqml
 
-    If this value is not set, it defaults to the value defined in the start 
+    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.
 */
 
@@ -1201,7 +1218,8 @@ void QDeclarativeNumberAnimation::setFrom(qreal f)
     \qmlproperty real NumberAnimation::to
     This property holds the ending number value.
 
-    If this value is not set, it defaults to the value defined in the end 
+    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
@@ -1221,7 +1239,10 @@ void QDeclarativeNumberAnimation::setTo(qreal t)
     \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}
 */
@@ -1286,31 +1307,32 @@ void QDeclarativeVector3dAnimation::setTo(QVector3D t)
     \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.
+    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:
 
-    When used in a transition RotationAnimation will rotate all
+    \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}.
 
-    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
+    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}
 */
@@ -1377,6 +1399,7 @@ QDeclarativeRotationAnimation::~QDeclarativeRotationAnimation()
     For example, the following animation is not applied until the \c angle value
     has reached 100:
 
+    \qml
     Item {
         states: [ ... ]
 
@@ -1384,6 +1407,7 @@ QDeclarativeRotationAnimation::~QDeclarativeRotationAnimation()
             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.
@@ -1419,7 +1443,7 @@ void QDeclarativeRotationAnimation::setTo(qreal t)
 
 /*!
     \qmlproperty enumeration RotationAnimation::direction
-    The direction in which to rotate.
+    This property holds the direction of the rotation.
 
     Possible values are:
 
@@ -1512,19 +1536,26 @@ QDeclarativeListProperty<QDeclarativeAbstractAnimation> QDeclarativeAnimationGro
     \qmlclass SequentialAnimation QDeclarativeSequentialAnimation
     \since 4.7
     \inherits Animation
-    \brief The SequentialAnimation element allows you to run animations sequentially.
+    \brief The SequentialAnimation element allows animations to be run sequentially.
 
-    Animations controlled in SequentialAnimation will be run one after the other.
+    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 chains two numeric animations together.  The \c MyItem
-    object will animate from its current x position to 100, and then back to 0.
+    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.
 
-    \code
-    SequentialAnimation {
-        NumberAnimation { target: MyItem; property: "x"; to: 100 }
-        NumberAnimation { target: MyItem; property: "x"; to: 0 }
-    }
-    \endcode
+    \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}
 */
@@ -1574,19 +1605,22 @@ void QDeclarativeSequentialAnimation::transition(QDeclarativeStateActions &actio
     \qmlclass ParallelAnimation QDeclarativeParallelAnimation
     \since 4.7
     \inherits Animation
-    \brief The ParallelAnimation element allows you to run animations in parallel.
+    \brief The ParallelAnimation element allows animations to be run in parallel.
 
-    Animations contained in ParallelAnimation will be run at the same time.
+    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 demonstrates animating the \c MyItem item
-    to (100,100) by animating the x and y properties in parallel.
+    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.
 
-    \code
-    ParallelAnimation {
-        NumberAnimation { target: MyItem; property: "x"; to: 100 }
-        NumberAnimation { target: MyItem; property: "y"; to: 100 }
-    }
-    \endcode
+    \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}
 */
@@ -1685,7 +1719,7 @@ void QDeclarativePropertyAnimationPrivate::convertVariant(QVariant &variant, int
     \qmlclass PropertyAnimation QDeclarativePropertyAnimation
     \since 4.7
     \inherits Animation
-    \brief The PropertyAnimation element allows you to animate property changes.
+    \brief The PropertyAnimation element animates changes in property values.
 
     PropertyAnimation provides a way to animate changes to a property's value. 
 
@@ -2353,43 +2387,30 @@ void QDeclarativePropertyAnimation::transition(QDeclarativeStateActions &actions
     \qmlclass ParentAnimation QDeclarativeParentAnimation
     \since 4.7
     \inherits Animation
-    \brief The ParentAnimation element allows you to animate parent changes.
+    \brief The ParentAnimation element animates changes in parent values.
 
-    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.
+    ParentAnimation defines an animation to applied when a ParentChange
+    occurs. This allows parent changes to be smoothly animated.
 
-    \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
+    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
 
-    ParentAnimation can wrap any number of animations -- those animations will
-    be run in parallel (like those in a ParallelAnimation group).
+    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 reparenting between items with clipping, it's useful
-    to animate the parent change via another item with no clipping.
+    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.
 
-    When used in a transition, ParentAnimation will by default animate
-    all ParentChanges.
+    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}
 */
@@ -2426,8 +2447,8 @@ QDeclarativeParentAnimation::~QDeclarativeParentAnimation()
     \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
 {
@@ -2470,7 +2491,7 @@ void QDeclarativeParentAnimation::setNewParent(QDeclarativeItem *newParent)
 /*!
     \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 {
@@ -2720,28 +2741,14 @@ QAbstractAnimation *QDeclarativeParentAnimation::qtAnimation()
     \qmlclass AnchorAnimation QDeclarativeAnchorAnimation
     \since 4.7
     \inherits Animation
-    \brief The AnchorAnimation element allows you to animate anchor changes.
+    \brief The AnchorAnimation element animates changes in anchor values.
 
-    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
+    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
 */
diff --git a/src/declarative/util/qdeclarativebehavior.cpp b/src/declarative/util/qdeclarativebehavior.cpp
index 2bb28c3..3719085 100644
--- a/src/declarative/util/qdeclarativebehavior.cpp
+++ b/src/declarative/util/qdeclarativebehavior.cpp
@@ -75,28 +75,21 @@ public:
     \since 4.7
     \brief The Behavior element allows you to specify a default animation for a property change.
 
-    Behaviors provide one way to specify \l{qdeclarativeanimation.html}{animations} in QML.
-
-    In the example below, the rectangle will use a bounce easing curve over 200 millisecond for any changes to its y property:
-    \code
-    Rectangle {
-        width: 20; height: 20
-        color: "#00ff00"
-        y: 200  // initial value
-        Behavior on y {
-            NumberAnimation {
-                easing.type: Easing.OutBounce
-                easing.amplitude: 100
-                duration: 200
-            }
-        }
-    }
-    \endcode
+    A Behavior defines the default animation to be applied whenever a 
+    particular property value changes.
+
+    For example, the following Behavior defines a NumberAnimation to be run
+    whenever the \l Rectangle's \c width value changes. When the MouseArea
+    is clicked, the \c width is changed, triggering the behavior's animation:
+
+    \snippet doc/src/snippets/declarative/behavior.qml 0
 
-    Currently only a single Behavior may be specified for a property;
-    this Behavior can be enabled and disabled via the \l{enabled} property.
+    To run multiple animations within a Behavior, use ParallelAnimation or
+    SequentialAnimation.
 
-    \sa {declarative/animation/behaviors}{Behavior example}, QtDeclarative
+    Note that a property cannot have more than one assigned Behavior.
+
+    \sa {Property Behaviors}, {declarative/animation/behaviors}{Behavior example}, QtDeclarative
 */
 
 
@@ -113,7 +106,7 @@ QDeclarativeBehavior::~QDeclarativeBehavior()
     \qmlproperty Animation Behavior::animation
     \default
 
-    The animation to use when the behavior is triggered.
+    This property holds the animation to run when the behavior is triggered.
 */
 
 QDeclarativeAbstractAnimation *QDeclarativeBehavior::animation()
@@ -152,7 +145,9 @@ void QDeclarativeBehavior::qtAnimationStateChanged(QAbstractAnimation::State new
 
 /*!
     \qmlproperty bool Behavior::enabled
-    Whether the Behavior will be triggered when the property it is tracking changes.
+
+    This property holds whether the behavior will be triggered when the tracked
+    property changes value.
 
     By default a Behavior is enabled.
 */
diff --git a/src/declarative/util/qdeclarativesmoothedanimation.cpp b/src/declarative/util/qdeclarativesmoothedanimation.cpp
index e0d1097..11c3d4b 100644
--- a/src/declarative/util/qdeclarativesmoothedanimation.cpp
+++ b/src/declarative/util/qdeclarativesmoothedanimation.cpp
@@ -253,15 +253,22 @@ void QSmoothedAnimation::init()
     \inherits NumberAnimation
     \brief The SmoothedAnimation element allows a property to smoothly track a value.
 
-    The SmoothedAnimation animates a property's value to a set target value
-    using an ease in/out quad easing curve.  If the animation is restarted
-    with a different target value, the easing curves used to animate to the old
-    and the new target values are smoothly spliced together to avoid any obvious
-    visual glitches by maintaining the current velocity.
-
-    The property animation is configured by setting the velocity at which the
-    animation should occur, or the duration that the animation should take.
-    If both a velocity and a duration are specified, the one that results in
+    A SmoothedAnimation animates a property's value to a set target value
+    using an ease in/out quad easing curve.  When the target value changes,
+    the easing curves used to animate between the old and new target values 
+    are smoothly spliced together to create a smooth movement to the new 
+    target value that maintains the current velocity.
+
+    The follow example shows one \l Rectangle tracking the position of another
+    using SmoothedAnimation. The green rectangle's \c x and \c y values are
+    bound to those of the red rectangle. Whenever these values change, the
+    green rectangle smoothly animates to its new position:
+
+    \snippet doc/src/snippets/declarative/smoothedanimation.qml 0
+
+    A SmoothedAnimation can be configured by setting the \l velocity at which the
+    animation should occur, or the \l duration that the animation should take.
+    If both the \l velocity and \l duration are specified, the one that results in
     the quickest animation is chosen for each change in the target value.
 
     For example, animating from 0 to 800 will take 4 seconds if a velocity
@@ -271,10 +278,6 @@ void QSmoothedAnimation::init()
     will take 8 seconds with a duration of 8000 set, and will take 8 seconds
     with both a velocity of 200 and a duration of 8000 set.
 
-    The follow example shows one rectangle tracking the position of another.
-
-    \snippet doc/src/snippets/declarative/smoothedanimation.qml 0
-
     The default velocity of SmoothedAnimation is 200 units/second.  Note that if the range of the
     value being animated is small, then the velocity will need to be adjusted
     appropriately.  For example, the opacity of an item ranges from 0 - 1.0.
@@ -287,7 +290,7 @@ void QSmoothedAnimation::init()
     sources. The \l PropertyAnimation documentation shows a variety of methods
     for creating animations.
 
-    \sa {QML Animation}, {declarative/animation/basics}{Animation basics example}
+    \sa SpringAnimation, NumberAnimation, {QML Animation}, {declarative/animation/basics}{Animation basics example}
 */
 
 QDeclarativeSmoothedAnimation::QDeclarativeSmoothedAnimation(QObject *parent)
diff --git a/src/declarative/util/qdeclarativespringanimation.cpp b/src/declarative/util/qdeclarativespringanimation.cpp
index be0af6d..8ce4832 100644
--- a/src/declarative/util/qdeclarativespringanimation.cpp
+++ b/src/declarative/util/qdeclarativespringanimation.cpp
@@ -215,7 +215,9 @@ void QDeclarativeSpringAnimationPrivate::updateMode()
     You can also limit the maximum \l velocity of the animation.
 
     The following \l Rectangle moves to the position of the mouse using a 
-    SpringAnimation when the mouse is clicked:
+    SpringAnimation when the mouse is clicked. The use of the \l Behavior
+    on the \c x and \c y values indicates that whenever these values are 
+    changed, a SpringAnimation should be applied.
 
     \snippet doc/src/snippets/declarative/springanimation.qml 0
 
@@ -224,7 +226,7 @@ void QDeclarativeSpringAnimationPrivate::updateMode()
     sources. The \l PropertyAnimation documentation shows a variety of methods
     for creating animations.
 
-    \sa {QML Animation}, {declarative/animation/basics}{Animation basics example}, {declarative/toys/clocks}{Clocks example}
+    \sa SmoothedAnimation, {QML Animation}, {declarative/animation/basics}{Animation basics example}, {declarative/toys/clocks}{Clocks example}
 */
 
 QDeclarativeSpringAnimation::QDeclarativeSpringAnimation(QObject *parent)
@@ -284,8 +286,8 @@ qreal QDeclarativeSpringAnimation::from() const
 
     This property holds the value from which the animation will begin.
 
-    If not set, the animation will start regardless of the 
-    value being tracked.
+    If not set, the animation will start whenever the tracked value has
+    changed, regardless of its value.
 */
 
 void QDeclarativeSpringAnimation::setFrom(qreal value)
@@ -303,7 +305,10 @@ void QDeclarativeSpringAnimation::setFrom(qreal value)
 
 /*!
     \qmlproperty real SpringAnimation::velocity
+
     This property holds the maximum velocity allowed when tracking the source.
+
+    The default value is 0 (no maximum velocity).
 */
 
 qreal QDeclarativeSpringAnimation::velocity() const
@@ -322,13 +327,14 @@ void QDeclarativeSpringAnimation::setVelocity(qreal velocity)
 
 /*!
     \qmlproperty real SpringAnimation::spring
-    This property holds the spring constant
 
-    The spring constant describes how strongly the target is pulled towards the
-    source. Setting spring to 0 turns off spring tracking.  Useful values 0 - 5.0
+    This property describes how strongly the target is pulled towards the
+    source. The default value is 0 (that is, the spring-like motion is disabled).
+    
+    The useful value range is 0 - 5.0.
 
-    When a spring constant is set and the velocity property is greater than 0,
-    velocity limits the maximum speed.
+    When this property is set and the \l velocity value is greater than 0,
+    the \l velocity limits the maximum speed.
 */
 qreal QDeclarativeSpringAnimation::spring() const
 {
@@ -347,10 +353,11 @@ void QDeclarativeSpringAnimation::setSpring(qreal spring)
     \qmlproperty real SpringAnimation::damping
     This property holds the spring damping value.
 
-    This value describes how quickly a sprung follower comes to rest.
+    This value describes how quickly the spring-like motion comes to rest.
+    The default value is 0.
 
-    The useful range is 0 - 1.0. The lower the value, the faster the
-    follower comes to rest.
+    The useful value range is 0 - 1.0. The lower the value, the faster it
+    comes to rest.
 */
 qreal QDeclarativeSpringAnimation::damping() const
 {
@@ -392,7 +399,7 @@ void QDeclarativeSpringAnimation::setEpsilon(qreal epsilon)
 
 /*!
     \qmlproperty real SpringAnimation::modulus
-    This property holds the modulus value.
+    This property holds the modulus value. The default value is 0.
 
     Setting a \a modulus forces the target value to "wrap around" at the modulus.
     For example, setting the modulus to 360 will cause a value of 370 to wrap around to 10.
@@ -417,8 +424,10 @@ void QDeclarativeSpringAnimation::setModulus(qreal modulus)
     \qmlproperty real SpringAnimation::mass
     This property holds the "mass" of the property being moved.
 
-    mass is 1.0 by default.  Setting a different mass changes the dynamics of
-    a \l spring follow.
+    The value is 1.0 by default. 
+    
+    A greater mass causes slower movement and a greater spring-like 
+    motion when an item comes to rest.
 */
 qreal QDeclarativeSpringAnimation::mass() const
 {
diff --git a/src/declarative/util/qdeclarativetransition.cpp b/src/declarative/util/qdeclarativetransition.cpp
index 6b7418e..6561b8c 100644
--- a/src/declarative/util/qdeclarativetransition.cpp
+++ b/src/declarative/util/qdeclarativetransition.cpp
@@ -66,8 +66,6 @@ QT_BEGIN_NAMESPACE
    
     \snippet doc/src/snippets/declarative/transition.qml 0
 
-    Items can have multiple transitions, if 
-
     To specify multiple transitions, specify \l Item::transitions as a list:
 
     \qml