Move some example code into snippets/ and add other doc fixes

13 files changed, 329 insertions, 204 deletions

diff --git a/doc/src/declarative/animation.qdoc b/doc/src/declarative/animation.qdoc
index 6e98949..c320898 100644
--- a/doc/src/declarative/animation.qdoc
+++ b/doc/src/declarative/animation.qdoc
@@ -46,14 +46,14 @@
 Animation in QML is done by animating properties of objects. Properties of type
 real, int, color, rect, point, size, and vector3d can all be animated.
 
-QML supports three main forms of animation - basic property animation,
+QML supports three main forms of animation: basic property animation,
 transitions, and property behaviors.
 
 \tableofcontents
 
 \section1 Basic Property Animation
 
-The simplest form of animation is directly using \l PropertyAnimation, which can animate all of the property
+The simplest form of animation is a \l PropertyAnimation, which can animate all of the property
 types listed above. If the property you are animating is a number or color, you can alternatively use
 NumberAnimation or ColorAnimation. These elements don't add any additional functionality,
 but will help enforce type correctness and are slightly more efficient.
@@ -62,61 +62,23 @@ A property animation can be specified as a value source using the \e Animation \
 for repeating animations.
 
 The following example creates a bouncing effect:
-\qml
-Rectangle {
-    id: rect
-    width: 120; height: 200;
-    Image {
-        id: img
-        source: "qt-logo.png"
-        x: 60-img.width/2
-        y: 0
-        SequentialAnimation on y {
-            loops: Animation.Infinite
-            NumberAnimation { to: 200-img.height; easing.type: Easing.OutBounce; duration: 2000 }
-            PauseAnimation { duration: 1000 }
-            NumberAnimation { to: 0; easing.type: Easing.OutQuad; duration: 1000 }
-        }
-    }
-}
-\endqml
+\snippet doc/src/snippets/declarative/animation.qml property-anim-1
 
 \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.
+or \c target values; they are automatically selected for you. You do, however, need to specify a \c to value.
 An animation specified as a value source will be \c running by default.
 
-\qml
-Rectangle {
-    id: rect
-    width: 200; height: 200;
-    Rectangle {
-        color: "red"
-        width: 50; height: 50
-        NumberAnimation on x { to: 50 }
-    }
-}
-\endqml
+For example, here is a rectangle that uses a \l NumberAnimation value source to animate the movement
+from its current position to an \c x value of 50. The animation starts immediately, and only the \c to 
+property is required:
+
+\snippet doc/src/snippets/declarative/animation.qml property-anim-2
 
 A property animation can also be specified as a resource that is manipulated from script.
 
-\qml
-PropertyAnimation {
-    id: animation
-    target: image
-    property: "scale"
-    from: 1; to: .5
-}
-Image {
-    id: image
-    source: "image.png"
-    MouseArea {
-        anchors.fill: parent
-        onPressed: animation.start()
-    }
-}
-\endqml
+\snippet doc/src/snippets/declarative/animation.qml property-anim-3
 
 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.
@@ -131,50 +93,20 @@ 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:
 
-\code
-transitions: [
-    Transition {
-        NumberAnimation {
-            properties: "x,y"
-            easing.type: Easing.OutBounce
-            duration: 200
-        }
-    }
-]
-\endcode
+\snippet doc/src/snippets/declarative/animation.qml transitions-1
 
 As can be seen, transitions make use of the same basic animation classes introduced above.
 In the above example we have specified that we want to animate the \c x and \c y properties, but have not
-specified the objects to animate or the \c to values. By default these values are supplied by the framework --
+specified the objects to animate or the \c to values. By default these values are supplied by the framework;
 the animation will animate any \c targets whose \c x and \c y have changed, and the \c to values will be those
 defined in the end state. You can always supply explicit values to override these implicit values when needed.
 
