doc improvements

2 files changed, 27 insertions, 5 deletions

diff --git a/src/declarative/qml/qdeclarativecomponent.cpp b/src/declarative/qml/qdeclarativecomponent.cpp
index 04ec382..36c4b49 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()}.
 */
 
 /*!
diff --git a/src/declarative/qml/qdeclarativeengine.cpp b/src/declarative/qml/qdeclarativeengine.cpp
index 2e37af7..00bc1b7 100644
--- a/src/declarative/qml/qdeclarativeengine.cpp
+++ b/src/declarative/qml/qdeclarativeengine.cpp
@@ -1090,6 +1090,8 @@ If you are certain the files will be local, you could simplify to:
 
 To create a QML object from an arbitrary string of QML (instead of a file),
 use \l{QML:Qt::createQmlObject()}{Qt.createQmlObject()}.
+
+\sa {Dynamic Object Management}
 */
 
 QScriptValue QDeclarativeEnginePrivate::createComponent(QScriptContext *ctxt, QScriptEngine *engine)
@@ -1137,6 +1139,8 @@ Each object in this array has the members \c lineNumber, \c columnNumber, \c fil
 Note that this function returns immediately, and therefore may not work if
 the \a qml string loads new components (that is, external QML files that have not yet been loaded).
 If this is the case, consider using \l{QML:Qt::createComponent()}{Qt.createComponent()} instead.
+
+\sa {Dynamic Object Management}
 */
 
 QScriptValue QDeclarativeEnginePrivate::createQmlObject(QScriptContext *ctxt, QScriptEngine *engine)