doc improvements

7 files changed, 83 insertions, 30 deletions

diff --git a/src/declarative/qml/qdeclarativecomponent.cpp b/src/declarative/qml/qdeclarativecomponent.cpp
index 9d3032c..6d15278 100644
--- a/src/declarative/qml/qdeclarativecomponent.cpp
+++ b/src/declarative/qml/qdeclarativecomponent.cpp
@@ -70,6 +70,36 @@ class QByteArray;
     \since 4.7
     \brief The QDeclarativeComponent class encapsulates a QML component description.
     \mainclass
+
+    Components are reusable, encapsulated QML elements with well-defined interfaces.
+    They are often defined in \l {qdeclarativedocuments.html}{Component Files}.
+
+    A QDeclarativeComponent instance can be created from a QML file.
+    For example, if there is a \c main.qml file like this:
+
+    \qml
+    import Qt 4.7
+
+    Item {
+        width: 200
+        height: 200
+    }
+    \endqml
+
+    The following code loads this QML file as a component, creates an instance of
+    this component using create(), and then queries the \l Item's \l {Item::}{width}
+    value:
+
+    \code
+    QDeclarativeEngine *engine = new QDeclarativeEngine;
+    QDeclarativeComponent component(engine, QUrl::fromLocalFile("main.qml"));
+
+    QObject *myObject = component.create();
+    QDeclarativeItem *item = qobject_cast<QDeclarativeItem*>(myObject);
+    int width = item->width();
+    \endcode
+
+    \sa {Using QML in C++ Applications}
 */
 
 /*!
diff --git a/src/declarative/qml/qdeclarativecontext.cpp b/src/declarative/qml/qdeclarativecontext.cpp
index 60e9dd3..3d25291 100644
--- a/src/declarative/qml/qdeclarativecontext.cpp
+++ b/src/declarative/qml/qdeclarativecontext.cpp
@@ -145,6 +145,8 @@ QDeclarativeContextPrivate::QDeclarativeContextPrivate()
     has been created in that context is an expensive operation (essentially forcing all bindings
     to reevaluate). Thus whenever possible you should complete "setup" of the context
     before using it to create any objects.
+
+    \sa {Using QML in C++ Applications}
 */
 
 /*! \internal */
