Doc fixes

4 files changed, 101 insertions, 94 deletions

diff --git a/doc/src/declarative/codingconventions.qdoc b/doc/src/declarative/codingconventions.qdoc
index 7ca206b..d0f873d 100644
--- a/doc/src/declarative/codingconventions.qdoc
+++ b/doc/src/declarative/codingconventions.qdoc
@@ -57,7 +57,7 @@ Through our documentation and examples, QML objects are always structured in the
 \o id
 \o property declarations
 \o signal declarations
-\o javascript functions
+\o JavaScript functions
 \o object properties
 \o child objects
 \o states
@@ -102,7 +102,7 @@ we will write this:
 \snippet doc/src/snippets/declarative/codingconventions/lists.qml 1
 
 
-\section1 Javascript code
+\section1 JavaScript code
 
 If the script is a single expression, we recommend writing it inline:
 
@@ -116,7 +116,7 @@ If the script is more than a couple of lines long or can be used by different ob
 
 \snippet doc/src/snippets/declarative/codingconventions/javascript.qml 2
 
-For long scripts, we will put the functions in their own javascript file and import it like this:
+For long scripts, we will put the functions in their own JavaScript file and import it like this:
 
 \snippet doc/src/snippets/declarative/codingconventions/javascript-imports.qml 0
 
diff --git a/doc/src/declarative/dynamicobjects.qdoc b/doc/src/declarative/dynamicobjects.qdoc
index a2b65a8..c376266 100644
--- a/doc/src/declarative/dynamicobjects.qdoc
+++ b/doc/src/declarative/dynamicobjects.qdoc
@@ -43,23 +43,25 @@
 \page qdeclarativedynamicobjects.html
 \title Dynamic Object Management
 
-QML has some support for dynamically loading and managing QML objects from
-within Javascript blocks. It is preferable to use the existing QML elements for
-dynamic object management wherever possible; these are \l{Loader}, 
-\l{Repeater}, \l{ListView}, \l{GridView} and \l{PathView}. It is also possible 
-to dynamically create and manage objects from C++, and this is preferable for 
-hybrid QML/C++ applications - see \l{Using QML in C++ Applications}.
-Dynamically creating and managing objects from 
-within Javascript blocks is intended for when none of the existing QML elements 
-fit the needs of your application, and you do not desire for your application 
-to involve C++ code.
+QML provides a number of ways to dynamically create and manage QML objects. 
+The \l{Loader}, \l{Repeater}, \l{ListView}, \l{GridView} and \l{PathView} elements
+all support dynamic object management.  Objects can also be created and managed 
+from C++, and this is the preferred method for hybrid QML/C++ applications
+(see \l{Using QML in C++ Applications}).
+
+QML also supports the dynamic creation of objects from within JavaScript
+code. This is useful if the existing QML elements do not fit the needs of your
+application, and there are no C++ components involved.
+
 
 \section1 Creating Objects Dynamically
-There are two ways of creating objects dynamically. You can either create
-a component which instantiates items, or create an item from a string of QML.
-Creating a component is better for the situation where you have a predefined
-item which you want to manage dynamic instances of, and creating an item from
-a string of QML is intended for when the QML itself is generated at runtime.
+There are two ways to create objects dynamically from JavaScript. You can either call 
+\l {Qt.createComponent(url file)}{Qt.createComponent()} to create
+a component which instantiates items, or use \l{Qt.createQmlObject(string qml, object parent, string filepath)}{Qt.createQmlObject()}
+to create an item from a string of QML.
+Creating a component is better if you have a predefined
+item, and you want to create dynamic instances of that item; creating an item from
+a string of QML is useful when the item QML itself is generated at runtime.
 
 If you have a component specified in a QML file, you can dynamically load it with
 the \l {Qt.createComponent(url file)}{Qt.createComponent()} function on the \l{QML Global Object}. 
@@ -69,7 +71,7 @@ a component object which can be used to create and load that QML file.
 Once you have a component you can use its \c createObject() method to create an instance of
 the component. 
 
-Here is an example. Here is a simple QML component defined in \c Sprite.qml:
+Here is an example. Here is a \c Sprite.qml, which defines a simple QML component:
 
 \quotefile doc/src/snippets/declarative/Sprite.qml
 
@@ -84,14 +86,10 @@ over the network cannot be expected to be ready immediately:
 \snippet doc/src/snippets/declarative/componentCreation.js 0
 \codeline
 \snippet doc/src/snippets/declarative/componentCreation.js 1
