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

6 files changed, 52 insertions, 37 deletions

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