-\code
-Transition {
-    from: "*"
-    to: "MyState"
-    reversible: true
-    SequentialAnimation {
-        NumberAnimation {
-            duration: 1000
-            easing.type: Easing.OutBounce
-            // animate myItem's x and y if they have changed in the state
-            target: myItem
-            properties: "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
+\snippet doc/src/snippets/declarative/animation.qml transitions-2
 
 QML transitions have selectors to determine which state changes a transition should apply to.
 The following transition will only be triggered when we enter into the \c "details" state.
+(The "*" value is a wildcard value that specifies the transition should be applied when changing
+from \e any state to the "details" state.)
 
 \code
 Transition {
@@ -188,30 +120,7 @@ Transitions can happen in parallel, in sequence, or in any combination of the tw
 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 {
-    from: "*"
-    to: "MyState"
-    reversible: true
-    SequentialAnimation {
-        ColorAnimation { duration: 1000 }
-        PauseAnimation { duration: 1000 }
-        ParallelAnimation {
-            NumberAnimation {
-                duration: 1000
-                easing.type: Easing.OutBounce
-                targets: box1
-                properties: "x,y"
-            }
-            NumberAnimation {
-                duration: 1000
-                targets: box2
-                properties: "x,y"
-            }
-        }
-    }
-}
-\endcode
+\snippet doc/src/snippets/declarative/animation.qml transitions-3
 
 \section1 Property Behaviors
 
@@ -219,24 +128,15 @@ A \l{Behavior}{property behavior} specifies a default animation to run whenever
 of what caused the change. The \c enabled property can be used to force a \l Behavior
 to 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.
+In the following snippet, we specify that we want the \c x position of \c redRect to be animated
+whenever it changes. The animation will last 300 milliseconds and use an \l{PropertyAnimation::easing.type}{Easing.InOutQuad} easing curve.
 
-\qml
-Rectangle {
-    id: redRect
-    color: "red"
-    width: 100; height: 100
-    Behavior on x { NumberAnimation { duration: 300; easing.type: Easing.InOutQuad } }
-}
-\endqml
+\snippet doc/src/snippets/declarative/animation.qml behavior
 
 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
+To trigger this behavior, we could enter a state that changes \c x:
 
 \qml
 State {
@@ -249,7 +149,7 @@ State {
 }
 \endqml
 
-\o Update x from a script
+Or, update \c x from a script:
 
 \qml
 MouseArea {
@@ -257,11 +157,10 @@ MouseArea {
     onClicked: redRect.x = 24;
 }
 \endqml
-\endlist
 
-If x were bound to another property, triggering the binding would also trigger the behavior.
+If \c x were bound to another property, triggering the binding would also trigger the behavior.
 
-If a state change has a transition animation matching a property with a Behavior, the transition animation
-will override the Behavior for that state change.
+If a state change has a transition animation matching a property with a \l Behavior, the transition animation
+will override the \l Behavior for that state change.
 
 */
diff --git a/doc/src/declarative/qdeclarativestates.qdoc b/doc/src/declarative/qdeclarativestates.qdoc
index fd0c677..43b5c31 100644
--- a/doc/src/declarative/qdeclarativestates.qdoc
+++ b/doc/src/declarative/qdeclarativestates.qdoc
@@ -70,58 +70,30 @@ In QML:
 \o A state can affect the properties of other objects, not just the object owning the state (and not just that object's children).
 \endlist
 
+To define a state for an item, add a \l State element to the \l{Item::states}{states} property. To
+change the current state of an \l Item, set the \l{Item::state}{state} property to the name
+of the required state.
+
 Here is an example of using states. In the default state \c myRect is positioned at 0,0. In the 'moved' state it is positioned at 50,50. Clicking within the mouse area changes the state from the default state to the 'moved' state, thus moving the rectangle.
 
-\qml
-Item {
-    id: myItem
-
-    Rectangle {
-        id: myRect
-        width: 100
-        height: 100
-        color: "red"
-    }
-
-    states: [
-        State {
-            name: "moved"
-            PropertyChanges {
-                target: myRect
-                x: 50
-                y: 50
-            }
-        }
-    ]
-
-    MouseArea {
-        anchors.fill: parent
-        onClicked: myItem.state = 'moved'
-    }
-}
-\endqml
+\snippet doc/src/snippets/declarative/states.qml 0
+\snippet doc/src/snippets/declarative/states.qml 1
 
 State changes can be animated using \l{state-transitions}{Transitions}.
 
-For example, adding this code to the above \c {Item {}} element animates the transition to the "moved" state:
+For example, adding this code to the above \c Item element animates the transition to the "moved" state:
 
-\qml
-    transitions: [
-        Transition {
-            NumberAnimation { properties: "x,y"; duration: 500 }
-        }
-    ]
-\endqml
+\snippet doc/src/snippets/declarative/states.qml transitions
 
 See \l{state-transitions}{Transitions} for more information.
 
 
 Other things you can do in a state change:
 \list
-\o override signal handlers with PropertyChanges
-\o change an item's visual parent with ParentChange
-\o change an item's anchors with AnchorChanges
-\o run some script with StateChangeScript
+\o Override signal handlers with PropertyChanges
+\o Change an item's visual parent with ParentChange
+\o Change an item's anchors with AnchorChanges
+\o Run some script with StateChangeScript
 \endlist
 
 */
diff --git a/doc/src/snippets/declarative/anchorchanges.qml b/doc/src/snippets/declarative/anchorchanges.qml
new file mode 100644
index 0000000..6c0a0ad
--- /dev/null
+++ b/doc/src/snippets/declarative/anchorchanges.qml
@@ -0,0 +1,28 @@
+//![0]
+import Qt 4.7
+
+Item {
+    id: window
+    width: 200; height: 200
+
+    Rectangle { id: myRect; width: 100; height: 100; color: "red" }
+
+    states: State {
+        name: "reanchored"
+
+        AnchorChanges {
+            target: myRect
+            anchors.top: window.top
+            anchors.bottom: window.bottom
+        }
+        PropertyChanges {
+            target: myRect
+            anchors.topMargin: 3
+            anchors.bottomMargin: 3
+        }
+    }
+
+    MouseArea { anchors.fill: parent; onClicked: window.state = "reanchored" }
+}
+//![0]
+
diff --git a/doc/src/snippets/declarative/animation.qml b/doc/src/snippets/declarative/animation.qml
new file mode 100644
index 0000000..f5c6bf6
--- /dev/null
+++ b/doc/src/snippets/declarative/animation.qml
@@ -0,0 +1,141 @@
+import Qt 4.7
+
+Row {
+
+//![property-anim-1]
+Rectangle {
+    id: rect
+    width: 120; height: 200
+
+    Image {
+        id: img
+        source: "pics/qt.png"
+        x: 60 - img.width/2
+        y: 0
+
+        SequentialAnimation on y {
+            loops: Animation.Infinite
+            NumberAnimation { to: 200 - img.height; easing.type: Easing.OutBounce; duration: 2000 }
+            PauseAnimation { duration: 1000 }
+            NumberAnimation { to: 0; easing.type: Easing.OutQuad; duration: 1000 }
+        }
+    }
+}
+//![property-anim-1]
+
+//![property-anim-2]
+Rectangle {
+    width: 200; height: 200
+
+    Rectangle {
+        color: "red"
+        width: 50; height: 50
+        NumberAnimation on x { to: 50 }
+    }
+}
+//![property-anim-2]
+
+
+Item {
+//![property-anim-3]
+PropertyAnimation {
+    id: animation
+    target: image
+    property: "scale"
+    from: 1; to: 0.5
+}
+
+Image {
+    id: image
+    source: "pics/qt.png"
+    MouseArea {
+        anchors.fill: parent
+        onPressed: animation.start()
+    }
+}
+//![property-anim-3]
+}
+
+
+//![transitions-1]
+transitions: [
+    Transition {
+        NumberAnimation {
+            properties: "x,y"
+            easing.type: Easing.OutBounce
+            duration: 200
+        }
+    }
+]
+//![transitions-1]
+
+
+//![transitions-2]
+Transition {
+    from: "*"
+    to: "MyState"
+    reversible: true
+
+    SequentialAnimation {
+        NumberAnimation {
+            duration: 1000
+            easing.type: Easing.OutBounce
+
+            // animate myItem's x and y if they have changed in the state
+            target: myItem
+            properties: "x,y"
+        }
+
+        NumberAnimation {
+            duration: 1000
+
+            // animate myItem2's y to 200, regardless of what happens in the state
+            target: myItem2
+            property: "y"
+            to: 200
+        }
+    }
+}
+//![transitions-2]
+
+
+//![transitions-3]
+Transition {
+    from: "*"
+    to: "MyState"
+    reversible: true
+
+    SequentialAnimation {
+        ColorAnimation { duration: 1000 }
+        PauseAnimation { duration: 1000 }
+
+        ParallelAnimation {
+            NumberAnimation {
+                duration: 1000
+                easing.type: Easing.OutBounce
+                targets: box1
+                properties: "x,y"
+            }
+            NumberAnimation {
+                duration: 1000
+                targets: box2
+                properties: "x,y"
+            }
+        }
+    }
+}
+//![transitions-3]
+
+//![behavior]
+Rectangle {
+    id: redRect
+    color: "red"
+    width: 100; height: 100
+
+    Behavior on x { 
+        NumberAnimation { duration: 300; easing.type: Easing.InOutQuad }
+    }
+}
+//![behavior]
+
+}
diff --git a/doc/src/snippets/declarative/createQmlObject.qml b/doc/src/snippets/declarative/createQmlObject.qml
index f2ac6e6..f274e40 100644
--- a/doc/src/snippets/declarative/createQmlObject.qml
+++ b/doc/src/snippets/declarative/createQmlObject.qml
@@ -42,7 +42,7 @@
 import Qt 4.7
 
 Rectangle {
-    id: targetItem
+    id: parentItem
     property QtObject newObject
 
     width: 100
@@ -51,7 +51,7 @@ Rectangle {
     function createIt() {
 //![0]
 newObject = Qt.createQmlObject('import Qt 4.7; Rectangle {color: "red"; width: 20; height: 20}',
-    targetItem, "dynamicSnippet1");
+    parentItem, "dynamicSnippet1");
 //![0]
     }
 
diff --git a/doc/src/snippets/declarative/state.qml b/doc/src/snippets/declarative/state.qml
new file mode 100644
index 0000000..0954298
--- /dev/null
+++ b/doc/src/snippets/declarative/state.qml
@@ -0,0 +1,29 @@
+//![0]
+import Qt 4.7
+
+Rectangle {
+    id: myRect
+    width: 100; height: 100
+    color: "black"
+
+    states: [
+        State {
+            name: "clicked"
+            PropertyChanges {
+                target: myRect
+                color: "red"
+            }
+        }
+    ]
+
+    MouseArea {
+        anchors.fill: parent
+        onClicked: {
+            if (myRect.state == "")     // i.e. the default state
+                myRect.state = "clicked";
+            else
+                myRect.state = "";
+        }
+    }
+}
+//![0]
diff --git a/doc/src/snippets/declarative/states.qml b/doc/src/snippets/declarative/states.qml
new file mode 100644
index 0000000..7bfb5bd
--- /dev/null
+++ b/doc/src/snippets/declarative/states.qml
@@ -0,0 +1,41 @@
+//![0]
+import Qt 4.7
+
+Item {
+    id: myItem
+    width: 200; height: 200
+
+    Rectangle {
+        id: myRect
+        width: 100; height: 100
+        color: "red"
+    }
+
+    states: [
+        State {
+            name: "moved"
+            PropertyChanges {
+                target: myRect
+                x: 50
+                y: 50
+            }
+        }
+    ]
+
+    MouseArea {
+        anchors.fill: parent
+        onClicked: myItem.state = 'moved'
+    }
+//![0]
+
+//![transitions]
+transitions: [
+    Transition {
+        NumberAnimation { properties: "x,y"; duration: 500 }
+    }
+]
+//![transitions]
+
+//![1]
+}
+//![1]
diff --git a/src/declarative/qml/qdeclarativecomponent.cpp b/src/declarative/qml/qdeclarativecomponent.cpp
index 9847079..7b51239 100644
--- a/src/declarative/qml/qdeclarativecomponent.cpp
+++ b/src/declarative/qml/qdeclarativecomponent.cpp
@@ -78,7 +78,7 @@ class QByteArray;
     \since 4.7
     \brief The Component element encapsulates a QML component description.
 
-    Components are reusable, encapsulated Qml element with a well-defined interface.
+    Components are reusable, encapsulated QML elements with well-defined interfaces.
     They are often defined in \l {qdeclarativedocuments.html}{Component Files}.
 
     The \e Component element allows defining components within a QML file.
diff --git a/src/declarative/qml/qdeclarativeengine.cpp b/src/declarative/qml/qdeclarativeengine.cpp
index 39b0802..0715624 100644
--- a/src/declarative/qml/qdeclarativeengine.cpp
+++ b/src/declarative/qml/qdeclarativeengine.cpp
@@ -191,7 +191,7 @@ when the property has one of the following types:
 \o \c vector3d - use \l{Qt::vector3d()}{Qt.vector3d()}
 \endlist
 
-There are also string based constructors for these types, see \l{qdeclarativebasictypes.html}{QML Basic Types}.
+There are also string based constructors for these types. See \l{qdeclarativebasictypes.html}{QML Basic Types} for more information.
 
 \section1 Date/Time Formatters
 
@@ -1054,8 +1054,9 @@ or \c null if there was an error in creating the component.
 Call \l {Component::createObject()}{Component.createObject()} on the returned
 component to create an object instance of the component.
 
-Here is an example. Remember that QML files that might be loaded
-over the network cannot be expected to be ready immediately.
+Here is an example. Notice it checks whether the component \l{Component::status}{status} is
+\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
 \codeline
@@ -1095,12 +1096,12 @@ QScriptValue QDeclarativeEnginePrivate::createComponent(QScriptContext *ctxt, QS
 /*!
 \qmlmethod object Qt::createQmlObject(string qml, object parent, string filepath)
 
-Returns a new object created from the given \a string of QML with the specified \a parent,
+Returns a new object created from the given \a string of QML which will have the specified \a parent,
 or \c null if there was an error in creating the object.
 
 If \a filepath is specified, it will be used for error reporting for the created object.
 
-Example (where \c targetItem is the id of an existing QML item):
+Example (where \c parentItem is the id of an existing QML item):
 
 \snippet doc/src/snippets/declarative/createQmlObject.qml 0
 
diff --git a/src/declarative/util/qdeclarativepropertychanges.cpp b/src/declarative/util/qdeclarativepropertychanges.cpp
index e98afeb..8e3ec82 100644
--- a/src/declarative/util/qdeclarativepropertychanges.cpp
+++ b/src/declarative/util/qdeclarativepropertychanges.cpp
@@ -91,7 +91,7 @@ QT_BEGIN_NAMESPACE
     \endqml
 
     By default, PropertyChanges will establish new bindings where appropriate.
-    For example, the following creates a new binding for myItem's height property.
+    For example, the following creates a new binding for myItem's \c height property.
 
     \qml
     PropertyChanges {
@@ -500,8 +500,8 @@ QDeclarativePropertyChanges::ActionList QDeclarativePropertyChanges::actions()
     If explicit is set to true, any potential bindings will be interpreted as
     once-off assignments that occur when the state is entered.
 
-    In the following example, the addition of explicit prevents myItem.width from
-    being bound to parent.width. Instead, it is assigned the value of parent.width
+    In the following example, the addition of explicit prevents \c myItem.width from
+    being bound to \c parent.width. Instead, it is assigned the value of \c parent.width
     at the time of the state change.
     \qml
     PropertyChanges {
diff --git a/src/declarative/util/qdeclarativestate.cpp b/src/declarative/util/qdeclarativestate.cpp
index eca90a4..37f9f6a 100644
--- a/src/declarative/util/qdeclarativestate.cpp
+++ b/src/declarative/util/qdeclarativestate.cpp
@@ -136,12 +136,30 @@ QDeclarativeStateOperation::QDeclarativeStateOperation(QObjectPrivate &dd, QObje
     \since 4.7
     \brief The State element defines configurations of objects and properties.
 
-    A state is specified as a set of batched changes from the default configuration.
+    A \e state is a set of batched changes from the default configuration.
+
+    All items have a default state that defines the default configuration of objects
+    and property values. New states can be defined by adding State items to the \l {Item::states}{states} property to
+    allow items to switch between different configurations. These configurations
+    can, for example, be used to apply different sets of property values or execute
+    different scripts.
+
+    Here is an example. In the default state, \c myRect is colored black. In the "clicked"
+    state, the color is red. Clicking within the MouseArea toggles the rectangle's state
+    between the default state and the "clicked" state, thus toggling the color of the
+    rectangle between black and red.
+
+    \snippet doc/src/snippets/declarative/state.qml 0
+
+    Notice the default state is referred to using an empty string ("").
+
+    States are commonly used together with \l {state-transitions}{Transitions} to provide
+    animations when state changes occur.
 
     \note setting the state of an object from within another state of the same object is
     not allowed.
 
-    \sa {qmlstates}{States}, {state-transitions}{Transitions}, QtDeclarative
+    \sa {declarative/animation/states}{states example}, {qmlstates}{States}, {state-transitions}{Transitions}, QtDeclarative
 */
 
 /*!
@@ -173,7 +191,7 @@ QDeclarativeState::~QDeclarativeState()
 
 /*!
     \qmlproperty string State::name
-    This property holds the name of the state
+    This property holds the name of the state.
 
     Each state should have a unique name.
 */
@@ -204,12 +222,12 @@ bool QDeclarativeState::isWhenKnown() const
 
 /*!
     \qmlproperty bool State::when
-    This property holds when the state should be applied
+    This property holds when the state should be applied.
 
-    This should be set to an expression that evaluates to true when you want the state to
+    This should be set to an expression that evaluates to \c true when you want the state to
     be applied.
 
-    If multiple states in a group have \c when clauses that evaluate to true at the same time,
+    If multiple states in a group have \c when clauses that evaluate to \c true at the same time,
     the first matching state will be applied. For example, in the following snippet
     \c state1 will always be selected rather than \c state2 when sharedCondition becomes
     \c true.
@@ -236,7 +254,9 @@ void QDeclarativeState::setWhen(QDeclarativeBinding *when)
 
 /*!
     \qmlproperty string State::extend
-    This property holds the state that this state extends
+    This property holds the state that this state extends.
+
+    When a state extends another state, it inherits all the changes of that state.
 
     The state being extended is treated as the base state in regards to
     the changes specified by the extending state.
diff --git a/src/declarative/util/qdeclarativestategroup.cpp b/src/declarative/util/qdeclarativestategroup.cpp
index 1e530a1..67cd12e 100644
--- a/src/declarative/util/qdeclarativestategroup.cpp
+++ b/src/declarative/util/qdeclarativestategroup.cpp
@@ -91,8 +91,8 @@ public:
    \since 4.7
    \brief The StateGroup element provides state support for non-Item elements.
 
-   Item (and all dervied elements) provides built in support for states and transitions
-   via its state, states and transitions properties. StateGroup provides an easy way to
+   Item (and all derived elements) provides built in support for states and transitions
+   via its \l{Item::state}{state}, \l{Item::states}{states} and \l{Item::transitions}{transitions} properties. StateGroup provides an easy way to
    use this support in other (non-Item-derived) elements.
 
    \qml
diff --git a/src/declarative/util/qdeclarativestateoperations.cpp b/src/declarative/util/qdeclarativestateoperations.cpp
index 99f163e..2d55931 100644
--- a/src/declarative/util/qdeclarativestateoperations.cpp
+++ b/src/declarative/util/qdeclarativestateoperations.cpp
@@ -583,9 +583,9 @@ public:
     \qmlclass StateChangeScript QDeclarativeStateChangeScript
     \brief The StateChangeScript element allows you to run a script in a state.
 
-    StateChangeScripts are run when entering the state. You can use
-    ScriptAction to specify at which point in the transition
-    you want the StateChangeScript to be run.
+    A StateChangeScript is run upon entering a state. You can optionally use
+    ScriptAction to specify the point in the transition at which
+    the StateChangeScript should to be run.
 
     \qml
     State {
@@ -687,22 +687,16 @@ QString QDeclarativeStateChangeScript::typeName() const
     \qmlclass AnchorChanges QDeclarativeAnchorChanges
     \brief The AnchorChanges element allows you to change the anchors of an item in a state.
 
-    In the following example we change the top and bottom anchors of an item:
-    \qml
-    State {
-        name: "reanchored"
-        AnchorChanges {
-            target: content;
-            anchors.top: window.top;
-            anchors.bottom: window.bottom
-        }
-        PropertyChanges {
-            target: content;
-            anchors.topMargin: 3
-            anchors.bottomMargin: 3;
-        }
-    }
-    \endqml
+    The AnchorChanges element is used to modify the anchors of an item in a \l State.
+
+    AnchorChanges cannot be used to modify the margins on an item. For this, use
+    PropertyChanges intead.
+
+    In the following example we change the top and bottom anchors of an item
+    using AnchorChanges, and the top and bottom anchor margins using
+    PropertyChanges:
+
+    \snippet doc/src/snippets/declarative/anchorchanges.qml 0
 
     AnchorChanges can be animated using AnchorAnimation.
     \qml