11 files changed, 63 insertions, 41 deletions
diff --git a/doc/src/declarative/advtutorial1.qdoc b/doc/src/declarative/advtutorial1.qdoc
index a96485c..86d14ad 100644
--- a/doc/src/declarative/advtutorial1.qdoc
+++ b/doc/src/declarative/advtutorial1.qdoc
@@ -41,7 +41,6 @@
 
 /*!
 \page advtutorial1.html
-\example declarative/tutorials/samegame/samegame1
 \title Advanced Tutorial 1 - Creating the Game Canvas and Blocks
 
 The first step is to create the items in your application. In Same Game we have a main game screen and the blocks that populate it.
diff --git a/doc/src/declarative/advtutorial2.qdoc b/doc/src/declarative/advtutorial2.qdoc
index 9fab289..40a760d 100644
--- a/doc/src/declarative/advtutorial2.qdoc
+++ b/doc/src/declarative/advtutorial2.qdoc
@@ -41,7 +41,6 @@
 
 /*!
 \page advtutorial2.html
-\example declarative/tutorials/samegame/samegame2
 \title Advanced Tutorial 2 - Populating the Game Canvas
 
 Now that we've written some basic elements, let's start writing the game. The
diff --git a/doc/src/declarative/advtutorial3.qdoc b/doc/src/declarative/advtutorial3.qdoc
index 5ac1be3..e6e4e97 100644
--- a/doc/src/declarative/advtutorial3.qdoc
+++ b/doc/src/declarative/advtutorial3.qdoc
@@ -41,7 +41,6 @@
 
 /*!
 \page advtutorial3.html
-\example declarative/tutorials/samegame/samegame3
 \title Advanced Tutorial 3 - Implementing the Game Logic
 
 First we add to the \c initBoard function clearing of the board before filling it up again, so that clicking new game won't leave the previous game
diff --git a/doc/src/declarative/advtutorial4.qdoc b/doc/src/declarative/advtutorial4.qdoc
index 2599e32..aaa7293 100644
--- a/doc/src/declarative/advtutorial4.qdoc
+++ b/doc/src/declarative/advtutorial4.qdoc
@@ -41,7 +41,6 @@
 
 /*!
 \page advtutorial4.html
-\example declarative/tutorials/samegame/samegame4
 \title Advanced Tutorial 4 - Finishing Touches
 
 Now we're going to do two things to liven the game up. Animate the blocks and add a web-based high score system.
diff --git a/doc/src/declarative/animation.qdoc b/doc/src/declarative/animation.qdoc
index 1314493..d05a444 100644
--- a/doc/src/declarative/animation.qdoc
+++ b/doc/src/declarative/animation.qdoc
@@ -186,7 +186,7 @@ Transition {
 }
 \endcode
 
-To insert an explicit animation into your transition, you can use \target and \property as normal.
+To insert an explicit animation into your transition, you can use \c target and \c property as normal.
 
 \code
 Transition {
@@ -214,8 +214,8 @@ Transition {
 
 \section1 Property Behaviors
 
-A property behavior specifies a default animation to run whenever the property's value changes, regardless
-of what caused the change. Unlike Transition, Behavior doesn't provide a way to indicate that a Behavior
+A \l{Behavior}{property behavior} specifies a default animation to run whenever the property's value changes, regardless
+of what caused the change. Unlike Transition, \l Behavior doesn't provide a way to indicate that a Behavior
 should only apply under certain circumstances.
 
 In the following snippet, we specify that we want the x position of redRect to be animated
diff --git a/doc/src/declarative/qmldocument.qdoc b/doc/src/declarative/qmldocument.qdoc
index 2775ea6..453c023 100644
--- a/doc/src/declarative/qmldocument.qdoc
+++ b/doc/src/declarative/qmldocument.qdoc
@@ -44,9 +44,9 @@
 \title QML Documents
 
 A QML document is a block of QML source code.  QML documents generally correspond to files 
-stored on a disk or network resource, but can be constructed directly from text data.
+stored on a disk or network resource, but can also be constructed directly from text data.
 
-A simple QML document looks like this:
+Here is a simple QML document:
 
 \code
 import Qt 4.6
diff --git a/doc/src/declarative/qmlintro.qdoc b/doc/src/declarative/qmlintro.qdoc
index f84d614..2487a85 100644
--- a/doc/src/declarative/qmlintro.qdoc
+++ b/doc/src/declarative/qmlintro.qdoc
@@ -48,7 +48,7 @@
 \section1 What is QML?
 
 QML is a declarative language designed to describe the user interface of a
-program: both what it looks like and how it behaves. In QML, a user
+program: both what it looks like, and how it behaves. In QML, a user
 interface is specified as a tree of objects with properties.
 
 \section1 What should I know before starting?
@@ -56,8 +56,8 @@ interface is specified as a tree of objects with properties.
 This introduction is meant for those with little or no programming
 experience. JavaScript is used as a scripting language in QML, so you may want
 to learn a bit more about it (\l{JavaScript: The Definitive Guide}) before diving
-too deep into QML. It's also helpful to have a basic understanding of other web
-technologies like HTML and CSS, but not required.
+deeper into QML. It's also helpful to have a basic understanding of other web
+technologies like HTML and CSS, but it's not required.
 
 \section1 Basic QML Syntax
 
@@ -131,18 +131,18 @@ Item {
 }
 \endcode
 
-In the example above, the Text2 object will display the same text as Text1. If Text1 is updated,
-Text2 will be updated as well.
+In the example above, the \c text2 object will display the same text as \c text1. If \c text1 is changed,
+\c text2 is automatically changed to the same value.
 
-Note that to refer to other objects, we use their \e id (more information on the id property can be
-found in a following section).
+Note that to refer to other objects, we use their \e id values. (See below for more
+information on the \e id property.)
 
 \section1 QML Comments
 
 Commenting in QML is similar to JavaScript.
 \list
-\o Single line comments begin with // and end at the end of the line.
-\o Multiline comments begin with /* and end with *\/
+\o Single line comments start with // and finish at the end of the line.
+\o Multiline comments start with /* and finish with *\/
 \endlist
 
 \quotefile doc/src/snippets/declarative/comments.qml
@@ -173,7 +173,7 @@ Properties begin with a lowercase letter (with the exception of \l{Attached Prop
 
 \section2 Property types
 
-QML supports properties of many types (\l{Common QML Types}). The basic types include int,
+QML supports properties of many types (see \l{Common QML Types}). The basic types include int,
 real, bool, string, color, and lists.
 
 \code
@@ -186,12 +186,12 @@ Item {
 \endcode
 
 QML properties are what is known as \e typesafe. That is, they only allow you to assign a value that
-matches the property type. For example, the scale property of item is a real, and if you try to assign
+matches the property type. For example, the \c x property of item is a real, and if you try to assign
 a string to it you will get an error.
 
 \badcode
 Item {
-    scale: "hello"  //illegal!
+    x: "hello"  // illegal!
 }
 \endcode
 
@@ -239,8 +239,8 @@ Image {
 
 \section2 Default properties
 
-Each object type can specify one of its list properties as its default property.
-If a list property has been declared as the default property, the property tag can be omitted.
+Each object type can specify one of its list or object properties as its default property.
+If a property has been declared as the default property, the property tag can be omitted.
 
 For example this code:
 \code
@@ -263,9 +263,27 @@ State {
 
 because \c changes is the default property of the \c State type.
 
-\section2 Dot Properties
+\section2 Grouped Properties
 
+In some cases properties form a logical group and use a 'dot' or grouped notation
+to show this.
 
+Grouped properties can be written like this:
+\qml
+Text {
+    font.pixelSize: 12
+    font.bold: true
+}
+\endqml
+
+or like this:
+\qml
+Text {
+    font { pixelSize: 12; bold: true }
+}
+\endqml
+
+In the element documentation grouped properties are shown using the 'dot' notation.
 
 \section2 Attached Properties
 \target attached-properties
diff --git a/doc/src/declarative/qmlreference.qdoc b/doc/src/declarative/qmlreference.qdoc
index f17e9d7..2c79aeb 100644
--- a/doc/src/declarative/qmlreference.qdoc
+++ b/doc/src/declarative/qmlreference.qdoc
@@ -45,16 +45,22 @@
 
     \target qtdeclarativemainpage
 
-    QML is a language for building highly dynamic and fluid applications. It is targetted at the sorts of user
-    interface (and the sorts of hardware) in embedded devices such as phones, media
-    players, and set-top boxes. It is also appropriate for highly custom desktop
+    QML is a language for building the animation rich,
+    highly fluid user interfaces that are becoming common in portable consumer
+    electronics devices such as mobile phones, media players, set-top boxes and
+    netbooks. It is also appropriate for highly custom desktop
     user interfaces, or special elements in more traditional desktop user interfaces.
 
     Building fluid applications is done declaratively, rather than procedurally.
     That is, you specify \e what the UI should look like and how it should behave
     rather than specifying step-by-step \e how to build it. Specifying a UI declaratively
     does not just include the layout of the interface items, but also the way each
-    individual item looks and behaves and the overall flow of the application.
+    individual item looks and behaves and the overall flow of the application.    
+
+    The QML elements provide a sophisticated set of graphical and behavioral building
+    blocks.  These different elements are combined together in \l {QML Documents}{QML documents} to build components
+    ranging in complexity from simple buttons and sliders, to complete
+    internet-enabled applications like a \l {http://www.flickr.com}{Flickr} photo browser.
 
     Getting Started:
     \list
@@ -69,6 +75,7 @@
     \o \l {QML Documents}
     \o \l {Property Binding}
     \o \l {ECMAScript Blocks}
+    \o \l {QML Scope}
     \o \l {Network Transparency}
     \o \l {qmlmodels}{Data Models}
     \o \l {anchor-layout}{Anchor-based Layout}
@@ -82,5 +89,6 @@
     QML Reference:
     \list
     \o \l {elements}{QML Elements}
+    \o \l {QML Global Object}
     \endlist
 */
