Doc: More work on the QML documentation.

1 files changed, 59 insertions, 57 deletions

diff --git a/src/declarative/graphicsitems/qdeclarativerectangle.cpp b/src/declarative/graphicsitems/qdeclarativerectangle.cpp
index d027924..9238004 100644
--- a/src/declarative/graphicsitems/qdeclarativerectangle.cpp
+++ b/src/declarative/graphicsitems/qdeclarativerectangle.cpp
@@ -155,27 +155,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.
+
+    \section1 Example Usage
 
-    \image declarative-rect.png
+    \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 +226,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 +251,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"
-    }
+    \beginfloatleft
+    \inlineimage declarative-rect_gradient.png
+    \endfloat
 
-    Rectangle {
-        y: 100; width: 80; height: 80
-        gradient: Gradient {
-            GradientStop { position: 0.0; color: "lightsteelblue" }
-            GradientStop { position: 1.0; color: "blue" }
-        }
-    }
-
-    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 +317,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
 {