QStringBuilder: document issues with using "auto" keyword

Cleanup QStringBuilder API docs.

Task-number: QTBUG-104354
Change-Id: I00029c8f4bfdf35869396ac14d7d9ba0da34cdb5
Reviewed-by: Thiago Macieira <thiago.macieira@intel.com>

src/corelib/doc/snippets/qstring/stringbuilder.cpp

@@ -1,6 +1,8 @@
 // Copyright (C) 2016 The Qt Company Ltd.
 // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause
 
+#include <QString>
+
 using namespace Qt::StringLiterals;
 
 //! [0]
@@ -25,3 +27,24 @@ using namespace Qt::StringLiterals;
     QLatin1StringView world("world");
     QString message =  hello % el % world % QChar('!');
 //! [5]
+
+//! [6]
+    QString str("QStringBuilder");
+
+    // "s" type is deduced as QStringBuilder
+    auto s = "Like hot glue, " % str % " concatenates strings";
+
+    // Similarly the return type of this lambda is deduced as QStringBuilder
+    auto concatenateStr = []() {
+        return "Like hot glue, " % str % " concatenates strings";
+    };
+//! [6]
+
+//! [7]
+    QString s = "Like hot glue, " % str % " concatenates strings";
+
+    // With a lambda, specify a trailing return type
+    auto concatenateStr = []() -> QString {
+        return "Like hot glue, " % str % " concatenates strings";
+    };
+//! [7]

src/corelib/text/qstring.cpp

@@ -2039,7 +2039,7 @@ void qtWarnAboutInvalidRegularExpression(const QString &pattern, const char *whe
 
     Many strings are known at compile time. But the trivial
     constructor QString("Hello"), will copy the contents of the string,
-    treating the contents as Latin-1. To avoid this one can use the
+    treating the contents as Latin-1. To avoid this, one can use the
     QStringLiteral macro to directly create the required data at compile
     time. Constructing a QString out of the literal does then not cause
     any overhead at runtime.
@@ -2093,14 +2093,21 @@ void qtWarnAboutInvalidRegularExpression(const QString &pattern, const char *whe
 
     \snippet qstring/stringbuilder.cpp 5
 
-    A more global approach which is the most convenient but
-    not entirely source compatible, is to this define in your
-    .pro file:
+    A more global approach, which is more convenient but not entirely source
+    compatible, is to define \c QT_USE_QSTRINGBUILDER (by adding it to the compiler
+    flags) at build time. This will make concatenating strings with \c{'+'} work the
+    same way as \c{QStringBuilder} \c{'%'}.
 
-    \snippet qstring/stringbuilder.cpp 3
+    \note Take care when using the \c auto keyword with the result of
+    string concatenation using QStringBuilder:
+    \snippet qstring/stringbuilder.cpp 6
 
-    and the \c{'+'} will automatically be performed as the
-    \c{QStringBuilder} \c{'%'} everywhere.
+    Typically this is not what is expected (and can result in undefined behavior).
+    This issue can be fixed by specifying the return type:
+    \snippet qstring/stringbuilder.cpp 7
+
+    \note \l {https://invent.kde.org/sdk/clazy} {Clazy} has a check, auto-unexpected-qstringbuilder,
+    that catches this issue.
 
     \section1 Maximum Size and Out-of-memory Conditions
 

src/corelib/text/qstringbuilder.cpp

@@ -57,36 +57,57 @@ QT_BEGIN_NAMESPACE
     if there are three or more of them, and performs equally well in other
     cases.
 
+    \note Definnig \c QT_USE_STRINGBUILDER at build time (this is the default
+    when building Qt libraries and tools), will make using \c {'+'} when
+    concatenating strings work the same way as \c operator%().
+
     \sa QLatin1StringView, QString
 */
 
-/*! \fn template <typename A, typename B> QStringBuilder<A, B>::QStringBuilder(const A &a, const B &b)
-  Constructs a QStringBuilder from \a a and \a b.
+/*!
+    \internal
+    \fn template <typename A, typename B> QStringBuilder<A, B>::QStringBuilder(const A &a, const B &b)
+
+    Constructs a QStringBuilder from \a a and \a b.
  */
 
-/* \fn template <typename A, typename B> QStringBuilder<A, B>::operator%(const A &a, const B &b)
+/*!
+    \internal
+    \fn template <typename A, typename B> QStringBuilder<A, B>::operator%(const A &a, const B &b)
 
     Returns a \c QStringBuilder object that is converted to a QString object
     when assigned to a variable of QString type or passed to a function that
     takes a QString parameter.
 
-    This function is usable with arguments of type \c QString,
-    \c QLatin1StringView,
-    \c QChar, \c QLatin1Char, and \c char.
+    This function is usable with arguments of any of the following types:
+    \list
+    \li \c QAnyStringView,
+    \li \c QString, \c QStringView
+    \li \c QByteArray, \c QByteArrayView, \c QLatin1StringView
+    \li \c QChar, \c QLatin1Char, \c char, (since 5.10:) \c char16_t
+    \li (since 5.10:) \c{const char16_t[]} (\c{u"foo"}),
+    \endlist
 */
 
-/* \fn template <typename A, typename B> QByteArray QStringBuilder<A, B>::toLatin1() const
-  Returns a Latin-1 representation of the string as a QByteArray.  The
-  returned byte array is undefined if the string contains non-Latin1
-  characters.
- */
-/* \fn template <typename A, typename B> QByteArray QStringBuilder<A, B>::toUtf8() const
-  Returns a UTF-8 representation of the string as a QByteArray.
- */
-
-
 /*!
     \internal
+    \fn template <typename A, typename B> QByteArray QStringBuilder<A, B>::toLatin1() const
+
+    Returns a Latin-1 representation of the string as a QByteArray. It
+    is undefined behavior if the string contains non-Latin1 characters.
+ */
+
+/*!
+    \internal
+    \fn template <typename A, typename B> QByteArray QStringBuilder<A, B>::toUtf8() const
+
+    Returns a UTF-8 representation of the string as a QByteArray.
+ */
+
+/*!
+    \internal
+    Converts the UTF-8 string viewed by \a in to UTF-16 and writes the result
+    to the buffer starting at \a out.
  */
 void QAbstractConcatenable::convertFromUtf8(QByteArrayView in, QChar *&out) noexcept
 {