diff --git a/doc/src/declarative/qmlstates.qdoc b/doc/src/declarative/qmlstates.qdoc
index 261e3f5..ddb0fc8 100644
--- a/doc/src/declarative/qmlstates.qdoc
+++ b/doc/src/declarative/qmlstates.qdoc
@@ -3,7 +3,7 @@
 \target qmlstates
 \title QML States
 
-QML states describe user interface configurations, including:
+QML states typically describe user interface configurations, including:
 \list
 \o What UI elements are present
 \o The properties of those elements (including how they behave)
@@ -52,7 +52,7 @@ To animate state changes, you can use \l{state-transitions}{transitions}.
 Other things you can do in a state change:
 \list
 \o override signal handlers with PropertyChanges
-\o change an item's parent with ParentChange
+\o change an item's visual parent with ParentChange
 \o change an item's anchors with AnchorChanges
 \o run some script with StateChangeScript
 \endlist
diff --git a/doc/src/declarative/qmlviewer.qdoc b/doc/src/declarative/qmlviewer.qdoc
index f153df2..df96535 100644
--- a/doc/src/declarative/qmlviewer.qdoc
+++ b/doc/src/declarative/qmlviewer.qdoc
@@ -71,7 +71,7 @@
     that is a qreal from 0 to 86400 representing the number of seconds since
     midnight, dummy data for this could be provided by \c dummydata/clock.qml:
     \code
