QQuickImageProvider: Improve documentation about cancel() and finished()

Makes it a little more obvious how best to use this. We could do with
including some snippets showing how to ideally implement cancel() I
think, but this is a good start.

Change-Id: I88d63a451239f91aa3619ccb74e306a2052a6e70
Task-number: QTBUG-59485
Reviewed-by: Albert Astals Cid <albert.astals@canonical.com>
Reviewed-by: Pasi Petäjäjärvi <pasi.petajajarvi@qt.io>

1 files changed, 12 insertions, 2 deletions

diff --git a/src/quick/util/qquickimageprovider.cpp b/src/quick/util/qquickimageprovider.cpp
index a026abe762..0ceed7f681 100644
--- a/src/quick/util/qquickimageprovider.cpp
+++ b/src/quick/util/qquickimageprovider.cpp
@@ -183,7 +183,12 @@ QString QQuickImageResponse::errorString() const
 
     It may be reimplemented to cancel a request in the provider side, however, it is not mandatory.
 
-    A cancelled QQuickImageResponse still needs to emit finished().
+    A cancelled QQuickImageResponse still needs to emit finished() so that the
+    engine may clean up the QQuickImageResponse.
+
+    \note finished() should not be emitted until the response is complete,
+    regardless of whether or not cancel() was called. If it is called prematurely,
+    the engine may destroy the response while it is still active, leading to a crash.
 */
 void QQuickImageResponse::cancel()
 {
@@ -192,7 +197,12 @@ void QQuickImageResponse::cancel()
 /*!
     \fn void QQuickImageResponse::finished()
 
-    Signals that the job execution has finished (be it successfully, because an error happened or because it was cancelled).
+    Signals that the job execution has finished (be it successfully, because an
+    error happened or because it was cancelled).
+
+    \note Emission of this signal must be the final action the response performs:
+    once the signal is received, the response will subsequently be destroyed by
+    the engine.
  */
 
 /*!