-\snippet doc/src/snippets/declarative/componentCreation.js 2
-\snippet doc/src/snippets/declarative/componentCreation.js 4
-\codeline
-\snippet doc/src/snippets/declarative/componentCreation.js 5
 
 If you are certain the files will be local, you could simplify to:
 
-\snippet doc/src/snippets/declarative/componentCreation.js 3
+\snippet doc/src/snippets/declarative/componentCreation.js 2
 
 Notice that once a \c Sprite object is created, its parent is set to \c appWindow (defined
 in \c main.qml). After creating an item, you must set its parent to an item within the scene.
@@ -114,8 +112,22 @@ item, which is used for error reporting.
 
 \section1 Maintaining Dynamically Created Objects
 
-Dynamically created objects may be used the same as other objects, however they
-will not have an id in QML.
+When managing dynamically created items, you must ensure the creation context
+outlives the created item. Otherwise, if the creation context is destroyed first,
+the bindings in the dynamic item will no longer work.
+
+The actual creation context depends on how an item is created:
+
+\list
+\o If \l {Qt.createComponent(url file)}{Qt.createComponent()} is used, the creation context
+   is the QDeclarativeContext in which this method is called
+\o If \l{Qt.createQmlObject(string qml, object parent, string filepath)}{Qt.createQmlObject()}
+   if called, it is the context of the item used as the second argument to this method
+\o If a \c {Component \{\}} item is defined and \c {Component::}{createObject()} is called,
+   it is the context in which the \c Component item is defined
+
+Also, note that while dynamically created objects may be used the same as other objects, they
+do not have an id in QML.
 
 A restriction which you need to manage with dynamically created items,
 is that the creation context must outlive the
@@ -134,7 +146,7 @@ a worthwhile performance benefit. Note that you should never manually delete
 items which were dynamically created by QML Elements such as \l{Loader}.
 
 To manually delete a QML item, call its destroy method. This method has one
-argument, which is an approximate delay in ms and which defaults to zero. This
+argument, which is an approximate delay in milliseconds and which defaults to zero. This
 allows you to wait until the completion of an animation or transition. An example:
 
 \code
@@ -153,8 +165,9 @@ allows you to wait until the completion of an animation or transition. An exampl
         object.parent = parentItem;
     }
 \endcode
-In the above example, the dynamically created rectangle calls destroy as soon as it's created,
- but delays long enough for its fade out animation to play.
+
+In the above example, the dynamically created rectangle calls destroy as soon as it is created,
+ but delays long enough for its fade out animation to be played.
 
 */
 
diff --git a/doc/src/declarative/globalobject.qdoc b/doc/src/declarative/globalobject.qdoc
index 85cbde2..47460cf 100644
--- a/doc/src/declarative/globalobject.qdoc
+++ b/doc/src/declarative/globalobject.qdoc
@@ -234,58 +234,58 @@ The following functions on the global object allow you to dynamically create QML
 items from files or strings. See \l{Dynamic Object Management} for an overview
 of their use.
 
+
 \section2 Qt.createComponent(url file)
-    This function takes the URL of a QML file as its only argument. It returns
-    a component object which can be used to create and load that QML file.
 
-    Here is an example. Remember that QML files that might be loaded
-    over the network cannot be expected to be ready immediately.
+This function takes the URL of a QML file as its only argument. It returns
+a component object which can be used to create and load that QML file.
+
+Here is an example. Remember that QML files that might be loaded
+over the network cannot be expected to be ready immediately.
 
-    \snippet doc/src/snippets/declarative/componentCreation.js 0
-    \codeline
-    \snippet doc/src/snippets/declarative/componentCreation.js 1
-    \snippet doc/src/snippets/declarative/componentCreation.js 2
-    \snippet doc/src/snippets/declarative/componentCreation.js 4
-    \codeline
-    \snippet doc/src/snippets/declarative/componentCreation.js 5
+\snippet doc/src/snippets/declarative/componentCreation.js 0
+\codeline
+\snippet doc/src/snippets/declarative/componentCreation.js 1
 
-    If you are certain the files will be local, you could simplify to:
+If you are certain the files will be local, you could simplify to:
 
-    \snippet doc/src/snippets/declarative/componentCreation.js 3
+\snippet doc/src/snippets/declarative/componentCreation.js 2
 
