From cfb717d654b92dcfde94cddc7039abeafe67f289 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Thorbj=C3=B8rn=20Martsum?= <tmartsum@gmail.com>
Date: Thu, 26 Sep 2013 15:48:41 +0200
Subject: [PATCH] QList - fix a few doc issues

Though some of it was mensioned in the introduction to the class,
we are not in O(1) if we modify a shared container.

Change-Id: If63b4cb4bdfc98d6b1333bae307e5650341e5484
Reviewed-by: Sze Howe Koh <szehowe.koh@gmail.com>
Reviewed-by: Thiago Macieira <thiago.macieira@intel.com>
---
 src/corelib/tools/qlist.cpp | 24 ++++++++++++++----------
 1 file changed, 14 insertions(+), 10 deletions(-)

diff --git a/src/corelib/tools/qlist.cpp b/src/corelib/tools/qlist.cpp
index 5bced19404..d8ccf2cc43 100644
--- a/src/corelib/tools/qlist.cpp
+++ b/src/corelib/tools/qlist.cpp
@@ -647,7 +647,10 @@ void **QListData::erase(void **xi)
     \a i must be a valid index position in the list (i.e., 0 <= \a i <
     size()).
 
-    This function is very fast (\l{constant time}).
+    If this function is called on a list that is currently being shared, it
+    will trigger a copy of all elements. Otherwise, this function runs in
+    \l{constant time}. If you do not want to modify the list you should use
+    QList::at().
 
     \sa at(), value()
 */
@@ -656,7 +659,7 @@ void **QListData::erase(void **xi)
 
     \overload
 
-    Same as at().
+    Same as at(). This function runs in \l{constant time}.
 */
 
 /*! \fn QList::reserve(int alloc)
@@ -681,10 +684,10 @@ void **QListData::erase(void **xi)
 
     This is the same as list.insert(size(), \a value).
 
-    This operation is typically very fast (\l{constant time}),
-    because QList preallocates extra space on both sides of its
-    internal buffer to allow for fast growth at both ends of the
-    list.
+    If this list is not shared, this operation is typically
+    very fast (amortized \l{constant time}), because QList
+    preallocates extra space on both sides of its internal
+    buffer to allow for fast growth at both ends of the list.
 
     \sa operator<<(), prepend(), insert()
 */
@@ -709,8 +712,9 @@ void **QListData::erase(void **xi)
 
     This is the same as list.insert(0, \a value).
 
-    This operation is usually very fast (\l{constant time}), because
-    QList preallocates extra space on both sides of its internal
+    If this list is not shared, this operation is typically
+    very fast (amortized \l{constant time}), because QList
+    preallocates extra space on both sides of its internal
     buffer to allow for fast growth at both ends of the list.
 
     \sa append(), insert()
@@ -802,7 +806,7 @@ void **QListData::erase(void **xi)
     same as takeAt(0). This function assumes the list is not empty. To
     avoid failure, call isEmpty() before calling this function.
 
-    This operation takes \l{constant time}.
+    If this list is not shared, this operation takes \l{constant time}.
 
     If you don't use the return value, removeFirst() is more
     efficient.
@@ -817,7 +821,7 @@ void **QListData::erase(void **xi)
     not empty. To avoid failure, call isEmpty() before calling this
     function.
 
-    This operation takes \l{constant time}.
+    If this list is not shared, this operation takes \l{constant time}.
 
     If you don't use the return value, removeLast() is more
     efficient.