Document issues with rectangle border width of 1 where clipping is used

1 files changed, 14 insertions, 2 deletions

diff --git a/src/declarative/graphicsitems/qdeclarativerectangle.cpp b/src/declarative/graphicsitems/qdeclarativerectangle.cpp
index 301ca00..de3dbcd 100644
--- a/src/declarative/graphicsitems/qdeclarativerectangle.cpp
+++ b/src/declarative/graphicsitems/qdeclarativerectangle.cpp
@@ -202,8 +202,20 @@ void QDeclarativeRectangle::doUpdate()
 
     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{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()
 {