Doc improvements: move some example code to snippets, add screenshots,

other minor doc fixes

7 files changed, 71 insertions, 138 deletions

diff --git a/src/declarative/util/qdeclarativeanimation.cpp b/src/declarative/util/qdeclarativeanimation.cpp
index 1447532..25cf133 100644
--- a/src/declarative/util/qdeclarativeanimation.cpp
+++ b/src/declarative/util/qdeclarativeanimation.cpp
@@ -1774,7 +1774,7 @@ void QDeclarativePropertyAnimation::setTo(const QVariant &t)
 
     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 }
@@ -1951,15 +1951,15 @@ void QDeclarativePropertyAnimation::setTo(const QVariant &t)
         \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).
+    \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).
 
-    easing.overshoot is only applicable if type is: Easing.InBack, Easing.OutBack,
-    Easing.InOutBack or Easing.OutInBack.
+    \c easing.overshoot is only applicable if \c easing.type is: \c Easing.InBack, \c Easing.OutBack,
+    \c Easing.InOutBack or \c Easing.OutInBack.
 
-    easing.period is only applicable if type is: Easing.InElastic, Easing.OutElastic,
-    Easing.InOutElastic or Easing.OutInElastic.
+    \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.
@@ -2045,8 +2045,9 @@ void QDeclarativePropertyAnimation::setProperties(const QString &prop)
     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
