Doc: More work on the declarative API documentation.

6 files changed, 123 insertions, 54 deletions

diff --git a/src/declarative/graphicsitems/qdeclarativeflickable.cpp b/src/declarative/graphicsitems/qdeclarativeflickable.cpp
index 062bbfb..477c511 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 a0faf14..f152d0d 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 177c5b3..8382970 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/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/util/qdeclarativelistmodel.cpp b/src/declarative/util/qdeclarativelistmodel.cpp
index 60d8aa9..d3cf9c8 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
 */