diff -r 5dc02b23752f -r 3e2da88830cd src/declarative/graphicsitems/qdeclarativerectangle.cpp
--- a/src/declarative/graphicsitems/qdeclarativerectangle.cpp	Tue Jul 06 15:10:48 2010 +0300
+++ b/src/declarative/graphicsitems/qdeclarativerectangle.cpp	Wed Aug 18 10:37:55 2010 +0300
@@ -114,11 +114,11 @@
     rectangle with a gradient starting with red, blending to yellow at 1/3 of the
     size of the rectangle, and ending with Green:
 
-    \table
-    \row
-    \o \image gradient.png
-    \o \quotefile doc/src/snippets/declarative/gradient.qml
-    \endtable
+    \snippet doc/src/snippets/declarative/gradient.qml code
+
+    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.
 
     \sa GradientStop
 */
@@ -160,6 +160,8 @@
     You can also create rounded rectangles using the \l radius property.
 
     \qml
+    import Qt 4.7
+
     Rectangle {
         width: 100
         height: 100
@@ -202,8 +204,20 @@
 
     A width of 1 creates a thin line. For no line, use a width of 0 or a transparent color.
 
-    To keep the border smooth (rather than blurry), odd widths cause the rectangle to be painted at
-    a half-pixel offset;
+    If \c border.width is an odd number, the rectangle is painted at a half-pixel offset to retain
+    border smoothness. Also, the border is rendered evenly on either side of the 
+    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
+
+    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.
 */
 QDeclarativePen *QDeclarativeRectangle::border()
 {
@@ -432,6 +446,7 @@
             p.setRenderHint(QPainter::Antialiasing);
         if (d->pen && d->pen->isValid()) {
             QPen pn(QColor(d->pen->color()), d->pen->width());
+            pn.setJoinStyle(Qt::MiterJoin);
             p.setPen(pn);
         } else {
             p.setPen(Qt::NoPen);