Improve implicit shared documentation a bit

Task-number: QTBUG-27061

Change-Id: I66e000a9f59fda3654066013e6e78c3ba6fd27fe
Reviewed-by: Mitch Curtis <mitch.curtis@digia.com>
Reviewed-by: Thiago Macieira <thiago.macieira@intel.com>

6 files changed, 61 insertions, 7 deletions

diff --git a/src/corelib/tools/qhash.cpp b/src/corelib/tools/qhash.cpp
index 7f6feaf8a0..f14fac00b8 100644
--- a/src/corelib/tools/qhash.cpp
+++ b/src/corelib/tools/qhash.cpp
@@ -1594,6 +1594,11 @@ void QHashData::checkSanity()
     need to keep iterators over a long period of time, we recommend
     that you use QMap rather than QHash.
 
+    \warning Iterators on implicitly shared containers do not work
+    exactly like STL-iterators. You should avoid copying a container
+    while iterators are active on that container. For more information,
+    read \l{Implicit sharing iterator problem}.
+
     \sa QHash::const_iterator, QMutableHashIterator
 */
 
@@ -1791,6 +1796,11 @@ void QHashData::checkSanity()
     internal data structure. If you need to keep iterators over a long
     period of time, we recommend that you use QMap rather than QHash.
 
+    \warning Iterators on implicitly shared containers do not work
+    exactly like STL-iterators. You should avoid copying a container
+    while iterators are active on that container. For more information,
+    read \l{Implicit sharing iterator problem}.
+
     \sa QHash::iterator, QHashIterator
 */
 
