Improve documentation for incubators and incubation controllers

We don't want to promote manual event processing. Simply state that the
initialization and polling should happen in different places and time
should pass between them.

Furthermore, mention the pre-created incubation controllers that are
usually good enough for most people. Don't shine such a negative light
on the incubation controller snippet. It's good to have a simple example
you can immediately understand.

Fixes: QTBUG-116804
Change-Id: I496426e18147ce19d08ca1cd0945c99f4ff1e2ad
Reviewed-by: Fabian Kosmale <fabian.kosmale@qt.io>
(cherry picked from commit 589d0fa5de6b732bad0deb87d3797ba4a18e9de2)
Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>
(cherry picked from commit 56ec9ac8683025b7de6b0c82019a1216bfddb9b8)

1 files changed, 30 insertions, 12 deletions

diff --git a/src/qml/qml/qqmlincubator.cpp b/src/qml/qml/qqmlincubator.cpp
index aa696d5434..5b863ef312 100644
--- a/src/qml/qml/qqmlincubator.cpp
+++ b/src/qml/qml/qqmlincubator.cpp
@@ -177,9 +177,15 @@ protected:
 };
 \endcode
 
-Although the previous example would work, it is not optimal.  Real world incubation
-controllers should try and maximize the amount of idle time they consume - rather
-than a static amount like 5 milliseconds - while not disturbing the application.
+Although the example works, it is heavily simplified. Real world incubation controllers
+try and maximize the amount of idle time they consume while not disturbing the
+application. Using a static amount of 5 milliseconds like above may both leave idle
+time on the table in some frames and disturb the application in others.
+
+\l{QQuickWindow}, \l{QQuickView}, and \l{QQuickWidget} all pre-create an incubation
+controller that spaces out incubation over multiple frames using a more intelligent
+algorithm. You rarely have to write your own.
+
 */
 
 /*!
@@ -458,25 +464,37 @@ synchronously which, depending on the complexity of the object,  can cause notic
 stutters in the application.
 
 The use of QQmlIncubator gives more control over the creation of a QML object,
-including allowing it to be created asynchronously using application idle time.  The following
+including allowing it to be created asynchronously using application idle time. The following
 example shows a simple use of QQmlIncubator.
 
 \code
+// Initialize the incubator
 QQmlIncubator incubator;
 component->create(incubator);
+\endcode
 
-while (!incubator.isReady()) {
-    QCoreApplication::processEvents(QEventLoop::AllEvents, 50);
-}
+Let the incubator run for a while (normally by returning control to the event loop),
+then poll it. There are a number of ways to get back to the incubator later. You may
+want to connect to one of the signals sent by \l{QQuickWindow}, or you may want to run
+a \l{QTimer} especially for that. You may also need the object for some specific
+purpose and poll the incubator when that purpose arises.
 
-QObject *object = incubator.object();
+\code
+// Poll the incubator
+if (incubator.isReady()) {
+    QObject *object = incubator.object();
+    // Use created object
+}
 \endcode
 
-Asynchronous incubators are controlled by a QQmlIncubationController that is
-set on the QQmlEngine, which lets the engine know when the application is idle and
+Asynchronous incubators are controlled by a \l{QQmlIncubationController} that is
+set on the \l{QQmlEngine}, which lets the engine know when the application is idle and
 incubating objects should be processed.  If an incubation controller is not set on the
-QQmlEngine, QQmlIncubator creates objects synchronously regardless of the
-specified IncubationMode.
+\l{QQmlEngine}, \l{QQmlIncubator} creates objects synchronously regardless of the
+specified IncubationMode. By default, no incubation controller is set. However,
+\l{QQuickView}, \l{QQuickWindow} and \l{QQuickWidget} all set incubation controllers
+on their respective \l{QQmlEngine}s. These incubation controllers space out incubations
+across multiple frames while the view is being rendered.
 
 QQmlIncubator supports three incubation modes:
 \list