Augment docs for JS dynamic creation functions

Note that I'm still not entirely certain the docs are in the right place
for people to find them - but if they do they should now have a better
understanding of which function to use.

1 files changed, 11 insertions, 1 deletions

diff --git a/src/declarative/qml/qmlengine.cpp b/src/declarative/qml/qmlengine.cpp
index 294e333..fc2c7e3 100644
--- a/src/declarative/qml/qmlengine.cpp
+++ b/src/declarative/qml/qmlengine.cpp
@@ -866,7 +866,9 @@ QScriptValue QmlEngine::qmlScriptObject(QObject* object, QmlEngine* engine)
         }
     \endcode
 
-    \sa QmlComponent::createObject()
+    If you want to just create an arbitrary string of QML, instead of an
+    existing qml component or qml file, consider the evalQML() function.
+    \sa QmlComponent::createObject(), QmlEngine::createQMLObject()
 */
 QScriptValue QmlEngine::createComponent(QScriptContext *ctxt, QScriptEngine *engine)
 {
@@ -892,6 +894,14 @@ QScriptValue QmlEngine::createComponent(QScriptContext *ctxt, QScriptEngine *eng
 
     Returns the created object, or null if there is an error. In the case of an
     error, details of the error are output using qWarning().
+
+    Note that this function returns immediately, and therefore may not work if
+    the QML loads new components. If you are trying to load a new component,
+    for example from a QML file, consider the createComponent() function
+    instead. 'New components' refers to external QML files that have not yet
+    been loaded, and so it is safe to use evalQml to load built-in components.
+
+    \sa QmlEngine::createComponent()
 */
 QScriptValue QmlEngine::createQMLObject(QScriptContext *ctxt, QScriptEngine *engine)
 {