Doc: Update, and reduce duplication of, QThread-related info

Added/Changed:
- Move content from the Thread Basics overview to the QThread class ref
- Rephrase bits for clarity
- Use more links

Removed:
- (threads-basics.qdoc) Warning against moveToThread(this): This usage
  came about when people tried to add slots to a QThread subclass. This
  patch adds a warning against the root cause.
- (threads-basics.qdoc) Note on sleep() et al.: They were made public in
  Qt 5.0.
- (threads-basics.qdoc) The strategy for managing member variables:
  Sounds error-prone. Pushing results through signals is safer.
- (qthread.cpp) The note about GUI classes: Irrelevant to QThread,
  and it's already mentioned elsewhere.

Change-Id: I6bc53cc22b929523f9976d2b920f94c02bd7273e
Reviewed-by: Geir Vattekar <geir.vattekar@digia.com>
Reviewed-by: Olivier Goffart <ogoffart@woboq.com>

2 files changed, 15 insertions, 39 deletions

diff --git a/src/corelib/doc/src/threads-basics.qdoc b/src/corelib/doc/src/threads-basics.qdoc
index e511c10423..4f381421b4 100644
--- a/src/corelib/doc/src/threads-basics.qdoc
+++ b/src/corelib/doc/src/threads-basics.qdoc
@@ -199,31 +199,6 @@
     still important.
     On Linux, Valgrind and Helgrind can help detect threading errors.
 
-    The anatomy of QThread is quite interesting:
-
-    \list
-    \li QThread does not live in the new thread where \l{QThread::}{run()} is
-       executed. It lives in the old thread.
-    \li Most QThread methods are the thread's control interface and are meant to
-       be called from the old thread. Do not move this interface to the newly
-       created thread using \l{QObject::}{moveToThread()}; i.e., calling
-       \l{QObject::moveToThread()}{moveToThread(this)} is regarded as bad
-       practice.
-    \li \l{QThread::}{exec()} and the static methods
-       \l{QThread::}{usleep()}, \l{QThread::}{msleep()},
-       \l{QThread::}{sleep()} are meant to be called from the newly created
-       thread.
-    \li Additional members defined in the QThread subclass are
-       accessible by both threads. The developer is responsible for
-       coordinating access. A typical strategy is to set the members before
-       \l{QThread::}{start()} is called. Once the worker thread is running,
-       the main thread should not touch the additional members anymore. After
-       the worker has terminated, the main thread can access the additional
-       members again. This is a convenient strategy for passing parameters to a
-       thread before it is started as well as for collecting the result once it
-       has terminated.
-    \endlist
-
     \section2 Protecting the Integrity of Data
 
     When writing a multithread application, extra care must be taken to avoid
diff --git a/src/corelib/thread/qthread.cpp b/src/corelib/thread/qthread.cpp
index 7667aff0b2..50ccca9eda 100644
--- a/src/corelib/thread/qthread.cpp
+++ b/src/corelib/thread/qthread.cpp
@@ -204,20 +204,20 @@ QThreadPrivate::~QThreadPrivate()
     There will not be any event loop running in the thread unless you call
     exec().
 
-    It is important to remember that a QThread object usually lives
-    in the thread where it was created, not in the thread that it
-    manages. This oft-overlooked detail means that a QThread's slots
-    will be executed in the context of its home thread, not in the
-    context of the thread it is managing. For this reason,
-    implementing new slots in a QThread subclass is error-prone and
-    discouraged.
+    It is important to remember that a QThread instance \l{QObject#Thread
+    Affinity}{lives in} the old thread that instantiated it, not in the
+    new thread that calls run(). This means that all of QThread's queued
+    slots will execute in the old thread. Thus, a developer who wishes to
+    invoke slots in the new thread must use the worker-object approach; new
+    slots should not be implemented directly into a subclassed QThread.
 
-    \note If you interact with an object, using any technique other
-    than queued signal/slot connections (e.g. direct function calls),
-    then the usual multithreading precautions need to be taken.
+    When subclassing QThread, keep in mind that the constructor executes in
+    the old thread while run() executes in the new thread. If a member
+    variable is accessed from both functions, then the variable is accessed
+    from two different threads. Check that it is safe to do so.
 
-    \note It is not possible to change the thread affinity of GUI
-    objects; they must remain in the main thread.
+    \note Care must be taken when interacting with objects across different
+    threads. See \l{Synchronizing Threads} for details.
 
     \section1 Managing threads
 
@@ -262,7 +262,7 @@ QThreadPrivate::~QThreadPrivate()
     \l{Mandelbrot Example}, as that is the name of the QThread subclass).
     Note that this is currently not available with release builds on Windows.
 
-    \sa {Thread Support in Qt}, QThreadStorage, QMutex, QSemaphore, QWaitCondition,
+    \sa {Thread Support in Qt}, QThreadStorage, {Synchronizing Threads}
         {Mandelbrot Example}, {Semaphores Example}, {Wait Conditions Example}
 */
 
@@ -489,7 +489,8 @@ uint QThread::stackSize() const
     that was passed to exit(). The value returned is 0 if exit() is called via
     quit().
 
-    It is necessary to call this function to start event handling.
+    This function is meant to be called from within run(). It is necessary to
+    call this function to start event handling.
 
     \sa quit(), exit()
 */