QString/doc: correct the record on const char* optimizations

This portion of the documentation was there since the Qt 4.5 import of
the repository and may have been correct at the time. They haven't been
for some time and definitely aren't now. So be clear that even if there
are overloads, some of them are bad ideas.

Change-Id: I810d70e579eb4e2c8e45fffd1719adefb6f9f3bf
Reviewed-by: Volker Hilsheimer <volker.hilsheimer@qt.io>
(cherry picked from commit d46eeffe83db56aea7703d20351dde2969bf372a)
Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>

2 files changed, 11 insertions, 2 deletions

diff --git a/src/corelib/doc/snippets/code/src_corelib_text_qstring.cpp b/src/corelib/doc/snippets/code/src_corelib_text_qstring.cpp
index fe44bee4a8..4f7831d642 100644
--- a/src/corelib/doc/snippets/code/src_corelib_text_qstring.cpp
+++ b/src/corelib/doc/snippets/code/src_corelib_text_qstring.cpp
@@ -75,6 +75,9 @@ if (str == QString("auto") || str == QString("extern")
 }
 //! [4]
 
+//! [4bis]
+str.append("Hello ").append("World");
+//! [4bis]
 
 //! [5]
 if (str == QLatin1String("auto")
diff --git a/src/corelib/text/qstring.cpp b/src/corelib/text/qstring.cpp
index a9d3b3fe8b..dd7b72aab1 100644
--- a/src/corelib/text/qstring.cpp
+++ b/src/corelib/text/qstring.cpp
@@ -9004,8 +9004,8 @@ QString &QString::setRawData(const QChar *unicode, qsizetype size)
     \c{const char *} instead of QString. This includes the copy
     constructor, the assignment operator, the comparison operators,
     and various other functions such as \l{QString::insert()}{insert()},
-    \l{QString::replace()}{replace()}, and \l{QString::indexOf()}{indexOf()}.
-    These functions are usually optimized to avoid constructing a
+    \l{QString::append()}{append()}, and \l{QString::prepend()}{prepend()}.
+    Some of these functions are optimized to avoid constructing a
     QString object for the \c{const char *} data. For example,
     assuming \c str is a QString,
 
@@ -9018,6 +9018,12 @@ QString &QString::setRawData(const QChar *unicode, qsizetype size)
     because it doesn't construct four temporary QString objects and
     make a deep copy of the character data.
 
+    However, that is not true for all QString member functions that take
+    \c{const char *} and therefore applications should assume a temporary will
+    be created, such as in
+
+    \snippet code/src_corelib_text_qstring.cpp 4bis
+
     Applications that define \l QT_NO_CAST_FROM_ASCII (as explained
     in the QString documentation) don't have access to QString's
     \c{const char *} API. To provide an efficient way of specifying