diff --git a/src/declarative/util/qdeclarativeconnections.cpp b/src/declarative/util/qdeclarativeconnections.cpp
index 808d196..b364821 100644
--- a/src/declarative/util/qdeclarativeconnections.cpp
+++ b/src/declarative/util/qdeclarativeconnections.cpp
@@ -72,7 +72,9 @@ public:
 /*!
     \qmlclass Connections QDeclarativeConnections
   \since 4.7
-    \brief A Connections object describes generalized connections to signals.
+    \brief A Connections element describes generalized connections to signals.
+
+    A Connections object creates a connection to a QML signal.
 
     When connecting to signals in QML, the usual way is to create an
     "on<Signal>" handler that reacts when a signal is received, like this:
@@ -83,16 +85,16 @@ public:
     }
     \endqml
 
-    However, in some cases, it is not possible to connect to a signal in this
-    way, such as:
+    However, it is not possible to connect to a signal in this way in some 
+    cases, such as when:
 
     \list
-        \i multiple connections to the same signal
-        \i connections outside the scope of the signal sender
-        \i connections to targets not defined in QML
+        \i Multiple connections to the same signal are required
+        \i Creating connections outside the scope of the signal sender
+        \i Connecting to targets not defined in QML
     \endlist
 
-    When any of these are needed, the Connections object can be used instead.
+    When any of these are needed, the Connections element can be used instead.
 
     For example, the above code can be changed to use a Connections object,
     like this:
@@ -105,7 +107,7 @@ public:
     }
     \endqml
 
-    More generally, the Connections object can be a child of some other object than
+    More generally, the Connections object can be a child of some object other than
     the sender of the signal:
 
     \qml
@@ -141,7 +143,7 @@ QDeclarativeConnections::~QDeclarativeConnections()
     \qmlproperty Object Connections::target
     This property holds the object that sends the signal.
 
-    If not set at all, the target defaults to be the parent of the Connections.
+    If this property is not set, the \c target defaults to the parent of the Connection.
 
     If set to null, no connection is made and any signal handlers are ignored
     until the target is not null.
@@ -175,12 +177,11 @@ void QDeclarativeConnections::setTarget(QObject *obj)
 /*!
     \qmlproperty bool Connections::ignoreUnknownSignals
 
-    Normally, you will get a runtime error if you try to connect
-    to signals on an object which the object does not have.
+    Normally, a connection to a non-existent signal produces runtime errors.
 
-    By setting this flag to true, such errors are ignored. This is
-    useful if you intend to connect to different types of object, handling
-    a different set of signals for each.
+    If this property is set to \c true, such errors are ignored.
+    This is useful if you intend to connect to different types of objects, handling
+    a different set of signals for each object.
 */
 bool QDeclarativeConnections::ignoreUnknownSignals() const
 {
diff --git a/src/declarative/util/qdeclarativelistmodel.cpp b/src/declarative/util/qdeclarativelistmodel.cpp
index 7518eb7..78a3207 100644
--- a/src/declarative/util/qdeclarativelistmodel.cpp
+++ b/src/declarative/util/qdeclarativelistmodel.cpp
@@ -76,125 +76,41 @@ QDeclarativeListModelParser::ListInstruction *QDeclarativeListModelParser::ListM
 
     For example:
 
-    \code
-    ListModel {
-        id: fruitModel
-        ListElement {
-            name: "Apple"
-            cost: 2.45
-        }
-        ListElement {
-            name: "Orange"
-            cost: 3.25
-        }
-        ListElement {
-            name: "Banana"
-            cost: 1.95
-        }
-    }
-    \endcode
+    \snippet doc/src/snippets/declarative/listmodel.qml 0
 
-    Roles (properties) must begin with a lower-case letter.The above example defines a
+    Roles (properties) must begin with a lower-case letter. The above example defines a
     ListModel containing three elements, with the roles "name" and "cost".
 
     Values must be simple constants - either strings (quoted), bools (true, false), numbers,
     or enum values (like Text.AlignHCenter).
 
     The defined model can be used in views such as ListView:
-    \code
-    Component {
-        id: fruitDelegate
-        Item {
-            width: 200; height: 50
-            Text { text: name }
-            Text { text: '$'+cost; anchors.right: parent.right }
-        }
-    }
 
-    ListView {
-        model: fruitModel
-        delegate: fruitDelegate
-        anchors.fill: parent
-    }
-    \endcode
+    \snippet doc/src/snippets/declarative/listmodel-simple.qml 0
+    \dots 8
+    \snippet doc/src/snippets/declarative/listmodel-simple.qml 1
+    \image listmodel.png
 
     It is possible for roles to contain list data.  In the example below we create a list of fruit attributes:
 
-    \code
-    ListModel {
-        id: fruitModel
-        ListElement {
-            name: "Apple"
-            cost: 2.45
-            attributes: [
-                ListElement { description: "Core" },
-                ListElement { description: "Deciduous" }
-            ]
-        }
-        ListElement {
-            name: "Orange"
-            cost: 3.25
-            attributes: [
-                ListElement { description: "Citrus" }
-            ]
-        }
-        ListElement {
-            name: "Banana"
-            cost: 1.95
-            attributes: [
-                ListElement { description: "Tropical" },
-                ListElement { description: "Seedless" }
-            ]
-        }
-    }
-    \endcode
+    \snippet doc/src/snippets/declarative/listmodel-nested.qml model
+
+    The delegate below displays all the fruit attributes:
+
+    \snippet doc/src/snippets/declarative/listmodel-nested.qml delegate
+    \image listmodel-nested.png
 
-    The delegate below will list all the fruit attributes:
-    \code
-    Component {
-        id: fruitDelegate
-        Item {
-            width: 200; height: 50
-            Text { id: name; text: name }
-            Text { text: '$'+cost; anchors.right: parent.right }
-            Row {
-                anchors.top: name.bottom
-                spacing: 5
-                Text { text: "Attributes:" }
-                Repeater {
-                    model: attributes
-                    Component { Text { text: description } }
-                }
-            }
-        }
-    }
-    \endcode
 
     \section2 Modifying list models
 
     The content of a ListModel may be created and modified using the clear(),
-    append(), and set() methods.  For example:
-
-    \code
-    Component {
-        id: fruitDelegate
-        Item {
-            width: 200; height: 50
-            Text { text: name }
-            Text { text: '$'+cost; anchors.right: parent.right }
-
-            // Double the price when clicked.
-            MouseArea {
-                anchors.fill: parent
-                onClicked: fruitModel.set(index, "cost", cost*2)
-            }
-        }
-    }
-    \endcode
+    append(), set() and setProperty() methods.  For example:
+    
+    \snippet doc/src/snippets/declarative/listmodel-modify.qml delegate
 
     When creating content dynamically, note that the set of available properties cannot be changed
-    except by first clearing the model - whatever properties are first added are then the
-    only permitted properties in the model.
+    except by first clearing the model. Whatever properties are first added to the model are then the
+    only permitted properties in the model until it is cleared.
 
 
     \section2 Using threaded list models with WorkerScript
@@ -214,11 +130,11 @@ QDeclarativeListModelParser::ListInstruction *QDeclarativeListModelParser::ListM
     \snippet examples/declarative/threading/threadedlistmodel/dataloader.js 0
 
     The application's \tt Timer object periodically sends a message to the
-    worker script by calling \tt WorkerScript::sendMessage(). When this message
-    is received, \tt WorkerScript.onMessage() is invoked in
+    worker script by calling \l WorkerScript::sendMessage(). When this message
+    is received, \l {WorkerScript::onMessage}{WorkerScript.onMessage()} is invoked in
     \tt dataloader.js, which appends the current time to the list model.
 
-    Note the call to sync() from the \c WorkerScript.onMessage() handler.
+    Note the call to sync() from the \l {WorkerScript::onMessage}{WorkerScript.onMessage()} handler.
     You must call sync() or else the changes made to the list from the external
     thread will not be reflected in the list model in the main thread.
 
@@ -454,7 +370,7 @@ void QDeclarativeListModel::insert(int index, const QScriptValue& valuemap)
     to the end of the list:
 
     \code
-        fruitModel.move(0,fruitModel.count-3,3)
+        fruitModel.move(0, fruitModel.count - 3, 3)
     \endcode
 
     \sa append()
diff --git a/src/declarative/util/qdeclarativepackage.cpp b/src/declarative/util/qdeclarativepackage.cpp
index 9617b86..9245fc2 100644
--- a/src/declarative/util/qdeclarativepackage.cpp
+++ b/src/declarative/util/qdeclarativepackage.cpp
@@ -48,9 +48,9 @@ QT_BEGIN_NAMESPACE
 
 /*!
     \qmlclass Package QDeclarativePackage
-    \brief Package provides a collection of named items
+    \brief Package provides a collection of named items.
 
-    The Package class is currently used in conjunction with
+    The Package class is used in conjunction with
     VisualDataModel to enable delegates with a shared context
     to be provided to multiple views.
 
@@ -58,7 +58,7 @@ QT_BEGIN_NAMESPACE
     \e {Package.name} attached property.
 
     The example below creates a Package containing two named items;
-    \e list and \e grid.  The third element in the package is parented to whichever
+    \e list and \e grid.  The third element in the package (the \l Rectangle) is parented to whichever
     delegate it should appear in.  This allows an item to move
     between views.
 
@@ -70,7 +70,7 @@ QT_BEGIN_NAMESPACE
 
     \snippet examples/declarative/modelviews/package/view.qml 0
 
-    \sa QtDeclarative
+    \sa {declarative/modelviews/package}{Package example}, QtDeclarative
 */
 
 
diff --git a/src/declarative/util/qdeclarativestate.cpp b/src/declarative/util/qdeclarativestate.cpp
index 37f9f6a..ae19a9c 100644
--- a/src/declarative/util/qdeclarativestate.cpp
+++ b/src/declarative/util/qdeclarativestate.cpp
@@ -144,8 +144,9 @@ QDeclarativeStateOperation::QDeclarativeStateOperation(QObjectPrivate &dd, QObje
     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
+    The following example displays a single Rectangle. In the default state, the rectangle
+    is colored black. In the "clicked" state, a PropertyChanges element changes the
+    rectangle's color to 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.
 
diff --git a/src/declarative/util/qdeclarativestateoperations.cpp b/src/declarative/util/qdeclarativestateoperations.cpp
index 2d55931..51e6f99 100644
--- a/src/declarative/util/qdeclarativestateoperations.cpp
+++ b/src/declarative/util/qdeclarativestateoperations.cpp
@@ -172,6 +172,14 @@ void QDeclarativeParentChangePrivate::doChange(QDeclarativeItem *targetParent, Q
     items involved in the reparenting (i.e. items in the common ancestor tree
     for the original and new parent).
 
+    The example below displays a large red rectangle and a small blue rectangle, side by side. 
+    When the \c blueRect is clicked, it changes to the "reparented" state: its parent is changed to \c redRect and it is 
+    positioned at (10, 10) within the red rectangle, as specified in the ParentChange.
+
+    \snippet doc/src/snippets/declarative/parentchange.qml 0
+
+    \image parentchange.png
+
     You can specify at which point in a transition you want a ParentChange to occur by
     using a ParentAnimation.
 */
@@ -698,6 +706,8 @@ QString QDeclarativeStateChangeScript::typeName() const
 
     \snippet doc/src/snippets/declarative/anchorchanges.qml 0
 
+    \image anchorchanges.png
+
     AnchorChanges can be animated using AnchorAnimation.
     \qml
     //animate our anchor changes
diff --git a/src/declarative/util/qdeclarativexmllistmodel.cpp b/src/declarative/util/qdeclarativexmllistmodel.cpp
index 4f9355b..4adef25 100644
--- a/src/declarative/util/qdeclarativexmllistmodel.cpp
+++ b/src/declarative/util/qdeclarativexmllistmodel.cpp
@@ -523,10 +523,13 @@ void QDeclarativeXmlListModelPrivate::clear_role(QDeclarativeListProperty<QDecla
     A XmlListModel could create a model from this data, like this:
 
     \qml
+    import Qt 4.7
+
     XmlListModel {
         id: xmlModel
         source: "http://www.mysite.com/feed.xml"
         query: "/rss/channel/item"
+
         XmlRole { name: "title"; query: "title/string()" }
         XmlRole { name: "pubDate"; query: "pubDate/string()" }
     }
@@ -536,7 +539,7 @@ void QDeclarativeXmlListModelPrivate::clear_role(QDeclarativeListProperty<QDecla
     a model item for each \c <item> in the XML document. 
     
     The XmlRole objects define the
-    model item attributes; here, each model item will have \c title and \c pubDate 
+    model item attributes. Here, each model item will have \c title and \c pubDate 
     attributes that match the \c title and \c pubDate values of its corresponding \c <item>.
     (See \l XmlRole::query for more examples of valid XPath expressions for XmlRole.)
 
@@ -672,11 +675,11 @@ void QDeclarativeXmlListModel::setSource(const QUrl &src)
 
 /*!
     \qmlproperty string XmlListModel::xml
-    This property holds XML text set directly.
+    This property holds the XML data for this model, if set.
 
     The text is assumed to be UTF-8 encoded.
 
-    If both source and xml are set, xml will be used.
+    If both \l source and \c xml are set, \c xml will be used.
 */
 QString QDeclarativeXmlListModel::xml() const
 {
@@ -733,6 +736,7 @@ void QDeclarativeXmlListModel::setQuery(const QString &query)
         source: "http://mysite.com/feed.xml"
         query: "/feed/entry"
         namespaceDeclarations: "declare default element namespace 'http://www.w3.org/2005/Atom';"
+
         XmlRole { name: "title"; query: "title/string()" }
     }
     \endqml