diff -r ef0373b55136 -r 758a864f9613 src/declarative/util/qdeclarativebehavior.cpp
--- a/src/declarative/util/qdeclarativebehavior.cpp	Fri Sep 17 08:34:18 2010 +0300
+++ b/src/declarative/util/qdeclarativebehavior.cpp	Mon Oct 04 01:19:32 2010 +0300
@@ -72,6 +72,7 @@
 
 /*!
     \qmlclass Behavior QDeclarativeBehavior
+  \ingroup qml-animation-transition
     \since 4.7
     \brief The Behavior element allows you to specify a default animation for a property change.
 
@@ -84,12 +85,15 @@
 
     \snippet doc/src/snippets/declarative/behavior.qml 0
 
-    To run multiple animations within a Behavior, use ParallelAnimation or
+    Note that a property cannot have more than one assigned Behavior. To provide
+    multiple animations within a Behavior, use ParallelAnimation or
     SequentialAnimation.
 
-    Note that a property cannot have more than one assigned Behavior.
+    If a \l{QML States}{state change} has a \l Transition that matches the same property as a
+    Behavior, the \l Transition animation overrides the Behavior for that
+    state change.
 
-    \sa {Property Behaviors}, {declarative/animation/behaviors}{Behavior example}, QtDeclarative
+    \sa {QML Animation}, {declarative/animation/behaviors}{Behavior example}, QtDeclarative
 */