Doc: More work on the QML documentation.

4 files changed, 95 insertions, 51 deletions

diff --git a/src/3rdparty/webkit/WebKit/qt/declarative/qdeclarativewebview.cpp b/src/3rdparty/webkit/WebKit/qt/declarative/qdeclarativewebview.cpp
index 1538133..67ce708 100644
--- a/src/3rdparty/webkit/WebKit/qt/declarative/qdeclarativewebview.cpp
+++ b/src/3rdparty/webkit/WebKit/qt/declarative/qdeclarativewebview.cpp
@@ -141,46 +141,76 @@ void GraphicsWebView::mouseMoveEvent(QGraphicsSceneMouseEvent* event)
     \qmlclass WebView QDeclarativeWebView
     \ingroup qml-view-elements
     \since 4.7
-    \brief The WebView item allows you to add web content to a canvas.
+    \brief The WebView item allows you to add Web content to a canvas.
     \inherits Item
 
-    A WebView renders web content based on a URL.
+    A WebView renders Web content based on a URL.
 
     This type is made available by importing the \c QtWebKit module:
 
     \bold{import QtWebKit 1.0}
 
-    If the width and height of the item is not set, they will
-    dynamically adjust to a size appropriate for the content.
-    This width may be large for typical online web pages.
+    The WebView item includes no scrolling, scaling, toolbars, or other common browser
+    components. These must be implemented around WebView. See the \l{QML Web Browser}
+    example for a demonstration of this.
 
-    If the width or height is explictly set, the rendered website
-    will be clipped, not scaled, to fit into the set dimensions.
+    The page to be displayed by the item is specified using the \l url property,
+    and this can be changed to fetch and display a new page. While the page loads,
+    the \l progress property is updated to indicate how much of the page has been
+    loaded.
 
-    If the preferredWidth is set, the width will be this amount or larger,
-    usually laying out the web content to fit the preferredWidth.
+    \section1 Appearance
 
-    \qml
-    import QtWebKit 1.0
+    If the width and height of the item is not set, they will dynamically adjust
+    to a size appropriate for the content. This width may be large for typical
+    online web pages, typically greater than 800 by 600 pixels.
 
-    WebView {
-        url: "http://www.nokia.com"
-        preferredWidth: 490
-        preferredHeight: 400
-        scale: 0.5
-        smooth: false
-        smoothCache: true
-    }
-    \endqml
+    If the \l{Item::}{width} or \l{Item::}{height} is explictly set, the rendered Web site will be
+    clipped, not scaled, to fit into the set dimensions.
 
-    \image webview.png
+    If the preferredWidth property is set, the width will be this amount or larger,
+    usually laying out the Web content to fit the preferredWidth.
 
-    The item includes no scrolling, scaling,
-    toolbars, etc., those must be implemented around WebView. See the WebBrowser example
-    for a demonstration of this.
+    The appearance of the content can be controlled to a certain extent by changing
+    the settings.standardFontFamily property and other settings related to fonts.
+
+    The page can be zoomed by calling the heuristicZoom() method, which performs a
+    series of tests to determine whether zoomed content will be displayed in an
+    appropriate way in the space allocated to the item.
+
+    \section1 User Interaction and Navigation
+
+    By default, certain mouse and touch events are delivered to other items in
+    preference to the Web content. For example, when a scrolling view is created
+    by placing a WebView in a Flickable, move events are delivered to the Flickable
+    so that the user can scroll the page. This prevents the user from accidentally
+    selecting text in a Web page instead of scrolling.
+
+    The pressGrabTime property defines the time the user must touch or press a
+    mouse button over the WebView before the Web content will receive the move
+    events it needs to select text and images.
+
+    When this item has keyboard focus, all keyboard input will be sent directly to
+    the Web page within.
+
+    When the navigates by clicking on links, the item records the pages visited
+    in its internal history
+
+    Because this item is designed to be used as a component in a browser, it
+    exposes \l{Action}{actions} for \l back, \l forward, \l reload and \l stop.
+    These can be triggered to change the current page displayed by the item.
+
+    \section1 Example Usage
+
+    \beginfloatright
+    \inlineimage webview.png
+    \endfloat
+
+    The following example displays a scaled down Web page at a fixed size.
+
+    \snippet doc/src/snippets/declarative/webview/webview.qml document
 
-    When this item has keyboard focus, all keyboard input will be sent directly to the
-    web page within.
+    \clearfloat
 
     \sa {declarative/modelviews/webview}{WebView example}, {demos/declarative/webbrowser}{Web Browser demo}
 */
@@ -555,11 +585,11 @@ bool QDeclarativeWebView::heuristicZoom(int clickX, int clickY, qreal maxZoom)
     \qmlproperty int WebView::pressGrabTime
 
     The number of milliseconds the user must press before the WebView
