Document that clearComponentCache() does not clear existing objects

Task-number: QTBUG-95788
Change-Id: I547ec38676d7e6f9b25fea79f58b94eacb135a5f
Reviewed-by: Fabian Kosmale <fabian.kosmale@qt.io>
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
(cherry picked from commit ae33c2da3ec33c2280167c0202aab6cd5d168b82)
Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>

1 files changed, 10 insertions, 0 deletions

diff --git a/src/qml/qml/qqmlengine.cpp b/src/qml/qml/qqmlengine.cpp
index 663c70fcb9..25f1e37fad 100644
--- a/src/qml/qml/qqmlengine.cpp
+++ b/src/qml/qml/qqmlengine.cpp
@@ -1063,6 +1063,16 @@ QQmlEngine::~QQmlEngine()
   Once the component cache has been cleared, components must be loaded before
   any new objects can be created.
 
+  \note Any existing objects created from QML components retain their types,
+  even if you clear the component cache. This includes singleton objects. If you
+  create more objects from the same QML code after clearing the cache, the new
+  objects will be of different types than the old ones. Assigning such a new
+  object to a property of its declared type belonging to an object created
+  before clearing the cache won't work.
+
+  As a general rule of thumb, make sure that no objects created from QML
+  components are alive when you clear the component cache.
+
   \sa trimComponentCache()
  */
 void QQmlEngine::clearComponentCache()