Move the Property Modifier Type documentation

Property Modifier Types are just another sort of QML object type, and
don't deserve explicit top-level documentation.  This commit moves the
docs into the object types documentation, and adds documentation to the
syntax page about the "<PropertyModifierObject> on <propertyName>"
syntax.

Change-Id: Ia9b707739b562d2c8b75fa99b88795ba4d415cf7
Reviewed-by: Michael Brasser <michael.brasser@nokia.com>

6 files changed, 114 insertions, 69 deletions

diff --git a/src/qml/doc/src/cppintegration/definetypes.qdoc b/src/qml/doc/src/cppintegration/definetypes.qdoc
index 9a8be977ca..5ba6b81f68 100644
--- a/src/qml/doc/src/cppintegration/definetypes.qdoc
+++ b/src/qml/doc/src/cppintegration/definetypes.qdoc
@@ -475,13 +475,63 @@ qDebug() << "Value of MessageBoard.expired:" << attached->expired();
 \endcode
 
 
-\section2 Property Value Sources
+\section2 Property Modifier Types
 
-In the QML language syntax, there is a concept of \e {property value sources}.
-These are QML types that can automatically update the value of a property over
-time, using the \c {<PropertyValueSource> on <property>} syntax. For example,
-the various \l{qtquick-statesanimations-animations.html}{property animation}
-types provided by the \c QtQuick module are examples of property value sources.
+A property modifier type is a special kind of QML object type.  A property
+modifier type instance affects a property (of a QML object instance) which it
+is applied to.  There are two different kinds of property modifier types:
+\list
+\li property value write interceptors
+\li property value sources
+\endlist
+
+A property value write interceptor can be used to filter or modify values as
+they are written to properties.  Currently, the only supported property
+value write interceptor is the \l Behavior type provided by the \c QtQuick
+import.
+
+A property value source can be used to automatically update the value of a
+property over time.  Clients can define their own property value source types.
+The various \l{qtquick-statesanimations-animations.html}{property animation}
+types provided by the \c QtQuick import are examples of property value
+sources.
+
+Property modifier type instances can be created and applied to a property of
+a QML object through the "<ModifierType> on <propertyName>" syntax, as the
+following example shows:
+
+\qml
+import QtQuick 2.0
+
+Item {
+    width: 400
+    height: 50
+
+    Rectangle {
+        width: 50
+        height: 50
+        color: "red"
+
+        NumberAnimation on x {
+            from: 0
+            to: 350
+            loops: Animation.Infinite
+            duration: 2000
+        }
+    }
+}
+\endqml
+
+Clients can register their own property value source types, but currently not
+property value write interceptors.
+
+\section3 Property Value Sources
+
+\e {Property value sources} are QML types that can automatically update the
+value of a property over time, using the
+\c {<PropertyValueSource> on <property>} syntax. For example, the various
+\l{qtquick-statesanimations-animations.html}{property animation} types
+provided by the \c QtQuick module are examples of property value sources.
 
 A property value source can be implemented in C++ by subclassing
 QQmlPropertyValueSource and providing an implementation that writes different
diff --git a/src/qml/doc/src/qtqml.qdoc b/src/qml/doc/src/qtqml.qdoc
index c13ed4395b..b525b92be9 100644
--- a/src/qml/doc/src/qtqml.qdoc
+++ b/src/qml/doc/src/qtqml.qdoc
@@ -76,7 +76,6 @@ for an introduction to writing QML applications.
             \li \l{qtqml-documents-definetypes.html}{Defining Object Types from QML}
             \li \l{qtqml-cppintegration-definetypes.html}{Defining Object Types from C++}
             \endlist
