doc: add alias cycle in qmllint warnings

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

Task-number: QTBUG-111137
Change-Id: I0743c7700aa2d4d84b687604b5f61a9f01d05f37
Reviewed-by: Ulf Hermann <ulf.hermann@qt.io>

1 files changed, 41 insertions, 7 deletions

diff --git a/src/qml/doc/src/qmllint/alias-cycle.qdoc b/src/qml/doc/src/qmllint/alias-cycle.qdoc
index fcc3cb801a..561cedf416 100644
--- a/src/qml/doc/src/qmllint/alias-cycle.qdoc
+++ b/src/qml/doc/src/qmllint/alias-cycle.qdoc
@@ -5,22 +5,56 @@
 \page qmllint-warnings-and-errors-alias-cycle.html
 \ingroup qmllint-warnings-and-errors
 
-\title alias-cycle
-\brief BRIEF
+\title Alias Cycle
+\brief Alias property is part of an alias cycle.
 
-\section1 alias-cycle
+\section1 Alias Property Is Part Of An Alias Cycle
 
 \section2 What happened?
-TODO
+A \l{QML Object Attributes#property-aliases}{property alias} resolves to itself or to another
+alias resolving to itself.
+
+Usually, \l{QML Object Attributes#property-aliases}{a property alias} should reference another
+property either directly, or indirectly by passing through another alias property.
+
+If a property alias directly or indirectly references itself, then it forms an alias cycle.
+The warning indicates that the current alias property is inside or references
+an alias cycle, see \l{#example}{Example}.
 
 \section2 Why is this bad?
-TODO
+Instances of components with alias cycles will not be created at runtime: they will be null instead.
 
 \section2 Example
 \qml
+import QtQuick
+
+Item {
+    id: someId
+    property alias myself: someId.myself // not ok: referring to itself
+
+    property alias cycle: someId.cycle2 // not ok: indirectly referring to itself
+    property alias cycle2: someId.cycle
+
+    property alias indirect: someId.cycle // not ok: referring to alias indirectly referring to itself
+}
 \endqml
-You can fix this warning by TODO
+You can fix this warning by breaking up the alias cycles:
 \qml
+import QtQuick
+
+Item {
+    id: someId
+    Item {
+        id: anotherId
+        property string myself
+        property int cycle
+    }
+    property alias myself: anotherId.myself // ok: referring to a property
+
+    property alias cycle: someId.cycle2 // ok: does not refer to itself anymore
+    property alias cycle2: anotherId.cycle // ok: not a cycle anymore
+
+    property alias indirect: someId.cycle // ok: cycle does not form an alias cycle anymore
+}
 \endqml
 */
-