-    The methods and properties of the Component element are defined in its own
-    page, but when using it dynamically only two methods are usually used.
-    \c Component.createObject() returns the created object or \c null if there is an error.
-    If there is an error, \l {Component::errorsString()}{Component.errorsString()} describes
-    the error that occurred.
+The methods and properties of the Component element are defined in its own
+page, but when using it dynamically only two methods are usually used.
+\c Component.createObject() returns the created object or \c null if there is an error.
+If there is an error, \l {Component::errorsString()}{Component.errorsString()} describes
+the error that occurred.
+
+If you want to just create an arbitrary string of QML, instead of
+loading a QML file, consider the \l{Qt.createQmlObject(string qml, object parent, string filepath)}{Qt.createQmlObject()} function.
 
-    If you want to just create an arbitrary string of QML, instead of
-    loading a QML file, consider the \l{Qt.createQmlObject(string qml, object parent, string filepath)}{Qt.createQmlObject()} function.
 
 \section2 Qt.createQmlObject(string qml, object parent, string filepath)
-    Creates a new object from the specified string of QML. It requires a
-    second argument, which is the id of an existing QML object to use as
-    the new object's parent. If a third argument is provided, this is used
-    for error reporting as the filepath that the QML came from.
 
-    Example (where \c targetItem is the id of an existing QML item):
+Creates a new object from the specified string of QML. It requires a
+second argument, which is the id of an existing QML object to use as
+the new object's parent. If a third argument is provided, this is used
+for error reporting as the filepath that the QML came from.
+
+Example (where \c targetItem is the id of an existing QML item):
 
-    \snippet doc/src/snippets/declarative/createQmlObject.qml 0
+\snippet doc/src/snippets/declarative/createQmlObject.qml 0
 
-    This function is intended for use inside QML only. It is intended to behave
-    similarly to eval, but for creating QML elements.
+This function is intended for use inside QML only. It is intended to behave
+similarly to eval, but for creating QML elements.
 
-    Returns the created object, \c or null if there is an error. In the case of an
-    error, a QtScript Error object is thrown. This object has the additional property,
-    qmlErrors, which is an array of all the errors encountered when trying to execute the
-    QML. Each object in the array has the members \c lineNumber, \c columnNumber, \c fileName and \c message.
+Returns the created object, \c or null if there is an error. In the case of an
+error, a QtScript Error object is thrown. This object has the additional property,
+qmlErrors, which is an array of all the errors encountered when trying to execute the
+QML. Each object in the array has the members \c lineNumber, \c columnNumber, \c fileName and \c message.
 
-    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 \l{Qt.createComponent(url file)}{Qt.createComponent()} function
-    instead. 'New components' refers to external QML files that have not yet
-    been loaded, and so it is safe to use \c Qt.createQmlObject() to load built-in
-    components.
+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 \l{Qt.createComponent(url file)}{Qt.createComponent()} function
+instead. 'New components' refers to external QML files that have not yet
+been loaded, and so it is safe to use \c Qt.createQmlObject() to load built-in
+components.
 
 \section1 XMLHttpRequest
 
diff --git a/doc/src/snippets/declarative/componentCreation.js b/doc/src/snippets/declarative/componentCreation.js
index 814545e..be928f0 100644
--- a/doc/src/snippets/declarative/componentCreation.js
+++ b/doc/src/snippets/declarative/componentCreation.js
@@ -20,38 +20,32 @@ function finishCreation() {
 }
 //![0]
 
-//![1]
 function createSpriteObjects() {
-//![1]
-
-    //![2]
-    component = Qt.createComponent("Sprite.qml");
-    if (component.status == Component.Ready)
-        finishCreation();
-    else
-        component.statusChanged.connect(finishCreation);
-    //![2]
 
-    //![3]
-    component = Qt.createComponent("Sprite.qml");
-    sprite = component.createObject();
+//![1]
+component = Qt.createComponent("Sprite.qml");
+if (component.status == Component.Ready)
+    finishCreation();
+else
+    component.statusChanged.connect(finishCreation);
+//![1]
 
-    if (sprite == null) {
-        // Error Handling
-        console.log("Error loading component:", component.errorsString());
-    } else {
-        sprite.parent = appWindow;
-        sprite.x = 100;
-        sprite.y = 100;
-        // ...
-    }
-    //![3]
+//![2]
+component = Qt.createComponent("Sprite.qml");
+sprite = component.createObject();
+
+if (sprite == null) {
+    // Error Handling
+    console.log("Error loading component:", component.errorsString());
+} else {
+    sprite.parent = appWindow;
+    sprite.x = 100;
+    sprite.y = 100;
+    // ...
+}
+//![2]
 
-//![4]
 }
-//![4]
 
-//![5]
 createSpriteObjects();
-//![5]