2 files changed, 48 insertions, 38 deletions

diff --git a/src/declarative/qml/qmlscript.cpp b/src/declarative/qml/qmlscript.cpp
index 7242498..eb0b858 100644
--- a/src/declarative/qml/qmlscript.cpp
+++ b/src/declarative/qml/qmlscript.cpp
@@ -43,12 +43,13 @@
 
 /*!
     \qmlclass Script QmlScript
-    \brief The Script element adds JavaScript snippets.
+    \brief The Script element provides a way to add JavaScript code snippets in QML.
     \ingroup group_utility
 
-    QmlScript is used to add convenient JavaScript "glue" methods to
-    your Qt Declarative application or component. While you can have any JavaScript code
-    within a QmlScript, it is best to limit yourself to defining functions.
+    The Script element is used to add convenient JavaScript "glue" methods to
+    your Qt Declarative application or component. 
+
+    An example: 
 
     \qml
     Script {
@@ -60,23 +61,27 @@
     MouseRegion { onClicked: debugMyComponent() }
     \endqml
 
-    \note QmlScript executes JavaScript as soon as it is specified.
-    When defining a component, this may be before the execution context is
-    fully specified.  As a result some properties or items may not be
-    accessible. By limiting your JavaScript to defining functions that are
-    only executed later once the context is fully defined, this problem is
-    avoided.
+    \note While it is possible to use any JavaScript code within a Script element,
+    it is recommended that the code be limited to defining functions. The Script
+    element executes JavaScript as soon as it is specified, so
+    when defining a component, this may be done before the execution context is
+    fully specified.  As a result, some properties or items may not be
+    accessible. You can avoid this problem by limiting your JavaScript to
+    defining functions that are only executed later once the context is fully
+    defined.
+
+    \sa {ECMAScript Blocks}
 */
 
 /*!
     \qmlproperty string Script::script
     \default
-    JavaScript code to execute.
+    The JavaScript code to be executed.
 */
 
 /*!
     \qmlproperty url Script::source
 
-    Setting this property causes the Script element to read JavaScript code from
-    the file specified.
+    Specifies a source file containing JavaScript code. This can be used instead
+    of providing inline JavaScript code in the Script element.
 */
diff --git a/src/declarative/util/qmlconnection.cpp b/src/declarative/util/qmlconnection.cpp
index b1771d4..3e72ab8 100644
--- a/src/declarative/util/qmlconnection.cpp
+++ b/src/declarative/util/qmlconnection.cpp
@@ -65,7 +65,18 @@ public:
     \qmlclass Connection QmlConnection
     \brief A Connection object describes generalized connections to signals.
 
-    JavaScript-in-HTML style signal properties do not allow:
+    When connecting to signals in QML, the usual way is to create an
+    "on<Signal>" handler that reacts when a signal is received, like this:
+
+    \qml
+    MouseRegion {
+        onClicked: { foo(x+123,y+456) }
+    }
+    \endqml
+
+    However, in some cases, it is not possible to connect to a signal in this
+    way. For example, JavaScript-in-HTML style signal properties do not allow:
+
     \list
         \i connecting to signals with the same name but different parameters
         \i conformance checking that parameters are correctly named
@@ -74,39 +85,33 @@ public:
         \i signals in classes with coincidentally-named on<Signal> properties
     \endlist
 
-    When any of these is needed, the Connection object can be used instead.
-    Where a signal could be connected like this:
+    When any of these are needed, the Connection object can be used instead.
 
-    \qml
-MouseRegion {
-    onClicked: { foo(x+123,y+456) }
-}
-    \endqml
-
-    An equivalent binding can be made with a Connection object:
+    For example, the above code can be changed to use a Connection object,
+    like this:
 
     \qml
-MouseRegion {
-    Connection {
-        signal: "clicked(x,y)"
-        script: { foo(x+123,y+456) }
+    MouseRegion {
+        Connection {
+            signal: "clicked(x,y)"
+            script: { foo(x+123,y+456) }
+        }
     }
-}
     \endqml
 
     More generally, the Connection object can be a child of some other object than
     the sender of the signal, and the script is the default attribute:
 
     \qml
-MouseRegion {
-    id: mr
-}
-...
-Connection {
-    sender: mr
-    signal: "clicked(x,y)"
-    script: { foo(x+123,y+456) }
-}
+    MouseRegion {
+        id: mr
+    }
+    ...
+    Connection {
+        sender: mr
+        signal: "clicked(x,y)"
+        script: { foo(x+123,y+456) }
+    }
     \endqml
 */
 
@@ -249,7 +254,7 @@ void QmlConnection::setScript(const QmlScriptString& script)
     \qmlproperty string Connection::signal
     This property holds the signal from the sender to which the script is attached.
 
-    The signal must have its formal parameter names given in parentheses:
+    The signal's formal parameter names must be given in parentheses:
 
     \qml
 Connection {