-    starts passing move events through to the web engine (rather than
+    starts passing move events through to the Web engine (rather than
     letting other QML elements such as a Flickable take them).
 
     Defaults to 400ms. Set to 0 to always grab and pass move events to
-    the web engine.
+    the Web engine.
 */
 int QDeclarativeWebView::pressGrabTime() const
 {
diff --git a/src/declarative/graphicsitems/qdeclarativeflickable.cpp b/src/declarative/graphicsitems/qdeclarativeflickable.cpp
index b302393..062bbfb 100644
--- a/src/declarative/graphicsitems/qdeclarativeflickable.cpp
+++ b/src/declarative/graphicsitems/qdeclarativeflickable.cpp
@@ -350,24 +350,34 @@ void QDeclarativeFlickablePrivate::updateBeginningEnd()
     \brief The Flickable item provides a surface that can be "flicked".
     \inherits Item
 
-    Flickable places its children on a surface that can be dragged and flicked.
+    The Flickable item places its children on a surface that can be dragged
+    and flicked, causing the view onto the child items to scroll. This
+    behavior forms the basis of Items that are designed to show large numbers
+    of child items, such as \l ListView and \l GridView.
 
-    \code
-    import Qt 4.7
+    In traditional user interfaces, views can be scrolled using standard
+    controls, such as scroll bars and arrow buttons. In some situations, it
+    is also possible to drag the view directly by pressing and holding a
+    mouse button while moving the cursor. In touch-based user interfaces,
+    this dragging action is often complemented with a flicking action, where
+    scrolling continues after the user has stopped touching the view.
 
-    Flickable {
-        width: 200; height: 200
-        contentWidth: image.width; contentHeight: image.height
+    Flickable does not automatically clip its contents. If it is not used as
+    a full-screen item, you should consider setting the \l{Item::}{clip} property
+    to true.
 
-        Image { id: image; source: "bigImage.png" }
-    }
-    \endcode
+    \section1 Example Usage
+
+    \beginfloatright
+    \inlineimage flickable.gif
+    \endfloat
 
-    \image flickable.gif
+    The following example shows a large 
 
-    Flickable does not automatically clip its contents. If
-    it is not full-screen it is likely that \l {Item::clip}{clip} should be set
-    to \c true.
+    \clearfloat
+    \snippet doc/src/snippets/declarative/flickable.qml document
+
+    \section1 Limitations
 
     \note Due to an implementation detail, items placed inside a Flickable cannot anchor to it by
     \c id. Use \c parent instead.
@@ -491,12 +501,15 @@ void QDeclarativeFlickable::setContentY(qreal pos)
 /*!
     \qmlproperty bool Flickable::interactive
 
-    This property holds whether the user can interact with the Flickable. A user
-    cannot drag or flick a Flickable that is not interactive.
+    This property describes whether the user can interact with the Flickable.
+    A user cannot drag or flick a Flickable that is not interactive.
+
+    By default, this property is true.
 
     This property is useful for temporarily disabling flicking. This allows
-    special interaction with Flickable's children: for example, you might want to
-    freeze a flickable map while scrolling through a pop-up dialog that is a child of the Flickable.
+    special interaction with Flickable's children; for example, you might want
+    to freeze a flickable map while scrolling through a pop-up dialog that
+    is a child of the Flickable.
 */
 bool QDeclarativeFlickable::isInteractive() const
 {
@@ -1333,8 +1346,8 @@ bool QDeclarativeFlickable::isFlicking() const
     \qmlproperty bool Flickable::flickingHorizontally
     \qmlproperty bool Flickable::flickingVertically
 
-    These properties hold whether the view is currently moving horizontally
-    or vertically due to the user flicking the view.
+    These properties describe whether the view is currently moving horizontally,
+    vertically or in either direction, due to the user flicking the view.
 */
 bool QDeclarativeFlickable::isFlickingHorizontally() const
 {
@@ -1386,8 +1399,9 @@ bool QDeclarativeFlickable::isMoving() const
     \qmlproperty bool Flickable::movingHorizontally
     \qmlproperty bool Flickable::movingVertically
 
-    These properties hold whether the view is currently moving horizontally
-    or vertically due to the user either dragging or flicking the view.
+    These properties describe whether the view is currently moving horizontally,
+    vertically or in either direction, due to the user either dragging or
+    flicking the view.
 */
 bool QDeclarativeFlickable::isMovingHorizontally() const
 {
diff --git a/src/declarative/graphicsitems/qdeclarativeimage.cpp b/src/declarative/graphicsitems/qdeclarativeimage.cpp
index 2fab373..9cd9ad6 100644
--- a/src/declarative/graphicsitems/qdeclarativeimage.cpp
+++ b/src/declarative/graphicsitems/qdeclarativeimage.cpp
@@ -73,7 +73,7 @@ QT_BEGIN_NAMESPACE
 
     The following example shows the simplest usage of the Image element.
 
-    \snippet doc/src/snippets/declarative/image.qml
+    \snippet doc/src/snippets/declarative/image.qml document
 
     \beginfloatleft
     \image declarative-qtlogo.png
diff --git a/src/declarative/qml/qdeclarativetypeloader.cpp b/src/declarative/qml/qdeclarativetypeloader.cpp
index ed41314..9b42065 100644
--- a/src/declarative/qml/qdeclarativetypeloader.cpp
+++ b/src/declarative/qml/qdeclarativetypeloader.cpp
@@ -224,7 +224,7 @@ void QDeclarativeDataBlob::setError(const QDeclarativeError &errors)
 }
 
 /*!
-\override
+\overload
 */
 void QDeclarativeDataBlob::setError(const QList<QDeclarativeError> &errors)
 {