Doc improvements

1 files changed, 50 insertions, 18 deletions

diff --git a/src/declarative/util/qdeclarativexmllistmodel.cpp b/src/declarative/util/qdeclarativexmllistmodel.cpp
index b9afa1f..f02ed16 100644
--- a/src/declarative/util/qdeclarativexmllistmodel.cpp
+++ b/src/declarative/util/qdeclarativexmllistmodel.cpp
@@ -472,39 +472,71 @@ void QDeclarativeXmlListModelPrivate::clear_role(QDeclarativeListProperty<QDecla
   \since 4.7
     \brief The XmlListModel element is used to specify a model using XPath expressions.
 
-    XmlListModel is used to create a model from XML data that can be used as a data source
+    XmlListModel is used to create a model from XML data. XmlListModel can be used as a data source
     for the view classes (such as ListView, PathView, GridView) and other classes that interact with model
-    data (such as Repeater).
+    data (such as \l Repeater).
+
+    For example, if there is a XML document at http://www.mysite.com/feed.xml like this:
+
+    \code
+    <?xml version="1.0" encoding="utf-8"?>
+    <rss version="2.0">
+        ...
+        <channel>
+            <item>
+                <title>Item A</title>
+                <pubDate>Sat, 07 Sep 2010 10:00:01 GMT</pubDate>
+            </item>
+            <item>
+                <title>Item B</title>
+                <pubDate>Sat, 07 Sep 2010 15:35:01 GMT</pubDate>
+            </item>
+        </channel>
+    </rss>
+    \endcode
+
+    Then it could be used to create the following model:
 
-    Here is an example of a model containing news from a Yahoo RSS feed:
     \qml
     XmlListModel {
-        source: "http://rss.news.yahoo.com/rss/oceania"
+        source: "http://www.mysite.com/feed.xml"
         query: "/rss/channel/item"
         XmlRole { name: "title"; query: "title/string()" }
         XmlRole { name: "pubDate"; query: "pubDate/string()" }
-        XmlRole { name: "description"; query: "description/string()" }
     }
     \endqml
 
-    You can also define certain roles as "keys" so that the model only adds data
-    that contains new values for these keys when reload() is called.
+    The \l {XmlListModel::query}{query} value of "/rss/channel/item" specifies that the XmlListModel should generate
+    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 
+    attributes that match the \c title and \c pubDate values of its corresponding \c <item>.
 
-    For example, if the roles above were defined like this:
+
+    \section2 Using key XML roles
+
+    You can define certain roles as "keys" so that when reload() is called,
+    the model will only add and refresh data that contains new values for
+    these keys.
+
+    For example, if above role for "pubDate" was defined like this instead:
 
     \qml
-        XmlRole { name: "title"; query: "title/string()"; isKey: true }
         XmlRole { name: "pubDate"; query: "pubDate/string()"; isKey: true }
     \endqml
 
-    Then when reload() is called, the model will only add new items with a
-    "title" and "pubDate" value combination that is not already present in
-    the model.
+    Then when reload() is called, the model will only add and reload
+    items with a "pubDate" value that is not already 
+    present in the model. 
 
-    This is useful to provide incremental updates and avoid repainting an
-    entire model in a view.
+    This is useful when displaying the contents of XML documents that
+    are incrementally updated (such as RSS feeds) to avoid repainting the
+    entire contents of a model in a view.
 
-    \sa {QtDeclarative}
+    If multiple key roles are specified, the model only adds and reload items
+    with a combined value of all key roles that is not already present in
+    the model.
+
+    \sa {declarative/xmldata}{XML data example}
 */
 
 QDeclarativeXmlListModel::QDeclarativeXmlListModel(QObject *parent)
@@ -625,8 +657,8 @@ void QDeclarativeXmlListModel::setXml(const QString &xml)
 
 /*!
     \qmlproperty string XmlListModel::query
-    An absolute XPath query representing the base query for the model items. The query should start with
-    '/' or '//'.
+    An absolute XPath query representing the base query for creating model items
+    from this model's XmlRole objects. The query should start with '/' or '//'.
 */
 QString QDeclarativeXmlListModel::query() const
 {
@@ -747,7 +779,7 @@ void QDeclarativeXmlListModel::componentComplete()
     Otherwise, items are only added if the model does not already
     contain items with matching key role values.
     
-    \sa XmlRole::isKey
+    \sa {Using key XML roles}, XmlRole::isKey
 */
 void QDeclarativeXmlListModel::reload()
 {