2 files changed, 23 insertions, 11 deletions
diff --git a/src/corelib/doc/src/containers.qdoc b/src/corelib/doc/src/containers.qdoc
index ff2df9c020..fa26409d83 100644
--- a/src/corelib/doc/src/containers.qdoc
+++ b/src/corelib/doc/src/containers.qdoc
@@ -533,10 +533,18 @@
     This problem doesn't occur with functions that return a const or
     non-const reference to a container.
 
+    \section3 Implicit sharing iterator problem
+
     \l{Implicit sharing} has another consequence on STL-style
-    iterators: You must not take a copy of a container while
-    non-const iterators are active on that container. Java-style
-    iterators don't suffer from that limitation.
+    iterators: you should avoid copying a container while
+    iterators are active on that container. The iterators
+    point to an internal structure, and if you copy a container
+    you should be very careful with your iterators. E.g:
+
+    \snippet code/doc_src_containers.cpp 24
+
+     The above example only shows a problem with QVector, but
+     the problem exists for all the implicitly shared Qt containers.
 
     \keyword foreach
     \section1 The foreach Keyword
diff --git a/src/corelib/doc/src/implicit-sharing.qdoc b/src/corelib/doc/src/implicit-sharing.qdoc
index 814f8140f3..1185fe8348 100644
--- a/src/corelib/doc/src/implicit-sharing.qdoc
+++ b/src/corelib/doc/src/implicit-sharing.qdoc
@@ -89,9 +89,12 @@
     of data. Objects can easily be assigned, sent as function arguments,
     and returned from functions.
 
-    Implicit sharing takes place behind the scenes; the programmer
-    does not need to worry about it. Even in multithreaded
-    applications, implicit sharing takes place, as explained in
+    Implicit sharing mostly takes place behind the scenes;
+    the programmer rarely needs to worry about it. However, Qt's
+    container iterators have different behavior than those from
+    the STL. Read \l{Implicit sharing iterator problem}.
+
+    In multithreaded applications, implicit sharing takes place, as explained in
     \l{Thread-Support in Qt Modules#Threads and Implicitly Shared Classes}
     {Threads and Implicitly Shared Classes}.
 
@@ -105,9 +108,10 @@
     greater than one. (This is often called \e {copy-on-write} or
     \e {value semantics}.)
 
-    An implicitly shared class has total control of its internal data. In
+    An implicitly shared class has control of its internal data. In
     any member functions that modify its data, it automatically detaches
-    before modifying the data.
+    before modifying the data. Notice, however, the special case with
+    container iterators; see \l{Implicit sharing iterator problem}.
 
     The QPen class, which uses implicit sharing, detaches from the shared
     data in all member functions that change the internal data.
@@ -133,9 +137,9 @@
     In this example, \c p1 and \c p2 share data until QPainter::begin()
     is called for \c p2, because painting a pixmap will modify it.
 
-    \warning Do not copy an implicitly shared container (QMap,
-    QVector, etc.) while you are iterating over it using an non-const
-    \l{STL-style iterators}{STL-style iterator}.
+    \warning Be careful with copying an implicitly shared container
+    (QMap, QVector, etc.) while you use
+    \l{STL-style iterators}{STL-style iterator}. See \l{Implicit sharing iterator problem}.
 
     \keyword implicitly shared classes
     \annotatedlist shared