1 files changed, 29 insertions, 17 deletions
diff --git a/src/declarative/graphicsitems/qdeclarativeimage.cpp b/src/declarative/graphicsitems/qdeclarativeimage.cpp
index 7a88e78..9cd9ad6 100644
--- a/src/declarative/graphicsitems/qdeclarativeimage.cpp
+++ b/src/declarative/graphicsitems/qdeclarativeimage.cpp
@@ -51,34 +51,46 @@ QT_BEGIN_NAMESPACE
 /*!
     \qmlclass Image QDeclarativeImage
     \since 4.7
-    \ingroup qml-vasic-visual-elements
-
-    \brief The Image element allows you to add bitmaps to a scene.
+    \ingroup qml-basic-visual-elements
+    \brief The Image element displays an image in a declarative user interface
     \inherits Item
 
-    An Image element displays a specified \l source image:
+    The Image element is used to display images in a declarative user interface.
 
-    \table
-    \row
-    \o \image declarative-qtlogo.png
-    \o \qml
-        import Qt 4.7
+    The source of the image is specified as a URL using the \l source property.
+    Images can be supplied in any of the standard image formats supported by Qt,
+    including bitmap formats such as PNG and JPEG, and vector graphics formats
+    such as SVG. If you need to display animated images, use the \l AnimatedImage
+    element.
 
-        Image { source: "qtlogo.png" }
-    \endqml
-    \endtable
+    If the \l{Item::width}{width} and \l{Item::height}{height} properties are not
+    specified, the Image element automatically uses the size of the loaded image.
+    By default, specifying the width and height of the element causes the image
+    to be scaled to that size. This behavior can be changed by setting the
+    \l fillMode property, allowing the image to be stretched and tiled instead.
+
+    \section1 Example Usage
+
+    The following example shows the simplest usage of the Image element.
+
+    \snippet doc/src/snippets/declarative/image.qml document
+
+    \beginfloatleft
+    \image declarative-qtlogo.png
+    \endfloat
+
+    \clearfloat
 
-    If the \l {Item::width}{width} and \l{Item::height}{height} properties are not specified,
-    the Image element is automatically sized to the loaded image. Image elements can be 
-    stretched and tiled using the \l fillMode property.
+    \section1 Performance
 
     By default, locally available images are loaded immediately, and the user interface
     is blocked until loading is complete. If a large image is to be loaded, it may be
     preferable to load the image in a low priority thread, by enabling the \l asynchronous
     property.
 
-    If the image is from a network rather than a local resource, it is automatically loaded
-    asynchronously, and the \l progress and \l status properties are updated as appropriate.  
+    If the image is obtained from a network rather than a local resource, it is
+    automatically loaded asynchronously, and the \l progress and \l status properties
+    are updated as appropriate.
 
     Images are cached and shared internally, so if several Image elements have the same \l source,
     only one copy of the image will be loaded.