Merge branch '4.7' of scm.dev.nokia.troll.no:qt/oslo-staging-2 into 4.7-integration

* '4.7' of scm.dev.nokia.troll.no:qt/oslo-staging-2:
  Fixed regression in QPixmap::size() for null pixmaps.
  Make test less sensitive to platform specifics
  Doc: Further QML improvements.
  Doc: Minor improvements to QML-related documentation.
  The test livelock of QTimer is now expected to work
  Make sure mapSelectionFromSource does not return a selection with invalid ranges.
  QEventDispatcherUnix: do not process too many timer if other events need to be processed first
  Doc: Continued work on the QML documentation.
  Doc: More work on the QML documentation.
  Doc: More work on the declarative API documentation.
  Doc: Some editing and tidying up.
  Doc: Added a missing file.
  Doc: Fixed text in license headers.

8 files changed, 294 insertions, 145 deletions

diff --git a/src/declarative/graphicsitems/qdeclarativeflickable.cpp b/src/declarative/graphicsitems/qdeclarativeflickable.cpp
index 5a94afb..84b0ccf 100644
--- a/src/declarative/graphicsitems/qdeclarativeflickable.cpp
+++ b/src/declarative/graphicsitems/qdeclarativeflickable.cpp
@@ -372,11 +372,12 @@ void QDeclarativeFlickablePrivate::updateBeginningEnd()
     \inlineimage flickable.gif
     \endfloat
 
-    The following example shows a large 
+    The following example shows a small view onto a large image in which the
+    user can drag or flick the image in order to view different parts of it.
 
-    \clearfloat
     \snippet doc/src/snippets/declarative/flickable.qml document
 
+    \clearfloat
     \section1 Limitations
 
     \note Due to an implementation detail, items placed inside a Flickable cannot anchor to it by
