Changes (and minor corrections) to QByteArray documentation.

- Note in operator+= and append() that QByteArray preallocates, meaning that
  appending data in typical cases does not suffer from allocation overhead.

- Note that in the best case, appending or prepending can be O(1) thanks to
  copy-on-write semantics.

  Also make it clear that if the shared data is later changed, a full data copy
  is performed. This was only previously noted in the constructor.

- Note that in the worst case, the data copy requires linear time.

- Also a slight readability change: 'and that takes' vs 'taking'.

1 files changed, 29 insertions, 12 deletions

diff --git a/src/corelib/tools/qbytearray.cpp b/src/corelib/tools/qbytearray.cpp
index a5cb16a..41ca942 100644
--- a/src/corelib/tools/qbytearray.cpp
+++ b/src/corelib/tools/qbytearray.cpp
@@ -850,7 +850,7 @@ QByteArray::Data QByteArray::shared_empty = { Q_BASIC_ATOMIC_INITIALIZER(1),
     This operation takes \l{constant time}, because QByteArray is
     \l{implicitly shared}. This makes returning a QByteArray from a
     function very fast. If a shared instance is modified, it will be
-    copied (copy-on-write), and that takes \l{linear time}.
+    copied (copy-on-write), taking \l{linear time}.
 
     \sa operator=()
 */
@@ -1186,10 +1186,18 @@ void QByteArray::chop(int n)
     Example:
     \snippet doc/src/snippets/code/src_corelib_tools_qbytearray.cpp 12
 
-    This operation is typically very fast (\l{constant time}),
-    because QByteArray preallocates extra space at the end of the
-    character data so it can grow without reallocating the entire
-    data each time.
+    Note: QByteArray is an \l{implicitly shared} class. Consequently,
+    if \e this is an empty QByteArray, then \e this will just share
+    the data held in \a ba. In this case, no copying of data is done,
+    taking \l{constant time}. If a shared instance is modified, it will
+    be copied (copy-on-write), taking \l{linear time}.
+
+    If \e this is not an empty QByteArray, a deep copy of the data is
+    performed, taking \l{linear time}.
+
+    This operation typically does not suffer from allocation overhead,
+    because QByteArray preallocates extra space at the end of the data
+    so that it may grow without reallocating for each append operation.
 
     \sa append(), prepend()
 */
@@ -1474,7 +1482,12 @@ QByteArray QByteArray::nulTerminated() const
 
     Note: QByteArray is an \l{implicitly shared} class. Consequently,
     if \e this is an empty QByteArray, then \e this will just share
-    the data held in \a ba. In this case, no copying of data is done.
+    the data held in \a ba. In this case, no copying of data is done,
+    taking \l{constant time}. If a shared instance is modified, it will
+    be copied (copy-on-write), taking \l{linear time}.
+
+    If \e this is not an empty QByteArray, a deep copy of the data is
+    performed, taking \l{linear time}.
 
     \sa append(), insert()
 */
@@ -1547,14 +1560,18 @@ QByteArray &QByteArray::prepend(char ch)
 
     This is the same as insert(size(), \a ba).
 
-    This operation is typically very fast (\l{constant time}),
-    because QByteArray preallocates extra space at the end of the
-    character data so it can grow without reallocating the entire
-    data each time.
-
     Note: QByteArray is an \l{implicitly shared} class. Consequently,
     if \e this is an empty QByteArray, then \e this will just share
-    the data held in \a ba. In this case, no copying of data is done.
+    the data held in \a ba. In this case, no copying of data is done,
+    taking \l{constant time}. If a shared instance is modified, it will
+    be copied (copy-on-write), taking \l{linear time}.
+
+    If \e this is not an empty QByteArray, a deep copy of the data is
+    performed, taking \l{linear time}.
+
+    This operation typically does not suffer from allocation overhead,
+    because QByteArray preallocates extra space at the end of the data
+    so that it may grow without reallocating for each append operation.
 
     \sa operator+=(), prepend(), insert()
 */