-    Object { property real time: 12345 }
+    QtObject { property real time: 12345 }
     \endcode
     Any QML can be used in the dummy data files. You could even animate the
     fictional data!
diff --git a/doc/src/declarative/scope.qdoc b/doc/src/declarative/scope.qdoc
index fc678d1..f7f25f5 100644
--- a/doc/src/declarative/scope.qdoc
+++ b/doc/src/declarative/scope.qdoc
@@ -44,7 +44,7 @@
 \title QML Scope
 
 \l {Property Binding}s and \l {ECMAScript Blocks} are executed in a scope chain automatically 
-established by QML when constructing a component instance.  QML is a \e {dynamically scoped} 
+established by QML when a component instance is constructed.  QML is a \e {dynamically scoped} 
 language.  Different object instances instantiated from the same component can exist in 
 different scope chains.
 
@@ -91,8 +91,8 @@ Text {
 \section1 QML Local Scope
 
 Most variables references are resolved in the local scope.  The local scope is controlled by the
-QML component in which the binding or script block was declarated.  The following example shows
-three different bindings, and the component that dictates their local scope.
+QML component in which the binding or script block was defined.  The following example shows
+three different bindings, and the component that dictates each local scope.
 
 \table
 \row
@@ -135,15 +135,15 @@ Rectangle { // Local scope component for binding 3
 \endcode
 \endtable
 
-Inside the local scope, four "sub-scopes" exist.  Each "sub-scope" is searched in order when
-resolving a name - names in a higher "sub-scopes" shadow those in lower sub-scopes.
+Inside the local scope, four "sub-scopes" exist.  Each sub-scope is searched in order when
+resolving a name; names in higher sub-scopes shadow those in lower sub-scopes.
 
 \section2 IDs
 
 IDs present in the component take precendence over other names.  The QML engine enforces 
 uniqueness of IDs within a component, so their names cannot conflict with one another.
 
-This is an example of using IDs within bindings.
+Here is an example of using IDs within bindings:
 
 \code
 Item {
@@ -192,7 +192,7 @@ scope object appear in the scope chain, immediately after \l {Script Methods}.
 In bindings and script blocks established explicitly in \l {QML Documents}, the scope object is 
 always the element containing the binding or script block.  The following example shows two
 bindings, one using grouped properties, and the corresponding scope object.  These two bindings
-use the scope object to resolve variable references - \c height is a property on \l Rectangle, 
+use the scope object to resolve variable references: \c height is a property on \l Rectangle, 
 and \c parent is a property on \l Text.
 
 \code
@@ -269,7 +269,7 @@ Item {
 \section1 QML Component chain
 
 When a QML component is instantiated it is given a parent component instance.  The parent 
-component instance is immutable - it is not effected, for example, by changes in the instance's
+component instance is immutable - it is not affected, for example, by changes in the instance's
 visual parent (in the case of visual elements).  Should name resolution fail within the
 \l {QML Local Scope}, this parent chain is searched.
 
@@ -283,8 +283,8 @@ For each component instance in the chain, the following are examined:
 
 This list is a sub-set of that in the \l {QML Local Scope}.
 
-Sub-components used within a component have their parent component instance set to the component
-instance that created them.  In the following example, the two \c Button instances have the 
+A sub-component's parent component instance is set to the component that created it.
+In the following example, the two \c Button instances have the 
 \c main.qml instance as their parent component instance.  If the \c Button type was used from
 within another QML file, it may have a difference parent component instance, and consequently
 the \c buttonClicked() method may resolve differently.