From 8caf3a066af32924d908171e1f3b5b30c76c992c Mon Sep 17 00:00:00 2001
From: Sami Shalayel <sami.shalayel@qt.io>
Date: Fri, 13 Oct 2023 15:25:13 +0200
Subject: doc: add duplicate property warning in qmllint warnings

Add description of the warning and an example on how to fix it.

Task-number: QTBUG-111137
Change-Id: I3cf959b212b85c5081ae67ff031e194f9f1f4545
Reviewed-by: Ulf Hermann <ulf.hermann@qt.io>
---
 .../src/qmllint/duplicate-property-binding.qdoc    | 107 +++++++++++++++++++--
 1 file changed, 101 insertions(+), 6 deletions(-)

(limited to 'src/qml/doc')

diff --git a/src/qml/doc/src/qmllint/duplicate-property-binding.qdoc b/src/qml/doc/src/qmllint/duplicate-property-binding.qdoc
index 73245ff187..90602f0410 100644
--- a/src/qml/doc/src/qmllint/duplicate-property-binding.qdoc
+++ b/src/qml/doc/src/qmllint/duplicate-property-binding.qdoc
@@ -5,22 +5,117 @@
 \page qmllint-warnings-and-errors-duplicate-property-binding.html
 \ingroup qmllint-warnings-and-errors
 
-\title duplicate-property-binding
-\brief BRIEF
+\title Duplicate Bindings
+\brief A property was bound multiple times.
 
-\section1 duplicate-property-binding
+This warning category has multiple warnings:
+\list
+    \li \l{Duplicate Interceptor On Property}
+    \li \l{Cannot Combine Value Source And Binding}
+    \li \l{Duplicate Value Source On Property}
+\endlist
+
+\section1 Duplicate Interceptor On Property
+
+\section2 What happened?
+One property has multiple \l{Property Modifier Types}{interceptors}.
+
+\section2 Why is this bad?
+Setting multiple interceptors on the same property is unsupported by the QML engine.
+
+\section2 Example
+
+Lets use \l{Behavior} as interceptor twice on the same property:
+\qml
+import QtQuick
+
+Rectangle {
+    Behavior on width {
+        NumberAnimation { duration: 1000 }
+    }
+    Behavior on width { // not ok: Duplicate interceptor on property "width" [duplicate-property-binding]
+        NumberAnimation { duration: 2000 }
+    }
+}
+\endqml
+You can fix this warning by removing all but one \l{Behavior}:
+\qml
+import QtQuick
+
+Rectangle {
+    Behavior on width {
+        NumberAnimation { duration: 2000 }
+    }
+}
+
+\sa {Property Modifier Types}
+
+\section1 Duplicate Value Source On Property
+
+\section2 What happened?
+One property has multiple \l{Property Value Sources}{value sources}.
+
+\section2 Why is this bad?
+The value sources will show unexpected behavior when combined. See \l{Example}{example} below.
+
+\section2 Example
+
+Lets use \l{NumberAnimation} as value source twice on the same property:
+\qml
+import QtQuick
+
+Rectangle {
+    NumberAnimation on x { to: 50; duration: 1000 }
+    NumberAnimation on x { to: 10; duration: 100 } // not ok: Duplicate value source on property "x" [duplicate-property-binding]
+
+    onXChanged: console.log(x)
+}
+\endqml
+
+If you check the output of that program, you will see that the two NumberAnimation will interleave
+each other, which is probably not the effect that was intended.
+You can fix this warning by removing all but one \l{NumberAnimation}:
+\qml
+import QtQuick
+
+Rectangle {
+    NumberAnimation on x { to: 50; duration: 1000 }
+}
+\endqml
+
+
+\section1 Cannot Combine Value Source And Binding
 
 \section2 What happened?
-TODO
+One property has a \l{Property Value Sources}{value source} and a binding on the same property.
 
 \section2 Why is this bad?
-TODO
+The binding will updated the property value before the value source starts updating this property.
+This may lead to unexpected behavior, and is also harder to read.
 
 \section2 Example
+
+Lets use \l{NumberAnimation} as value source on the same property:
 \qml
+import QtQuick
+
+Rectangle {
+    NumberAnimation on x { to: 50; duration: 1000 } // not ok: Cannot combine value source and binding on property "x" [duplicate-property-binding]
+    x: 55
+
+    onXChanged: console.log(x)
+}
 \endqml
-You can fix this warning by TODO
+
+If you check the output of that program, you will see that the \l{NumberAnimation} will animate
+from 55 to 50, which would be easier to read with following code:
 \qml
+import QtQuick
+
+Rectangle {
+    NumberAnimation on x { from: 55; to: 50; duration: 1000 } // ok: intentions are clearer now!
+}
 \endqml
+
 */
 
-- 
cgit v1.2.3