diff --git a/src/corelib/tools/qlinkedlist.cpp b/src/corelib/tools/qlinkedlist.cpp
index 28319f3fda..e967163b8b 100644
--- a/src/corelib/tools/qlinkedlist.cpp
+++ b/src/corelib/tools/qlinkedlist.cpp
@@ -691,9 +691,12 @@ const QLinkedListData QLinkedListData::shared_null = {
     Multiple iterators can be used on the same list. If you add items
     to the list, existing iterators will remain valid. If you remove
     items from the list, iterators that point to the removed items
-    will become dangling iterators. However, because of how \l{implicit
-    sharing} works, you must not take a copy of a container while
-    iterators are active on that container.
+    will become dangling iterators.
+
+    \warning Iterators on implicitly shared containers do not work
+    exactly like STL-iterators. You should avoid copying a container
+    while iterators are active on that container. For more information,
+    read \l{Implicit sharing iterator problem}.
 
     \sa QLinkedList::const_iterator, QMutableLinkedListIterator
 */
@@ -910,6 +913,11 @@ const QLinkedListData QLinkedListData::shared_null = {
     items from the list, iterators that point to the removed items
     will become dangling iterators.
 
+    \warning Iterators on implicitly shared containers do not work
+    exactly like STL-iterators. You should avoid copying a container
+    while iterators are active on that container. For more information,
+    read \l{Implicit sharing iterator problem}.
+
     \sa QLinkedList::iterator, QLinkedListIterator
 */
 
diff --git a/src/corelib/tools/qlist.cpp b/src/corelib/tools/qlist.cpp
index d8ccf2cc43..0811c3793e 100644
--- a/src/corelib/tools/qlist.cpp
+++ b/src/corelib/tools/qlist.cpp
@@ -1292,6 +1292,11 @@ void **QListData::erase(void **xi)
     iterators over a long period of time, we recommend that you use
     QLinkedList rather than QList.
 
+    \warning Iterators on implicitly shared containers do not work
+    exactly like STL-iterators. You should avoid copying a container
+    while iterators are active on that container. For more information,
+    read \l{Implicit sharing iterator problem}.
+
     \sa QList::const_iterator, QMutableListIterator
 */
 
@@ -1542,6 +1547,11 @@ void **QListData::erase(void **xi)
     iterators over a long period of time, we recommend that you use
     QLinkedList rather than QList.
 
+    \warning Iterators on implicitly shared containers do not work
+    exactly like STL-iterators. You should avoid copying a container
+    while iterators are active on that container. For more information,
+    read \l{Implicit sharing iterator problem}.
+
     \sa QList::iterator, QListIterator
 */
 
diff --git a/src/corelib/tools/qmap.cpp b/src/corelib/tools/qmap.cpp
index ab9b1d23ab..4da9669a39 100644
--- a/src/corelib/tools/qmap.cpp
+++ b/src/corelib/tools/qmap.cpp
@@ -1215,6 +1215,11 @@ void QMapDataBase::freeData(QMapDataBase *d)
     items from the map, iterators that point to the removed items
     will become dangling iterators.
 
+    \warning Iterators on implicitly shared containers do not work
+    exactly like STL-iterators. You should avoid copying a container
+    while iterators are active on that container. For more information,
+    read \l{Implicit sharing iterator problem}.
+
     \sa QMap::const_iterator, QMutableMapIterator
 */
 
@@ -1433,6 +1438,11 @@ void QMapDataBase::freeData(QMapDataBase *d)
     items from the map, iterators that point to the removed items
     will become dangling iterators.
 
+    \warning Iterators on implicitly shared containers do not work
+    exactly like STL-iterators. You should avoid copying a container
+    while iterators are active on that container. For more information,
+    read \l{Implicit sharing iterator problem}.
+
     \sa QMap::iterator, QMapIterator
 */
 
diff --git a/src/corelib/tools/qset.qdoc b/src/corelib/tools/qset.qdoc
index a0bc206014..e66a59a09c 100644
--- a/src/corelib/tools/qset.qdoc
+++ b/src/corelib/tools/qset.qdoc
@@ -643,8 +643,12 @@
 
     \snippet code/doc_src_qset.cpp 10
 
-    Multiple iterators can be used on the same set. However, you may
-    not attempt to modify the container while iterating on it.
+    Multiple iterators can be used on the same set.
+
+    \warning Iterators on implicitly shared containers do not work
+    exactly like STL-iterators. You should avoid copying a container
+    while iterators are active on that container. For more information,
+    read \l{Implicit sharing iterator problem}.
 
     \sa QSet::const_iterator, QMutableSetIterator
 */
@@ -682,8 +686,10 @@
 
     \snippet code/doc_src_qset.cpp 12
 
-    Multiple iterators can be used on the same set. However, you may
-    not attempt to modify the container while iterating on it.
+    \warning Iterators on implicitly shared containers do not work
+    exactly like STL-iterators. You should avoid copying a container
+    while iterators are active on that container. For more information,
+    read \l{Implicit sharing iterator problem}.
 
     \sa QSet::iterator, QSetIterator
 */
diff --git a/src/corelib/tools/qvector.cpp b/src/corelib/tools/qvector.cpp
index 11990d30b2..b9281c6915 100644
--- a/src/corelib/tools/qvector.cpp
+++ b/src/corelib/tools/qvector.cpp
@@ -957,6 +957,11 @@
     iterators}. The STL-style non-const iterator is simply a typedef
     for "T *" (pointer to T).
 
+    \warning Iterators on implicitly shared containers do not work
+    exactly like STL-iterators. You should avoid copying a container
+    while iterators are active on that container. For more information,
+    read \l{Implicit sharing iterator problem}.
+
     \sa QVector::begin(), QVector::end(), QVector::const_iterator, QMutableVectorIterator
 */
 
@@ -969,6 +974,11 @@
     iterators}. The STL-style const iterator is simply a typedef for
     "const T *" (pointer to const T).
 
+    \warning Iterators on implicitly shared containers do not work
+    exactly like STL-iterators. You should avoid copying a container
+    while iterators are active on that container. For more information,
+    read \l{Implicit sharing iterator problem}.
+
     \sa QVector::constBegin(), QVector::constEnd(), QVector::iterator, QVectorIterator
 */