diff --git a/src/declarative/graphicsitems/qdeclarativegridview.cpp b/src/declarative/graphicsitems/qdeclarativegridview.cpp
index 6a99733..8d08c99 100644
--- a/src/declarative/graphicsitems/qdeclarativegridview.cpp
+++ b/src/declarative/graphicsitems/qdeclarativegridview.cpp
@@ -1070,27 +1070,41 @@ void QDeclarativeGridViewPrivate::flick(AxisData &data, qreal minExtent, qreal m
     GridView are laid out horizontally or vertically. Grid views are inherently flickable
     as GridView inherits from \l Flickable.
 
-    For example, if there is a simple list model defined in a file \c ContactModel.qml like this:
+    \section1 Example Usage
+
+    The following example shows the definition of a simple list model defined
+    in a file called \c ContactModel.qml:
 
     \snippet doc/src/snippets/declarative/gridview/ContactModel.qml 0
 
-    Another component can display this model data in a GridView, like this:
+    \beginfloatright
+    \inlineimage gridview-simple.png
+    \endfloat
+
+    This model can be referenced as \c ContactModel in other QML files. See \l{QML Modules}
+    for more information about creating reusable components like this.
+
+    Another component can display this model data in a GridView, as in the following
+    example, which creates a \c ContactModel component for its model, and a \l Column element
+    (containing \l Image and \l Text elements) for its delegate.
 
+    \clearfloat
     \snippet doc/src/snippets/declarative/gridview/gridview.qml import
     \codeline
     \snippet doc/src/snippets/declarative/gridview/gridview.qml classdocs simple
-    \image gridview-simple.png
 
-    Here, the GridView creates a \c ContactModel component for its model, and a \l Column element
-    (containing \l Image and \ Text elements) for its delegate. The view will create a new delegate 
-    for each item in the model. Notice the delegate is able to access the model's \c name and 
-    \c portrait data directly.
+    \beginfloatright
+    \inlineimage gridview-highlight.png
+    \endfloat
+
+    The view will create a new delegate for each item in the model. Note that the delegate
+    is able to access the model's \c name and \c portrait data directly.
 
     An improved grid view is shown below. The delegate is visually improved and is moved 
     into a separate \c contactDelegate component.
-    
+
+    \clearfloat
     \snippet doc/src/snippets/declarative/gridview/gridview.qml classdocs advanced
-    \image gridview-highlight.png
 
     The currently selected item is highlighted with a blue \l Rectangle using the \l highlight property,
     and \c focus is set to \c true to enable keyboard navigation for the grid view.
@@ -1099,10 +1113,10 @@ void QDeclarativeGridViewPrivate::flick(AxisData &data, qreal minExtent, qreal m
     Delegates are instantiated as needed and may be destroyed at any time.
     State should \e never be stored in a delegate.
 
-    \note Views do not enable \e clip automatically.  If the view
-    is not clipped by another item or the screen, it will be necessary
-    to set \e {clip: true} in order to have the out of view items clipped
-    nicely.
+    \note Views do not set the \l{Item::}{clip} property automatically.
+    If the view is not clipped by another item or the screen, it will be necessary
+    to set this property to true in order to clip the items that are partially or
+    fully outside the view.
 
     \sa {declarative/modelviews/gridview}{GridView example}
 */
diff --git a/src/declarative/graphicsitems/qdeclarativelistview.cpp b/src/declarative/graphicsitems/qdeclarativelistview.cpp
index ae504aa..c1e6aaa 100644
--- a/src/declarative/graphicsitems/qdeclarativelistview.cpp
+++ b/src/declarative/graphicsitems/qdeclarativelistview.cpp
@@ -1394,11 +1394,14 @@ void QDeclarativeListViewPrivate::flick(AxisData &data, qreal minExtent, qreal m
     QAbstractListModel.
 
     A ListView has a \l model, which defines the data to be displayed, and
-    a \l delegate, which defines how the data should be displayed. Items in a 
-    ListView are laid out horizontally or vertically. List views are inherently flickable
-    as ListView inherits from \l Flickable.
+    a \l delegate, which defines how the data should be displayed. Items in a
+    ListView are laid out horizontally or vertically. List views are inherently
+    flickable because ListView inherits from \l Flickable.
 
-    For example, if there is a simple list model defined in a file \c ContactModel.qml like this:
+    \section1 Example Usage
+
+    The following example shows the definition of a simple list model defined
+    in a file called \c ContactModel.qml:
 
     \snippet doc/src/snippets/declarative/listview/ContactModel.qml 0
 
@@ -1416,7 +1419,7 @@ void QDeclarativeListViewPrivate::flick(AxisData &data, qreal minExtent, qreal m
 
     An improved list view is shown below. The delegate is visually improved and is moved 
     into a separate \c contactDelegate component.
-    
+
     \snippet doc/src/snippets/declarative/listview/listview.qml classdocs advanced
     \image listview-highlight.png
 
diff --git a/src/declarative/graphicsitems/qdeclarativeloader.cpp b/src/declarative/graphicsitems/qdeclarativeloader.cpp
index 5d71625..1066c2b 100644
--- a/src/declarative/graphicsitems/qdeclarativeloader.cpp
+++ b/src/declarative/graphicsitems/qdeclarativeloader.cpp
@@ -212,8 +212,8 @@ QDeclarativeLoader::~QDeclarativeLoader()
     \qmlproperty url Loader::source
     This property holds the URL of the QML component to instantiate.
 
-    Note the QML component must be an \l Item-based component. Loader cannot
-    load non-visual components.
+    Note the QML component must be an \l{Item}-based component. The loader
+    cannot load non-visual components.
 
     To unload the currently loaded item, set this property to an empty string,
     or set \l sourceComponent to \c undefined.
@@ -275,8 +275,8 @@ void QDeclarativeLoader::setSource(const QUrl &url)
     }
     \endqml
 
-    To unload the currently loaded item, set this property to an empty string,
-    or set \l sourceComponent to \c undefined.
+    To unload the currently loaded item, set this property to an empty string
+    or \c undefined.
 
     \sa source, progress
 */
diff --git a/src/declarative/graphicsitems/qdeclarativemousearea.cpp b/src/declarative/graphicsitems/qdeclarativemousearea.cpp
index 4685e65..a0208ef 100644
--- a/src/declarative/graphicsitems/qdeclarativemousearea.cpp
+++ b/src/declarative/graphicsitems/qdeclarativemousearea.cpp
@@ -185,27 +185,57 @@ QDeclarativeMouseAreaPrivate::~QDeclarativeMouseAreaPrivate()
     \brief The MouseArea item enables simple mouse handling.
     \inherits Item
 
-    A MouseArea is typically used in conjunction with a visible item,
-    where the MouseArea effectively 'proxies' mouse handling for that
-    item. For example, we can put a MouseArea in a \l Rectangle that changes
+    A MouseArea is an invisible item that is typically used in conjunction with
+    a visible item in order to provide mouse handling for that item.
+    By effectively acting as a proxy, the logic for mouse handling can be
+    contained within a MouseArea item.
+
+    For basic key handling, see the \l{Keys}{Keys attached property}.
+
+    The \l enabled property is used to enable and disable mouse handling for
+    the proxied item. When disabled, the mouse area becomes transparent to
+    mouse events.
+
+    The \l pressed read-only property indicates whether or not the user is
+    holding down a mouse button over the mouse area. This property is often
+    used in bindings between properties in a user interface. The containsMouse
+    read-only property indicates the presence of the mouse cursor over the
+    mouse area but, by default, only when a mouse button is held down; see below
+    for further details.
+
+    Information about the mouse position and button clicks are provided via
+    signals for which event handler properties are defined. The most commonly
+    used involved handling mouse presses and clicks: onClicked, onDoubleClicked,
+    onPressed, onReleased and onPressAndHold.
+
+    By default, MouseArea items only report mouse clicks and not changes to the
+    position of the mouse cursor. Setting the hoverEnabled property ensures that
+    handlers defined for onPositionChanged, onEntered and onExited are used and
+    that the containsMouse property is updated even when no mouse buttons are
+    pressed.
+
+    \section1 Example Usage
+
+    \beginfloatright
+    \inlineimage qml-mousearea-snippet.png
+    \endfloat
+
+    The following example uses a MouseArea in a \l Rectangle that changes
     the \l Rectangle color to red when clicked:
 
-    \snippet doc/src/snippets/declarative/mousearea.qml import
+    \snippet doc/src/snippets/declarative/mousearea/mousearea.qml import
     \codeline
-    \snippet doc/src/snippets/declarative/mousearea.qml intro
+    \snippet doc/src/snippets/declarative/mousearea/mousearea.qml intro
 
-    Many MouseArea signals pass a \l {MouseEvent}{mouse} parameter that contains
+    \clearfloat
+    Many MouseArea signals pass a \l{MouseEvent}{mouse} parameter that contains
     additional information about the mouse event, such as the position, button,
     and any key modifiers.
 
     Here is an extension of the previous example that produces a different
     color when the area is right clicked:
 
-    \snippet doc/src/snippets/declarative/mousearea.qml intro-extended
-
-    For basic key handling, see the \l {Keys}{Keys attached property}.
-
-    MouseArea is an invisible item: it is never painted.
+    \snippet doc/src/snippets/declarative/mousearea/mousearea.qml intro-extended
 
     \sa MouseEvent, {declarative/touchinteraction/mousearea}{MouseArea example}
 */
@@ -312,11 +342,14 @@ QDeclarativeMouseAreaPrivate::~QDeclarativeMouseAreaPrivate()
     \qmlsignal MouseArea::onCanceled()
 
     This handler is called when mouse events have been canceled, either because an event was not accepted, or
-    because another element stole the mouse event handling. This signal is for advanced use: it is useful when
-    there is more than one MouseArea that is handling input, or when there is a MouseArea inside a \l Flickable. In the latter
-    case, if you execute some logic on the pressed signal and then start dragging, the \l Flickable will steal the mouse handling
-    from the MouseArea. In these cases, to reset the logic when the MouseArea has lost the mouse handling to the
-    \l Flickable, \c onCanceled should be used in addition to onReleased.
+    because another element stole the mouse event handling.
+
+    This signal is for advanced use: it is useful when there is more than one MouseArea
+    that is handling input, or when there is a MouseArea inside a \l Flickable. In the latter
+    case, if you execute some logic on the pressed signal and then start dragging, the
+    \l Flickable will steal the mouse handling from the MouseArea. In these cases, to reset
+    the logic when the MouseArea has lost the mouse handling to the \l Flickable,
+    \c onCanceled should be used in addition to onReleased.
 */
 
 QDeclarativeMouseArea::QDeclarativeMouseArea(QDeclarativeItem *parent)
@@ -333,11 +366,13 @@ QDeclarativeMouseArea::~QDeclarativeMouseArea()
 /*!
     \qmlproperty real MouseArea::mouseX
     \qmlproperty real MouseArea::mouseY
-    These properties hold the coordinates of the mouse.
+    These properties hold the coordinates of the mouse cursor.
 
     If the hoverEnabled property is false then these properties will only be valid
     while a button is pressed, and will remain valid as long as the button is held
-    even if the mouse is moved outside the area.
+    down even if the mouse is moved outside the area.
+
+    By default, this property is false.
 
     If hoverEnabled is true then these properties will be valid when:
     \list
@@ -362,6 +397,8 @@ qreal QDeclarativeMouseArea::mouseY() const
 /*!
     \qmlproperty bool MouseArea::enabled
     This property holds whether the item accepts mouse events.
+
+    By default, this property is true.
 */
 bool QDeclarativeMouseArea::isEnabled() const
 {
@@ -389,7 +426,8 @@ void QDeclarativeMouseArea::setEnabled(bool a)
     \endlist
 
     The code below displays "right" when the right mouse buttons is pressed:
-    \snippet doc/src/snippets/declarative/mousearea.qml mousebuttons
+
+    \snippet doc/src/snippets/declarative/mousearea/mousearea.qml mousebuttons
 
     \sa acceptedButtons
 */
@@ -707,7 +745,8 @@ QVariant QDeclarativeMouseArea::itemChange(GraphicsItemChange change,
     pressed.  Hover enables handling of all mouse events even when no mouse button is
     pressed.
 
-    This property affects the containsMouse property and the onEntered, onExited and onPositionChanged signals.
+    This property affects the containsMouse property and the onEntered, onExited and
+    onPositionChanged signals.
 */
 bool QDeclarativeMouseArea::hoverEnabled() const
 {
@@ -850,7 +889,7 @@ QDeclarativeDrag *QDeclarativeMouseArea::drag()
     The following example displays a \l Rectangle that can be dragged along the X-axis. The opacity
     of the rectangle is reduced when it is dragged to the right.
 
-    \snippet doc/src/snippets/declarative/mousearea.qml drag
+    \snippet doc/src/snippets/declarative/mousearea/mousearea.qml drag
 
     \note Items cannot be dragged if they are anchored for the requested 
     \c drag.axis. For example, if \c anchors.left or \c anchors.right was set
@@ -861,7 +900,7 @@ QDeclarativeDrag *QDeclarativeMouseArea::drag()
     If \c drag.filterChildren is set to true, a drag can override descendant MouseAreas.  This
     enables a parent MouseArea to handle drags, for example, while descendants handle clicks:
 
-    \snippet doc/src/snippets/declarative/mouseareadragfilter.qml dragfilter
+    \snippet doc/src/snippets/declarative/mousearea/mouseareadragfilter.qml dragfilter
 
 */
 
diff --git a/src/declarative/graphicsitems/qdeclarativepathview.cpp b/src/declarative/graphicsitems/qdeclarativepathview.cpp
index de3f9fa..dad547f 100644
--- a/src/declarative/graphicsitems/qdeclarativepathview.cpp
+++ b/src/declarative/graphicsitems/qdeclarativepathview.cpp
@@ -404,14 +404,14 @@ QDeclarativePathView::~QDeclarativePathView()
     be instantiated, but not considered to be currently on the path.
     Usually, these items would be set invisible, for example:
 
-    \code
+    \qml
     Component {
         Rectangle {
             visible: PathView.onPath
             ...
         }
     }
-    \endcode
+    \endqml
 
     It is attached to each instance of the delegate.
 */
diff --git a/src/declarative/graphicsitems/qdeclarativerectangle.cpp b/src/declarative/graphicsitems/qdeclarativerectangle.cpp
index d027924..9831d5f 100644
--- a/src/declarative/graphicsitems/qdeclarativerectangle.cpp
+++ b/src/declarative/graphicsitems/qdeclarativerectangle.cpp
@@ -85,8 +85,8 @@ void QDeclarativePen::setWidth(int w)
 /*!
     \qmlclass GradientStop QDeclarativeGradientStop
     \ingroup qml-basic-visual-elements
-  \since 4.7
-    \brief The GradientStop item defines the color at a position in a Gradient
+    \since 4.7
+    \brief The GradientStop item defines the color at a position in a Gradient.
 
     \sa Gradient
 */
@@ -95,7 +95,12 @@ void QDeclarativePen::setWidth(int w)
     \qmlproperty real GradientStop::position
     \qmlproperty color GradientStop::color
 
-    Sets a \e color at a \e position in a gradient.
+    The position and color properties describe the color used at a given
+    position in a gradient, as represented by a gradient stop.
+
+    The default position is 0.0; the default color is black.
+
+    \sa Gradient
 */
 
 void QDeclarativeGradientStop::updateGradient()
@@ -107,20 +112,50 @@ void QDeclarativeGradientStop::updateGradient()
 /*!
     \qmlclass Gradient QDeclarativeGradient
     \ingroup qml-basic-visual-elements
-  \since 4.7
+    \since 4.7
     \brief The Gradient item defines a gradient fill.
 
-    A gradient is defined by two or more colors, which will be blended seemlessly.  The
-    colors are specified at their position in the range 0.0 - 1.0 via
-    the GradientStop item.  For example, the following code paints a
-    rectangle with a gradient starting with red, blending to yellow at 1/3 of the
-    size of the rectangle, and ending with Green:
+    A gradient is defined by two or more colors, which will be blended seamlessly.
 
-    \snippet doc/src/snippets/declarative/gradient.qml code
+    The colors are specified as a set of GradientStop child items, each of
+    which defines a position on the gradient from 0.0 to 1.0 and a color.
+    The position of each GradientStop is defined by setting its
+    \l{GradientStop::}{position} property; its color is defined using its
+    \l{GradientStop::}{color} property.
+
+    A gradient without any gradient stops is rendered as a solid white fill.
 
     Note that this item is not a visual representation of a gradient. To display a
-    gradient use a visual item (like rectangle) which supports having a gradient set
-    on it for display.
+    gradient, use a visual element (like \l Rectangle) which supports the use
+    of gradients.
+
+    \section1 Example Usage
+
+    \beginfloatright
+    \inlineimage qml-gradient.png
+    \endfloat
+
+    The following example declares a \l Rectangle item with a gradient starting
+    with red, blending to yellow at one third of the height of the rectangle,
+    and ending with green:
+
+    \snippet doc/src/snippets/declarative/gradient.qml code
+
+    \clearfloat
+    \section1 Performance and Limitations
+
+    Calculating gradients can be computationally expensive compared to the use
+    of solid color fills or images. Consider using gradients for static items
+    in a user interface.
+
+    In Qt 4.7, only vertical, linear gradients can be applied to items. If you
+    need to apply different orientations of gradients, a combination of rotation
+    and clipping will need to be applied to the relevant items. This can
+    introduce additional performance requirements for your application.
+
+    The use of animations involving gradient stops may not give the desired
+    result. An alternative way to animate gradients is to use pre-generated
+    images or SVG drawings containing gradients.
 
     \sa GradientStop
 */
@@ -128,6 +163,10 @@ void QDeclarativeGradientStop::updateGradient()
 /*!
     \qmlproperty list<GradientStop> Gradient::stops
     This property holds the gradient stops describing the gradient.
+
+    By default, this property contains an empty list.
+
+    To set the gradient stops, define them as children of the Gradient element.
 */
 
 const QGradient *QDeclarativeGradient::gradient() const
@@ -155,27 +194,46 @@ void QDeclarativeGradient::doUpdate()
 /*!
     \qmlclass Rectangle QDeclarativeRectangle
     \ingroup qml-basic-visual-elements
-  \since 4.7
-    \brief The Rectangle item allows you to add rectangles to a scene.
+    \since 4.7
+    \brief The Rectangle item provides a filled rectangle with an optional border.
     \inherits Item
 
-    A Rectangle is painted using a solid fill (color) and an optional border.
-    You can also create rounded rectangles using the \l radius property.
+    Rectangle items are used to fill areas with solid color or gradients, and are
+    often used to hold other items.
 
-    \qml
-    import Qt 4.7
-
-    Rectangle {
-        width: 100
-        height: 100
-        color: "red"
-        border.color: "black"
-        border.width: 5
-        radius: 10
-    }
-    \endqml
+    \section1 Appearance
+
+    Each Rectangle item is painted using either a solid fill color, specified using
+    the \l color property, or a gradient, defined using a Gradient element and set
+    using the \l gradient property. If both a color and a gradient are specified,
+    the gradient is used.
+
+    You can add an optional border to a rectangle with its own color and thickness
+    by settting the \l border.color and \l border.width properties.
+
+    You can also create rounded rectangles using the \l radius property. Since this
+    introduces curved edges to the corners of a rectangle, it may be appropriate to
+    set the \l smooth property to improve its appearance.
 
-    \image declarative-rect.png
+    \section1 Example Usage
+
+    \beginfloatright
+    \inlineimage declarative-rect.png
+    \endfloat
+
+    The following example shows the effects of some of the common properties on a
+    Rectangle item, which in this case is used to create a square:
+
+    \snippet doc/src/snippets/declarative/rectangle/rectangle.qml document
+
+    \clearfloat
+    \section1 Performance
+
+    Using the \l smooth property improves the appearance of a rounded rectangle at
+    the cost of rendering performance. You should consider unsetting this property
+    for rectangles in motion, and only set it when they are stationary.
+
+    \sa Image
 */
 
 int QDeclarativeRectanglePrivate::doUpdateSlotIdx = -1;
@@ -207,13 +265,14 @@ void QDeclarativeRectangle::doUpdate()
     rectangle's boundaries, and the spare pixel is rendered to the right and below the
     rectangle (as documented for QRect rendering). This can cause unintended effects if 
     \c border.width is 1 and the rectangle is \l{Item::clip}{clipped} by a parent item:
-   
-    \table
-    \row
-    \o \snippet doc/src/snippets/declarative/rect-border-width.qml 0
-    \o \image rect-border-width.png
-    \endtable
 
+    \beginfloatright
+    \inlineimage rect-border-width.png
+    \endfloat
+
+    \snippet doc/src/snippets/declarative/rectangle/rect-border-width.qml 0
+
+    \clearfloat
     Here, the innermost rectangle's border is clipped on the bottom and right edges by its
     parent. To avoid this, the border width can be set to two instead of one.
 */
@@ -231,34 +290,12 @@ QDeclarativePen *QDeclarativeRectangle::border()
     This property allows for the construction of simple vertical gradients.
     Other gradients may by formed by adding rotation to the rectangle.
 
-    \table
-    \row
-    \o \image declarative-rect_gradient.png
-    \o
-    \qml
-    Rectangle {
-        y: 0; width: 80; height: 80
-        color: "lightsteelblue"
-    }
-
-    Rectangle {
-        y: 100; width: 80; height: 80
-        gradient: Gradient {
-            GradientStop { position: 0.0; color: "lightsteelblue" }
-            GradientStop { position: 1.0; color: "blue" }
-        }
-    }
+    \beginfloatleft
+    \inlineimage declarative-rect_gradient.png
+    \endfloat
 
-    Rectangle {
-        y: 200; width: 80; height: 80
-        rotation: 90
-        gradient: Gradient {
-            GradientStop { position: 0.0; color: "lightsteelblue" }
-            GradientStop { position: 1.0; color: "blue" }
-        }
-    }
-    \endqml
-    \endtable
+    \snippet doc/src/snippets/declarative/rectangle/rectangle-gradient.qml rectangles
+    \clearfloat
 
     If both a gradient and a color are specified, the gradient will be used.
 
@@ -319,17 +356,21 @@ void QDeclarativeRectangle::setRadius(qreal radius)
     \qmlproperty color Rectangle::color
     This property holds the color used to fill the rectangle.
 
-    \qml
-    // green rectangle using hexidecimal notation
-    Rectangle { color: "#00FF00" }
+    The default color is white.
 
-    // steelblue rectangle using SVG color name
-    Rectangle { color: "steelblue" }
-    \endqml
+    \beginfloatright
+    \inlineimage rect-color.png
+    \endfloat
 
-    The default color is white.
+    The following example shows rectangles with colors specified
+    using hexadecimal and named color notation:
 
+    \snippet doc/src/snippets/declarative/rectangle/rectangle-colors.qml rectangles
+
+    \clearfloat
     If both a gradient and a color are specified, the gradient will be used.
+
+    \sa gradient
 */
 QColor QDeclarativeRectangle::color() const
 {
diff --git a/src/declarative/util/qdeclarativelistmodel.cpp b/src/declarative/util/qdeclarativelistmodel.cpp
index f290ab2..cf2eada 100644
--- a/src/declarative/util/qdeclarativelistmodel.cpp
+++ b/src/declarative/util/qdeclarativelistmodel.cpp
@@ -69,49 +69,67 @@ QDeclarativeListModelParser::ListInstruction *QDeclarativeListModelParser::ListM
     \since 4.7
     \brief The ListModel element defines a free-form list data source.
 
-    The ListModel is a simple hierarchy of elements containing data roles. The contents can
-    be defined dynamically, or explicitly in QML:
+    The ListModel is a simple container of ListElement definitions, each containing data roles.
+    The contents can be defined dynamically, or explicitly in QML.
 
-    For example:
+    The number of elements in the model can be obtained from its \l count property.
+    A number of familiar methods are also provided to manipulate the contents of the
+    model, including append(), insert(), move(), remove() and set(). These methods
+    accept dictionaries as their arguments; these are translated to ListElement objects
+    by the model.
 
-    \snippet doc/src/snippets/declarative/listmodel.qml 0
+    Elements can be manipulated via the model using the setProperty() method, which
+    allows the roles of the specified element to be set and changed.
+
+    \section1 Example Usage
+
+    The following example shows a ListModel containing three elements, with the roles
+    "name" and "cost".
 
-    Roles (properties) must begin with a lower-case letter. The above example defines a
-    ListModel containing three elements, with the roles "name" and "cost".
+    \beginfloatright
+    \inlineimage listmodel.png
+    \endfloat
+
+    \snippet doc/src/snippets/declarative/listmodel.qml 0
 
-    Values must be simple constants - either strings (quoted and optionally within a call to QT_TR_NOOP),
-    bools (true, false), numbers, or enum values (like Text.AlignHCenter).
+    \clearfloat
+    Roles (properties) in each element must begin with a lower-case letter and
+    should be common to all elements in a model. The ListElement documentation
+    provides more guidelines for how elements should be defined.
 
-    The defined model can be used in views such as ListView:
+    Since the example model contains an \c id property, it can be referenced
+    by views, such as the ListView in this example:
 
     \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:
+    It is possible for roles to contain list data.  In the following example we
+    create a list of fruit attributes:
 
     \snippet doc/src/snippets/declarative/listmodel-nested.qml model
 
-    The delegate below displays all the fruit attributes:
+    The delegate displays all the fruit attributes:
 
-    \snippet doc/src/snippets/declarative/listmodel-nested.qml delegate
-    \image listmodel-nested.png
+    \beginfloatright
+    \inlineimage listmodel-nested.png
+    \endfloat
 
+    \snippet doc/src/snippets/declarative/listmodel-nested.qml delegate
 
-    \section2 Modifying list models
+    \clearfloat
+    \section1 Modifying List Models
 
     The content of a ListModel may be created and modified using the clear(),
     append(), set() and setProperty() methods.  For example:
-    
-    \snippet doc/src/snippets/declarative/listmodel-modify.qml delegate
 
-    Note that when creating content dynamically the set of available properties cannot be changed
-    once set. Whatever properties are first added to the model are the
-    only permitted properties in the model.
+    \snippet doc/src/snippets/declarative/listmodel-modify.qml delegate
 
+    Note that when creating content dynamically the set of available properties
+    cannot be changed once set. Whatever properties are first added to the model
+    are the only permitted properties in the model.
 
-    \section2 Using threaded list models with WorkerScript
+    \section1 Using Threaded List Models with WorkerScript
 
     ListModel can be used together with WorkerScript access a list model
     from multiple threads. This is useful if list modifications are
@@ -127,16 +145,16 @@ QDeclarativeListModelParser::ListInstruction *QDeclarativeListModelParser::ListM
 
     \snippet examples/declarative/threading/threadedlistmodel/dataloader.js 0
 
-working-with-data
-    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.
+    The timer in the main example sends messages to the worker script by calling
+    \l WorkerScript::sendMessage(). When this message is received,
+    \l{WorkerScript::onMessage}{WorkerScript.onMessage()} is invoked in \c dataloader.js,
+    which appends the current time to the list model.
 
-    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
+    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.
 
-    \section3 Limitations
+    \section1 Limitations
 
     If a list model is to be accessed from a WorkerScript, it \bold cannot
     contain list data. So, the following model cannot be used from a WorkerScript
@@ -771,6 +789,39 @@ bool QDeclarativeListModelParser::definesEmptyList(const QString &s)
     \since 4.7
     \brief The ListElement element defines a data item in a ListModel.
 
+    List elements are defined inside ListModel definitions, and represent items in a
+    list that will be displayed using ListView or \l Repeater items.
+
+    List elements are defined like other QML elements except that they contain
+    a collection of \e role definitions instead of properties. Using the same
+    syntax as property definitions, roles both define how the data is accessed
+    and include the data itself.
+
+    The names used for roles must begin with a lower-case letter and should be
+    common to all elements in a given model. Values must be simple constants; either
+    strings (quoted and optionally within a call to QT_TR_NOOP), boolean values
+    (true, false), numbers, or enumeration values (such as AlignText.AlignHCenter).
+
+    \section1 Referencing Roles
+
+    The role names are used by delegates to obtain data from list elements.
+    Each role name is accessible in the delegate's scope, and refers to the
+    corresponding role in the current element. Where a role name would be
+    ambiguous to use, it can be accessed via the \l{ListView::}{model}
+    property (e.g., \c{model.cost} instead of \c{cost}).
+
+    \section1 Example Usage
+
+    The following model defines a series of list elements, each of which
+    contain "name" and "cost" roles and their associated values.
+
+    \snippet doc/src/snippets/declarative/qml-data-models/listelements.qml model
+
+    The delegate obtains the name and cost for each element by simply referring
+    to \c name and \c cost:
+
+    \snippet doc/src/snippets/declarative/qml-data-models/listelements.qml view
+
     \sa ListModel
 */