diff -r ef0373b55136 -r 758a864f9613 src/declarative/util/qdeclarativetransition.cpp
--- a/src/declarative/util/qdeclarativetransition.cpp	Fri Sep 17 08:34:18 2010 +0300
+++ b/src/declarative/util/qdeclarativetransition.cpp	Mon Oct 04 01:19:32 2010 +0300
@@ -53,6 +53,7 @@
 
 /*!
     \qmlclass Transition QDeclarativeTransition
+    \ingroup qml-animation-transition
     \since 4.7
     \brief The Transition element defines animated transitions that occur on state changes.
 
@@ -60,31 +61,42 @@
 
     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
+    to (50, 50).  The added 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:
+    Notice the example does not require \l{PropertyAnimation::}{to} and 
+    \l{PropertyAnimation::}{from} values for the NumberAnimation. As a convenience,
+    these properties are automatically set to the values of \c x and \c y before
+    and after the state change; the \c from values are provided by
+    the current values of \c x and \c y, and the \c to values are provided by
+    the PropertyChanges object. If you wish, you can provide \l{PropertyAnimation::}{to} and 
+    \l{PropertyAnimation::}{from} values anyway to override the default values.
+
+    By default, a Transition's animations are applied for any state change in the 
+    parent item. The  Transition \l {Transition::}{from} and \l {Transition::}{to} 
+    values can be set to restrict the animations to only be applied when changing 
+    from one particular state to another.
+
+    To define multiple transitions, specify \l Item::transitions as a list:
 
     \qml
     Item {
         ...
         transitions: [
-            Transition { ... }
+            Transition { ... },
             Transition { ... }
         ]
     }
     \endqml
 
-    \sa {declarative/animation/states}{states example}, {qmlstates}{States}, {state-transitions}{Transitions}, {QtDeclarative}
-*/
+    If a state change has a Transition that matches the same property as a
+    \l Behavior, the Transition animation overrides the \l Behavior for that
+    state change.
 
-/*!
-    \internal
-    \class QDeclarativeTransition
-    \brief The QDeclarativeTransition class allows you to define animated transitions that occur on state changes.
+    \sa {QML Animation}, {declarative/animation/states}{states example}, {qmlstates}{States}, {QtDeclarative}
 */
 
 //ParallelAnimationWrapper allows us to do a "callback" when the animation finishes, rather than connecting