Doc improvments

5 files changed, 31 insertions, 12 deletions

diff --git a/doc/src/declarative/animation.qdoc b/doc/src/declarative/animation.qdoc
index d05a444..bf5907d 100644
--- a/doc/src/declarative/animation.qdoc
+++ b/doc/src/declarative/animation.qdoc
@@ -49,6 +49,8 @@ real, int, color, rect, point, and size can all be animated.
 QML supports three different forms of animation - basic property animation,
 transitions, and property behaviors.
 
+\tableofcontents
+
 \section1 Basic Property Animation
 
 The simplest form of animation is directly using \l PropertyAnimation, which can animate all of the property
diff --git a/doc/src/declarative/extending.qdoc b/doc/src/declarative/extending.qdoc
index 7a9de60..5985494 100644
--- a/doc/src/declarative/extending.qdoc
+++ b/doc/src/declarative/extending.qdoc
@@ -636,7 +636,7 @@ declaring a new property, and the corresponding C++ type.
 \row \o variant \o QVariant
 \endtable
 
-QML supports two methods for adding a new property to a type - a new property
+QML supports two methods for adding a new property to a type: a new property
 definition, and a property alias.
 
 \section2 Property definitions
@@ -714,10 +714,10 @@ binding, the alias reference syntax is highly restricted.
 
 An alias reference takes one of the following forms
 \code
-    <Id>.<property>
-    <Id>
+    <id>.<property>
+    <id>
 \endcode
-where <Id> must refer to an object id within the same component as the type
+where <id> must refer to an object id within the same component as the type
 declaring the alias, and, optionally, <property> refers to a property on that object.  
 
 Here is the property definition example rewritten to use property aliases.
diff --git a/doc/src/declarative/focus.qdoc b/doc/src/declarative/focus.qdoc
index 8061a7c..924f590 100644
--- a/doc/src/declarative/focus.qdoc
+++ b/doc/src/declarative/focus.qdoc
@@ -49,6 +49,8 @@ focused QML \l Item.  To facilitate the construction of reusable components
 and to address some of the cases unique to fluid user interfaces, the QML items add a
 \e scope based extension to Qt's traditional keyboard focus model.
 
+\tableofcontents
+
 \section1 Key Handling Overview
 
 When the user presses or releases a key, the following occurs:
diff --git a/doc/src/declarative/qmlstates.qdoc b/doc/src/declarative/qmlstates.qdoc
index ddb0fc8..245a57f 100644
--- a/doc/src/declarative/qmlstates.qdoc
+++ b/doc/src/declarative/qmlstates.qdoc
@@ -3,6 +3,8 @@
 \target qmlstates
 \title QML States
 
+\section1 Overview
+
 QML states typically describe user interface configurations, including:
 \list
 \o What UI elements are present
@@ -14,10 +16,12 @@ A state can also be thought of as a set of batched changes from a default config
 
 Examples of states in modern UI:
 \list
-\o A Contacts application has a 'View Contact' state and an 'Edit Contact' State. In the first state the information presented is static (using labels), and in the second it is editable (using editors).
-\o A button has a pressed and unpressed state. When pressed the text moves down and to the right, and the button has a slightly darker appearance.
+\o An Address Book application with a 'View Contact' state and an 'Edit Contact' State. In the first state the contact information presented is read-only (using labels), and in the second it is editable (using editors).
+\o A button with a pressed and unpressed state. When pressed the text moves slightly down and to the right, and the button has a slightly darker appearance.
 \endlist
 
+\section1 States in QML
+
 In QML:
 \list
 \o Any object can use states.
@@ -25,29 +29,38 @@ In QML:
 \o A state can affect the properties of other objects, not just the object owning the state (and not just that object's children).
 \endlist
 
-The following example shows a simple use of states. In the default state \c myrect is positioned at 0,0. In the 'moved' state it is positioned at 50,50.
+Here is an example of using states. In the default state \c myRect is positioned at 0,0. In the 'moved' state it is positioned at 50,50. Clicking within the mouse region changes the state from the default state to the 'moved' state.
 
-\code
+\qml
 Item {
+    id: myItem
+
     Rectangle {
-        id: myrect
+        id: myRect
         width: 100
         height: 100
+        color: "red"
     }
+
     states: [
         State {
             name: "moved"
             PropertyChanges {
-                target: myrect
+                target: myRect
                 x: 50
                 y: 50
             }
         }
     ]
+
+    MouseRegion {
+        anchors.fill: parent
+        onClicked: myItem.state = 'moved'
+    }
 }
-\endcode
+\endqml
 
-To animate state changes, you can use \l{state-transitions}{transitions}.
+State changes can be animated using \l{state-transitions}{transitions}.
 
 Other things you can do in a state change:
 \list
diff --git a/doc/src/declarative/scope.qdoc b/doc/src/declarative/scope.qdoc
index f7f25f5..ef30f94 100644
--- a/doc/src/declarative/scope.qdoc
+++ b/doc/src/declarative/scope.qdoc
@@ -43,6 +43,8 @@
 \page qmlscope.html
 \title QML Scope
 
+\tableofcontents
+
 \l {Property Binding}s and \l {ECMAScript Blocks} are executed in a scope chain automatically 
 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