doc improvements

1 files changed, 23 insertions, 5 deletions

diff --git a/src/declarative/qml/qdeclarativecomponent.cpp b/src/declarative/qml/qdeclarativecomponent.cpp
index 04ec382757..36c4b49157 100644
--- a/src/declarative/qml/qdeclarativecomponent.cpp
+++ b/src/declarative/qml/qdeclarativecomponent.cpp
@@ -108,27 +108,45 @@ class QByteArray;
     \brief The Component element encapsulates a QML component definition.
 
     Components are reusable, encapsulated QML elements with well-defined interfaces.
-    They are often defined in \l {qdeclarativedocuments.html}{Component Files}.
 
-    The \e Component element allows defining components within a QML file.
-    This can be useful for reusing a small component within a single QML
-    file, or for defining a component that logically belongs with the
-    file containing it.
+    Components are often defined by \l {qdeclarativedocuments.html}{component files} -
+    that is, \c .qml files. The \e Component element allows components to be defined
+    within QML items rather than in a separate file. This may be useful for reusing 
+    a small component within a QML file, or for defining a component that logically 
+    belongs with other QML components within a file.
+
+    For example, here is a component that is used by multiple \l Loader objects:
 
     \qml
     Item {
         Component {
             id: redSquare
+
             Rectangle {
                 color: "red"
                 width: 10
                 height: 10
             }
         }
+
         Loader { sourceComponent: redSquare }
         Loader { sourceComponent: redSquare; x: 20 }
     }
     \endqml
+
+    Notice that while a \l Rectangle by itself would be automatically 
+    rendered and displayed, this is not the case for the above rectangle
+    because it is defined inside a \c Component. The component encapsulates the
+    QML elements within, as if they were defined in a separate \c .qml
+    file, and is not loaded until requested (in this case, by the
+    two \l Loader objects).
+
+    The Component element is commonly used to provide graphical components
+    for views. For example, the ListView::delegate property requires a Component
+    to specify how each list item is to be displayed.
+
+    Component objects can also be dynamically generated using
+    \l{Qt::createComponent}{Qt.createComponent()}.
 */
 
 /*!