diff -r 5dc02b23752f -r 3e2da88830cd src/declarative/util/qdeclarativetransition.cpp
--- a/src/declarative/util/qdeclarativetransition.cpp	Tue Jul 06 15:10:48 2010 +0300
+++ b/src/declarative/util/qdeclarativetransition.cpp	Wed Aug 18 10:37:55 2010 +0300
@@ -56,7 +56,29 @@
     \since 4.7
     \brief The Transition element defines animated transitions that occur on state changes.
 
-    \sa {qmlstates}{States}, {state-transitions}{Transitions}, {QtDeclarative}
+    A Transition defines the animations to be applied when a \l State change occurs.
+
+    For example, the following \l Rectangle has two states: the default state, and
+    an added "moved" state. In the "moved state, the rectangle's position changes 
+    to (50, 50).  The added \l Transition specifies that when the rectangle
+    changes between the default and the "moved" state, any changes
+    to the \c x and \c y properties should be animated, using an \c Easing.InOutQuad.
+   
+    \snippet doc/src/snippets/declarative/transition.qml 0
+
+    To specify multiple transitions, specify \l Item::transitions as a list:
+
+    \qml
+    Item {
+        ...
+        transitions: [
+            Transition { ... }
+            Transition { ... }
+        ]
+    }
+    \endqml
+
+    \sa {declarative/animation/states}{states example}, {qmlstates}{States}, {state-transitions}{Transitions}, {QtDeclarative}
 */
 
 /*!
@@ -171,18 +193,31 @@
 /*!
     \qmlproperty string Transition::from
     \qmlproperty string Transition::to
-    These properties are selectors indicating which state changes should trigger the transition.
+
+    These properties indicate the state changes that trigger the transition.
+
+    The default values for these properties is "*" (that is, any state).
+
+    For example, the following transition has not set the \c to and \c from
+    properties, so the animation is always applied when changing between
+    the two states (i.e. when the mouse is pressed and released).
+
+    \snippet doc/src/snippets/declarative/transition-from-to.qml 0
+
+    If the transition was changed to this:
 
-    from is used in conjunction with to to determine when a transition should
-    be applied. By default from and to are both "*" (any state). In the following example,
-    the transition is applied when changing from state1 to state2.
-    \code
-    Transition {
-        from: "state1"
-        to: "state2"
-        ...
+    \qml
+        transitions: Transition { 
+            to: "brighter"
+            ColorAnimation { duration: 1000 }
+        }
     }
-    \endcode
+    \endqml
+
+    The animation would only be applied when changing from the default state to
+    the "brighter" state (i.e. when the mouse is pressed, but not on release).
+
+    \sa reversible
 */
 QString QDeclarativeTransition::fromState() const
 {
@@ -205,6 +240,24 @@
     This property holds whether the transition should be automatically reversed when the conditions that triggered this transition are reversed.
 
     The default value is false.
+
+    By default, transitions run in parallel and are applied to all state
+    changes if the \l from and \l to states have not been set. In this
+    situation, the transition is automatically applied when a state change
+    is reversed, and it is not necessary to set this property to reverse
+    the transition.
+
+    However, if a SequentialAnimation is used, or if the \l from or \l to 
+    properties have been set, this property will need to be set to reverse
+    a transition when a state change is reverted. For example, the following
+    transition applies a sequential animation when the mouse is pressed,
+    and reverses the sequence of the animation when the mouse is released:
+
+    \snippet doc/src/snippets/declarative/transition-reversible.qml 0
+
+    If the transition did not set the \c to and \c reversible values, then 
+    on the mouse release, the transition would play the PropertyAnimation
+    before the ColorAnimation instead of reversing the sequence.
 */
 bool QDeclarativeTransition::reversible() const
 {
@@ -241,12 +294,27 @@
 /*!
     \qmlproperty list<Animation> Transition::animations
     \default
+
     This property holds a list of the animations to be run for this transition.
 
+    \qml
+    Transition {
+        PropertyAnimation { ... }
+        NumberAnimation { ... }
+    }
+    \endqml
+
     The top-level animations are run in parallel. To run them sequentially,
-    you can create a single SequentialAnimation which contains all the animations,
-    and assign that to animations the animations property.
-    \default
+    define them within a SequentialAnimation:
+
+    \qml
+    Transition {
+        SequentialAnimation {
+            PropertyAnimation { ... }
+            NumberAnimation { ... }
+        }
+    }
+    \endqml
 */
 QDeclarativeListProperty<QDeclarativeAbstractAnimation> QDeclarativeTransition::animations()
 {