diff --git a/src/declarative/qml/qdeclarativeexpression.cpp b/src/declarative/qml/qdeclarativeexpression.cpp
index 8ae5f2f..96cdec1 100644
--- a/src/declarative/qml/qdeclarativeexpression.cpp
+++ b/src/declarative/qml/qdeclarativeexpression.cpp
@@ -214,8 +214,30 @@ QScriptValue QDeclarativeExpressionPrivate::evalInObjectScope(QDeclarativeContex
 
 /*!
     \class QDeclarativeExpression
-  \since 4.7
+    \since 4.7
     \brief The QDeclarativeExpression class evaluates JavaScript in a QML context.
+
+    For example, given a file \c main.qml like this:
+
+    \qml
+    import Qt 4.7
+
+    Item {
+        width: 200; height: 200
+    }
+    \endqml
+
+    The following code evaluates a JavaScript expression in the context of the
+    above QML:
+
+    \code
+    QDeclarativeEngine *engine = new QDeclarativeEngine;
+    QDeclarativeComponent component(engine, QUrl::fromLocalFile("main.qml"));
+
+    QObject *myObject = component.create();
+    QDeclarativeExpression *expr = new QDeclarativeExpression(engine->rootContext(), myObject, "width * 2");
+    int result = expr->evaluate().toInt();  // result = 400
+    \endcode
 */
 
 /*!
diff --git a/src/declarative/qml/qdeclarativeextensionplugin.cpp b/src/declarative/qml/qdeclarativeextensionplugin.cpp
index c2e8300..0660599 100644
--- a/src/declarative/qml/qdeclarativeextensionplugin.cpp
+++ b/src/declarative/qml/qdeclarativeextensionplugin.cpp
@@ -67,10 +67,8 @@ QT_BEGIN_NAMESPACE
     See \l {Tutorial: Writing QML extensions with C++} for details on creating
     QML extensions, including how to build a plugin with with QDeclarativeExtensionPlugin.
     For a simple overview, see the \l{declarative/cppextensions/plugins}{plugins} example.
-    
-    Also see \l {How to Create Qt Plugins} for general Qt plugin documentation.
 
-    \sa QDeclarativeEngine::importPlugin()
+    \sa QDeclarativeEngine::importPlugin(), {How to Create Qt Plugins}
 */
 
 /*!
diff --git a/src/declarative/util/qdeclarativepackage.cpp b/src/declarative/util/qdeclarativepackage.cpp
index 1e49ad9..1a4f2a7 100644
--- a/src/declarative/util/qdeclarativepackage.cpp
+++ b/src/declarative/util/qdeclarativepackage.cpp
@@ -65,12 +65,12 @@ QT_BEGIN_NAMESPACE
     \snippet examples/declarative/modelviews/package/Delegate.qml 0
 
     These named items are used as the delegates by the two views who
-    reference the special VisualDataModel.parts property to select
+    reference the special \l{VisualDataModel::parts} property to select
     a model which provides the chosen delegate.
 
     \snippet examples/declarative/modelviews/package/view.qml 0
 
-    \sa {declarative/modelviews/package}{Package example}, QtDeclarative
+    \sa {declarative/modelviews/package}{Package example}, {demos/declarative/photoviewer}{Photo Viewer demo}, QtDeclarative
 */
 
 /*!
diff --git a/src/declarative/util/qdeclarativeview.cpp b/src/declarative/util/qdeclarativeview.cpp
index 12a8d3a..496f2ad 100644
--- a/src/declarative/util/qdeclarativeview.cpp
+++ b/src/declarative/util/qdeclarativeview.cpp
@@ -194,45 +194,46 @@ void QDeclarativeViewPrivate::itemGeometryChanged(QDeclarativeItem *resizeItem,
   \since 4.7
     \brief The QDeclarativeView class provides a widget for displaying a Qt Declarative user interface.
 
-    Any QGraphicsObject or QDeclarativeItem
-    created via QML can be placed on a standard QGraphicsScene and viewed with a standard
-    QGraphicsView.
+    QDeclarativeItem objects can be placed on a standard QGraphicsScene and 
+    displayed with QGraphicsView. QDeclarativeView is a QGraphicsView subclass 
+    provided as a convenience for displaying QML files, and connecting between 
+    QML and C++ Qt objects.
 
-    QDeclarativeView is a QGraphicsView subclass provided as a convenience for displaying QML
-    files, and connecting between QML and C++ Qt objects.
-
-    QDeclarativeView performs the following functions:
+    QDeclarativeView provides:
 
     \list
-    \o Manages QDeclarativeComponent loading and object creation.
-    \o Initializes QGraphicsView for optimal performance with QML:
+    \o Management of QDeclarativeComponent loading and object creation
+    \o Initialization of QGraphicsView for optimal performance with QML using these settings:
         \list
-        \o QGraphicsView::setOptimizationFlags(QGraphicsView::DontSavePainterState);
-        \o QGraphicsView::setViewportUpdateMode(QGraphicsView::BoundingRectViewportUpdate);
-        \o QGraphicsScene::setItemIndexMethod(QGraphicsScene::NoIndex);
+        \o QGraphicsView::setOptimizationFlags(QGraphicsView::DontSavePainterState)
+        \o QGraphicsView::setViewportUpdateMode(QGraphicsView::BoundingRectViewportUpdate)
+        \o QGraphicsScene::setItemIndexMethod(QGraphicsScene::NoIndex)
         \endlist
-    \o Initializes QGraphicsView for QML key handling:
+    \o Initialization of QGraphicsView for QML key handling using these settings:
         \list
-        \o QGraphicsView::viewport()->setFocusPolicy(Qt::NoFocus);
-        \o QGraphicsView::setFocusPolicy(Qt::StrongFocus);
-        \o QGraphicsScene::setStickyFocus(true);
+        \o QGraphicsView::viewport()->setFocusPolicy(Qt::NoFocus)
+        \o QGraphicsView::setFocusPolicy(Qt::StrongFocus)
+        \o QGraphicsScene::setStickyFocus(true)
         \endlist
     \endlist
 
     Typical usage:
-    \code
-    ...
-    QDeclarativeView *view = new QDeclarativeView(this);
-    vbox->addWidget(view);
 
-    QUrl url = QUrl::fromLocalFile(fileName);
-    view->setSource(url);
+    \code
+    QDeclarativeView *view = new QDeclarativeView;
+    view->setSource(QUrl::fromLocalFile("myqmlfile.qml"));
     view->show();
     \endcode
 
+    Since QDeclarativeView is a QWidget-based class, it can be used to
+    display QML interfaces within QWidget-based GUI applications that do not
+    use the Graphics View framework.
+
     To receive errors related to loading and executing QML with QDeclarativeView,
     you can connect to the statusChanged() signal and monitor for QDeclarativeView::Error.
     The errors are available via QDeclarativeView::errors().
+
+    \sa {Integrating QML with existing Qt UI code}, {Using QML in C++ Applications}
 */
 
 
diff --git a/src/declarative/util/qdeclarativexmllistmodel.cpp b/src/declarative/util/qdeclarativexmllistmodel.cpp
index 5583007..00169db 100644
--- a/src/declarative/util/qdeclarativexmllistmodel.cpp
+++ b/src/declarative/util/qdeclarativexmllistmodel.cpp
@@ -667,7 +667,7 @@ QString QDeclarativeXmlListModel::toString(int role) const
     \qmlproperty url XmlListModel::source
     The location of the XML data source.
 
-    If both source and xml are set, xml will be used.
+    If both \c source and \l xml are set, \l xml is used.
 */
 QUrl QDeclarativeXmlListModel::source() const
 {
@@ -692,7 +692,7 @@ void QDeclarativeXmlListModel::setSource(const QUrl &src)
 
     The text is assumed to be UTF-8 encoded.
 
-    If both \l source and \c xml are set, \c xml will be used.
+    If both \l source and \c xml are set, \c xml is used.
 */
 QString QDeclarativeXmlListModel::xml() const
 {