1 files changed, 26 insertions, 33 deletions
diff --git a/src/declarative/graphicsitems/qdeclarativeimage.cpp b/src/declarative/graphicsitems/qdeclarativeimage.cpp
index 34d33f5..90738c8 100644
--- a/src/declarative/graphicsitems/qdeclarativeimage.cpp
+++ b/src/declarative/graphicsitems/qdeclarativeimage.cpp
@@ -324,17 +324,34 @@ qreal QDeclarativeImage::paintedHeight() const
 /*!
     \qmlproperty QSize Image::sourceSize
 
-    This property holds the size of the loaded image, in pixels.
+    This property holds the actual width and height of the loaded image.
 
-    This is used to control the storage used by a loaded image. Unlike
-    the width and height properties, which scale the painting of the image, this property
-    affects the number of pixels stored.
+    Unlike the \l {Item::}{width} and \l {Item::}{height} properties, which scale
+    the painting of the image, this property sets the actual number of pixels
+    stored for the loaded image so that large images do not use more
+    memory than necessary. For example, this ensures the image is memory is no
+    larger than 1024x1024 pixels, regardless of the Image's \l {Item::}{width} and 
+    \l {Item::}{height} values:
+
+    \code
+    Rectangle {
+        width: ...
+        height: ...
+
+        Image {
+           anchors.fill: parent
+           source: "reallyBigImage.jpg"
+           sourceSize.width: 1024
+           sourceSize.height: 1024
+        }
+    }
+    \endcode
 
     If the image's actual size is larger than the sourceSize, the image is scaled down.
     If only one dimension of the size is set to greater than 0, the
     other dimension is set in proportion to preserve the source image's aspect ratio.
     (The \l fillMode is independent of this.)
-   
+
     If the source is an instrinsically scalable image (eg. SVG), this property
     determines the size of the loaded image regardless of intrinsic size.
     Avoid changing this property dynamically; rendering an SVG is \e slow compared
@@ -344,34 +361,8 @@ qreal QDeclarativeImage::paintedHeight() const
     be no greater than this property specifies. For some formats (currently only JPEG),
     the whole image will never actually be loaded into memory.
  
-    \note \e{Changing this property dynamically will lead to the image source being reloaded,
-    potentially even from the network if it is not in the disk cache.}
-
-    Here is an example that ensures the size of the image in memory is
-    no larger than 1024x1024 pixels, regardless of the size of the Image element.
-
-    \code
-    Image {
-       anchors.fill: parent
-       source: "images/reallyBigImage.jpg"
-       sourceSize.width: 1024
-       sourceSize.height: 1024
-    }
-    \endcode
-
-    The example below ensures the memory used by the image is no more than necessary 
-    to display the image at the size of the Image element.
-    Of course if the Image element is resized a costly reload will be required, so
-    use this technique \e only when the Image size is fixed.
-
-    \code
-    Image {
-       anchors.fill: parent
-       source: "images/reallyBigImage.jpg"
-       sourceSize.width: width
-       sourceSize.height: height
-    }
-    \endcode
+    \note \e {Changing this property dynamically causes the image source to be reloaded,
+    potentially even from the network, if it is not in the disk cache.}
 */
 
 void QDeclarativeImage::updatePaintedGeometry()
@@ -415,6 +406,8 @@ void QDeclarativeImage::geometryChanged(const QRectF &newGeometry, const QRectF
     Image can handle any image format supported by Qt, loaded from any URL scheme supported by Qt.
 
     The URL may be absolute, or relative to the URL of the component.
+
+    \sa QDeclarativeImageProvider
 */
 
 /*!