-        \li \l{qtqml-typesystem-topic.html#property-modifier-types}{Property Modifier Types}
         \endlist
 
     \li \l{qtqml-modules-topic.html}{QML Modules}
diff --git a/src/qml/doc/src/syntax/objectattributes.qdoc b/src/qml/doc/src/syntax/objectattributes.qdoc
index 894424cedd..314bd4512b 100644
--- a/src/qml/doc/src/syntax/objectattributes.qdoc
+++ b/src/qml/doc/src/syntax/objectattributes.qdoc
@@ -600,6 +600,34 @@ Item {
 \l {Property Aliases}{alias} property.
 
 
+\section3 Property Modifier Objects
+
+Properties can have
+\l{qtqml-cppintegration-definetypes.html#property-modifier-types}
+{property value modifier objects} associated with them.
+The syntax for declaring an instance of a property modifier type associated
+with a particular property is as follows:
+
+\code
+<PropertyModifierTypeName> on <propertyName> {
+    // attributes of the object instance
+}
+\endcode
+
+It is important to note that the above syntax is in fact an
+\l{qtqml-syntax-basics.html#object-declarations}{object declaration} which
+will instantiate an object which acts on a pre-existing property.
+
+Certain property modifier types may only be applicable to specific property
+types, however this is not enforced by the language.  For example, the
+\c NumberAnimation type provided by \c QtQuick will only animate
+numeric-type (such as \c int or \c real) properties.  Attempting to use a
+\c NumberAnimation with non-numeric property will not result in an error,
+however the non-numeric property will not be animated.  The behavior of a
+property modifier type when associated with a particular property type is
+defined by its implementation.
+
+
 \section2 Signal Attributes
 
 A signal is a notification from an object that some event has occurred: for
diff --git a/src/qml/doc/src/typesystem/objecttypes.qdoc b/src/qml/doc/src/typesystem/objecttypes.qdoc
index faa76b4ce7..3d807fc938 100644
--- a/src/qml/doc/src/typesystem/objecttypes.qdoc
+++ b/src/qml/doc/src/typesystem/objecttypes.qdoc
@@ -119,21 +119,14 @@ See \l{qtqml-documents-scope.html}{Scope and Naming Resolution} for more details
 C++ plugin writers and application developers may register types defined in C++
 through API provided by the Qt QML module.  There are various registration
 functions which each allow different use-cases to be fulfilled.
-
-\list
-\li qmlRegisterType
-\li qmlRegisterUncreatableType
-\li qmlRegisterExtendedType
-\li qmlRegisterInterface
-\li qmlRegisterCustomType
-\li qmlRegisterSingletonType
-\endlist
-
-For more information on this topic, see the documentation regarding
+For more information about those registration functions, and the specifics of
+exposing custom C++ types to QML, see the documentation regarding
 \l{qtqml-cppintegration-definetypes.html}{Defining QML Types from C++}.
 
 The QML type-system relies on imports, plugins and extensions being installed
 into a known import path.  Plugins may be provided by third-party developers
-and reused by client application developers.
+and reused by client application developers.  Please see the documentation
+about \l{qtqml-modules-topic.html}{QML modules} for more information about
+how to create and deploy a QML extension module.
 
 */
diff --git a/src/qml/doc/src/typesystem/topic.qdoc b/src/qml/doc/src/typesystem/topic.qdoc
index 3fe17943bb..098c2ed630 100644
--- a/src/qml/doc/src/typesystem/topic.qdoc
+++ b/src/qml/doc/src/typesystem/topic.qdoc
@@ -95,54 +95,4 @@ re-used in other QML documents.  See the documentation about
 \l{qtqml-typesystem-objecttypes.html}{object types in the QML type system} for
 in-depth information about object types.
 
-\section1 Property Modifier Types
-
-A property modifier type is a special kind of QML object type.  A property
-modifier type instance affects a property (of a QML object instance) which it
-is applied to.  There are two different kinds of property modifier types:
-\list
-\li property value write interceptors
-\li property value sources
-\endlist
-
-A property value write interceptor can be used to filter or modify values as
-they are written to properties.  Currently, the only supported property
-value write interceptor is the \l Behavior type provided by the \c QtQuick
-import.
-
-A property value source can be used to automatically update the value of a
-property over time.  Clients can define their own property value source types.
-The various \l{qtquick-statesanimations-animations.html}{property animation}
-types provided by the \c QtQuick import are examples of property value
-sources.
-
-Property modifier type instances can be created and applied to a property of
-a QML object through the "<ModifierType> on <propertyName>" syntax, as the
-following example shows:
-
-\qml
-import QtQuick 2.0
-
-Item {
-    width: 400
-    height: 50
-
-    Rectangle {
-        width: 50
-        height: 50
-        color: "red"
-
-        NumberAnimation on x {
-            from: 0
-            to: 350
-            loops: Animation.Infinite
-            duration: 2000
-        }
-    }
-}
-\endqml
-
-See the documentation on \l QQmlPropertyValueSource for information about how
-to define your own property value source types.
-
 */
diff --git a/src/quick/doc/src/concepts/statesanimations/topic.qdoc b/src/quick/doc/src/concepts/statesanimations/topic.qdoc
index e909dbc5dd..b498a28079 100644
--- a/src/quick/doc/src/concepts/statesanimations/topic.qdoc
+++ b/src/quick/doc/src/concepts/statesanimations/topic.qdoc
@@ -90,6 +90,31 @@ and transition elements.  See the documentation on
 and how to use them.
 
 
+\section1 Animating Property Assignments
+
+Animations are not only related to states and transitions between states.  For
+example, an animation might be triggered by other events, which are not
+associated with a distinct state.
+
+It is often beneficial to always animate changes to certain properties of
+visual items, regardless of the cause of the change (for example, opacity
+effects).  Qt Quick provides the \l Behavior type which allows the client to
+specify animation behavior for changes to properties.  The \l Behavior type
+is an example of a QML object
+\l{qtqml-cppintegration-definetypes.html#property-modifier-types}
+{property modifier}.
+
+Please see the documentation about
+\l{qtquick-statesanimations-animations.html#default-animation-as-behaviors}
+{default property animations} for more information about using the \l Behavior
+element to provide default property change animations.
+
+It is important to note, that using default property animations (via the
+\l Behavior type) in combination with state-transition animations can sometimes
+result in undefined behavior occurring.  Please see the documentation about
+\l{qtquick-statesanimations-behaviors.html}
+{using Qt Quick Behaviors with States} for more information about this topic.
+
 \section1 Animated Sprites
 
 The concept of animated sprites is separate to the concept of animations as