Doc: Explicitly un-specify order of binding evaluation

You cannot rely on any binding to evaluate before or after beginCreate()
returns or QQmlIncubater::setInitialState() is called.

Pick-to: 6.6 6.5
Task-number: QTBUG-117968
Change-Id: Ib38ecf6bc8dbd8a82167cdc4b2527bf48da23c10
Reviewed-by: Fabian Kosmale <fabian.kosmale@qt.io>
Reviewed-by: Andreas Aardal Hanssen <andrhans@cisco.com>

2 files changed, 22 insertions, 3 deletions

diff --git a/src/qml/qml/qqmlcomponent.cpp b/src/qml/qml/qqmlcomponent.cpp
index 3102e879fe..11ef88444e 100644
--- a/src/qml/qml/qqmlcomponent.cpp
+++ b/src/qml/qml/qqmlcomponent.cpp
@@ -995,6 +995,15 @@ QObject *QQmlComponentPrivate::createWithProperties(QObject *parent, const QVari
 
     The ownership of the returned object instance is transferred to the caller.
 
+    \note The categorization of bindings into constant values and actual
+    bindings is intentionally unspecified and may change between versions of Qt
+    and depending on whether and how you are using \l{qmlcachegen}. You should
+    not rely on any particular binding to be evaluated either before or after
+    beginCreate() returns. For example a constant expression like
+    \e{MyType.EnumValue} may be recognized as such at compile time or deferred
+    to be executed as binding. The same holds for constant expressions like
+    \e{-(5)} or \e{"a" + " constant string"}.
+
     \sa completeCreate(), QQmlEngine::ObjectOwnership
 */
 QObject *QQmlComponent::beginCreate(QQmlContext *context)
diff --git a/src/qml/qml/qqmlincubator.cpp b/src/qml/qml/qqmlincubator.cpp
index 9d06896bdd..5c18230450 100644
--- a/src/qml/qml/qqmlincubator.cpp
+++ b/src/qml/qml/qqmlincubator.cpp
@@ -760,13 +760,23 @@ void QQmlIncubator::statusChanged(Status status)
 }
 
 /*!
-Called after the \a object is first created, but before property bindings are
-evaluated and, if applicable, QQmlParserStatus::componentComplete() is
-called.  This is equivalent to the point between QQmlComponent::beginCreate()
+Called after the \a object is first created, but before complex property
+bindings are evaluated and, if applicable, QQmlParserStatus::componentComplete()
+is called. This is equivalent to the point between QQmlComponent::beginCreate()
 and QQmlComponent::completeCreate(), and can be used to assign initial values
 to the object's properties.
 
 The default implementation does nothing.
+
+\note Simple bindings such as numeric literals are evaluated before
+setInitialState() is called. The categorization of bindings into simple and
+complex ones is intentionally unspecified and may change between versions of
+Qt and depending on whether and how you are using \l{qmlcachegen}. You should
+not rely on any particular binding to be evaluated either before or after
+setInitialState() is called. For example, a constant expression like
+\e{MyType.EnumValue} may be recognized as such at compile time or deferred
+to be executed as binding. The same holds for constant expressions like
+\e{-(5)} or \e{"a" + " constant string"}.
 */
 void QQmlIncubator::setInitialState(QObject *object)
 {