Doc: Continued work on the QML documentation.

2 files changed, 56 insertions, 18 deletions

diff --git a/src/declarative/graphicsitems/qdeclarativerectangle.cpp b/src/declarative/graphicsitems/qdeclarativerectangle.cpp
index 9238004..e33969d 100644
--- a/src/declarative/graphicsitems/qdeclarativerectangle.cpp
+++ b/src/declarative/graphicsitems/qdeclarativerectangle.cpp
@@ -95,7 +95,12 @@ void QDeclarativePen::setWidth(int w)
     \qmlproperty real GradientStop::position
     \qmlproperty color GradientStop::color
 
-    Sets a \e color at a \e position in a gradient.
+    The position and color properties describe the color used at a given
+    position in a gradient, as represented by a gradient stop.
+
+    The default position is 0.0; the default color is black.
+
+    \sa Gradient
 */
 
 void QDeclarativeGradientStop::updateGradient()
@@ -107,20 +112,50 @@ void QDeclarativeGradientStop::updateGradient()
 /*!
     \qmlclass Gradient QDeclarativeGradient
     \ingroup qml-basic-visual-elements
-  \since 4.7
+    \since 4.7
     \brief The Gradient item defines a gradient fill.
 
-    A gradient is defined by two or more colors, which will be blended seemlessly.  The
-    colors are specified at their position in the range 0.0 - 1.0 via
-    the GradientStop item.  For example, the following code paints a
-    rectangle with a gradient starting with red, blending to yellow at 1/3 of the
-    size of the rectangle, and ending with Green:
+    A gradient is defined by two or more colors, which will be blended seamlessly.
 
-    \snippet doc/src/snippets/declarative/gradient.qml code
+    The colors are specified as a set of GradientStop child items, each of
+    which defines a position on the gradient from 0.0 to 1.0 and a color.
+    The position of each GradientStop is defined by setting its
+    \l{GradientStop::}{position} property; its color is defined using its
+    \l{GradientStop::}{color} property.
+
+    A gradient without any gradient stops is rendered as a solid white fill.
 
     Note that this item is not a visual representation of a gradient. To display a
-    gradient use a visual item (like rectangle) which supports having a gradient set
-    on it for display.
+    gradient, use a visual element (like \l Rectangle) which supports the use
+    of gradients.
+
+    \section1 Example Usage
+
+    \beginfloatright
+    \inlineimage qml-gradient.png
+    \endfloat
+
+    The following example declares a \l Rectangle item with a gradient starting
+    with red, blending to yellow at one third of the height of the rectangle,
+    and ending with green:
+
+    \snippet doc/src/snippets/declarative/gradient.qml code
+
+    \clearfloat
+    \section1 Performance and Limitations
+
+    Calculating gradients can be computationally expensive compared to the use
+    of solid color fills or images. Consider using gradients for static items
+    in a user interface.
+
+    In Qt 4.7, only vertical, linear gradients can be applied to items. If you
+    need to apply different orientations of gradients, a combination of rotation
+    and clipping will need to be applied to the relevant items. This can
+    introduce additional performance requirements for your application.
+
+    The use of animations involving gradient stops may not give the desired
+    result. An alternative way to animate gradients is to use pre-generated
+    images or SVG drawings containing gradients.
 
     \sa GradientStop
 */
@@ -128,6 +163,10 @@ void QDeclarativeGradientStop::updateGradient()
 /*!
     \qmlproperty list<GradientStop> Gradient::stops
     This property holds the gradient stops describing the gradient.
+
+    By default, this property contains an empty list.
+
+    To set the gradient stops, define them as children of the Gradient element.
 */
 
 const QGradient *QDeclarativeGradient::gradient() const
diff --git a/src/gui/painting/qbrush.cpp b/src/gui/painting/qbrush.cpp
index d3061d8..d0788c7 100644
--- a/src/gui/painting/qbrush.cpp
+++ b/src/gui/painting/qbrush.cpp
@@ -1218,17 +1218,16 @@ QDataStream &operator>>(QDataStream &s, QBrush &b)
     \o QConicalGradient
     \endtable
 
-    The colors in a gradient is defined using stop points of the
-    QGradientStop type, i.e. a position and a color.  Use the
-    setColorAt() function to define a single stop
-    point. Alternatively, use the setStops() function to define
-    several stop points in one go. Note that the latter function \e
-    replaces the current set of stop points.
+    The colors in a gradient are defined using stop points of the
+    QGradientStop type; i.e., a position and a color. Use the setColorAt()
+    function to define a single stop point. Alternatively, use the
+    setStops() function to define several stop points in one go. Note that
+    the latter function \e replaces the current set of stop points.
 
     It is the gradient's complete set of stop points (accessible
     through the stops() function) that describes how the gradient area
-    should be filled. If no stop points have been specified, a
-    gradient of black at 0 to white at 1 is used.
+    should be filled. If no stop points have been specified, a gradient
+    of black at 0 to white at 1 is used.
 
     A diagonal linear gradient from black at (100, 100) to white at
     (200, 200) could be specified like this: