QStringConverter: clarify decode()/encode() API docs

These methods return a struct which is implicitly convertible to
QString/QByteArray respectively. Don't hide the return type from QDoc,
this simplifies telling users what those methods return exactly.

Fixes: QTBUG-117705
Change-Id: Ibb22a1e54fffce8f5f20aaabe47983870ccfba1e
Reviewed-by: Thiago Macieira <thiago.macieira@intel.com>
(cherry picked from commit 9e5df4ae5344374eaae0cbdaa526d4dd49ed3a13)
Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>
(cherry picked from commit bab635fea519447e9cadb2ed0039fb73ae3365d2)

3 files changed, 39 insertions, 24 deletions

diff --git a/src/corelib/doc/snippets/code/src_corelib_text_qstringconverter.cpp b/src/corelib/doc/snippets/code/src_corelib_text_qstringconverter.cpp
index e7bd39c95c..b5bfc9cd55 100644
--- a/src/corelib/doc/snippets/code/src_corelib_text_qstringconverter.cpp
+++ b/src/corelib/doc/snippets/code/src_corelib_text_qstringconverter.cpp
@@ -34,3 +34,27 @@ while (new_data_available()) {
     encoded += fromUtf16(chunk);
 }
 //! [3]
+
+{
+//! [4]
+QByteArray encodedString = "...";
+auto toUtf16 = QStringDecoder(QStringDecoder::Utf8);
+auto data = toUtf16(encodedString); // data's type is QStringDecoder::EncodedData<const QByteArray &>
+QString string = toUtf16(encodedString); // Implicit conversion to QString
+
+// Here you have to cast "data" to QString
+auto func = [&]() { return !toUtf16.hasError() ? QString(data) : u"foo"_s; }
+//! [4]
+}
+
+{
+//! [5]
+QString string = "...";
+auto fromUtf16 = QStringEncoder(QStringEncoder::Utf8);
+auto data = fromUtf16(string); // data's type is QStringEncoder::DecodedData<const QString &>
+QByteArray encodedString = fromUtf16(string); // Implicit conversion to QByteArray
+
+// Here you have to cast "data" to QByteArray
+auto func = [&]() { return !fromUtf16.hasError() ? QByteArray(data) : "foo"_ba; }
+//! [5]
+}
diff --git a/src/corelib/text/qstringconverter.cpp b/src/corelib/text/qstringconverter.cpp
index 91d38fd0b5..55a4dd5f59 100644
--- a/src/corelib/text/qstringconverter.cpp
+++ b/src/corelib/text/qstringconverter.cpp
@@ -2268,12 +2268,14 @@ const char *QStringConverter::nameForEncoding(QStringConverter::Encoding e)
 */
 
 /*!
-    \fn QByteArray QStringEncoder::encode(const QString &in)
-    \fn QByteArray QStringEncoder::encode(QStringView in)
-    \fn QByteArray QStringEncoder::operator()(const QString &in)
-    \fn QByteArray QStringEncoder::operator()(QStringView in)
+    \fn QStringEncoder::DecodedData<const QString &> QStringEncoder::encode(const QString &in)
+    \fn QStringEncoder::DecodedData<QStringView> QStringEncoder::encode(QStringView in)
+    \fn QStringEncoder::DecodedData<const QString &> QStringEncoder::operator()(const QString &in)
+    \fn QStringEncoder::DecodedData<QStringView> QStringEncoder::operator()(QStringView in)
 
-    Converts \a in and returns the data as a byte array.
+    Converts \a in and returns a struct that is implicitly convertible to QByteArray.
+
+    \snippet code/src_corelib_text_qstringconverter.cpp 5
 */
 
 /*!
@@ -2357,12 +2359,15 @@ const char *QStringConverter::nameForEncoding(QStringConverter::Encoding e)
 */
 
 /*!
-    \fn QString QStringDecoder::operator()(const QByteArray &ba)
-    \fn QString QStringDecoder::decode(const QByteArray &ba)
-    \fn QString QStringDecoder::operator()(QByteArrayView ba)
-    \fn QString QStringDecoder::decode(QByteArrayView ba)
+    \fn QStringDecoder::EncodedData<const QByteArray &> QStringDecoder::operator()(const QByteArray &ba)
+    \fn QStringDecoder::EncodedData<const QByteArray &> QStringDecoder::decode(const QByteArray &ba)
+    \fn QStringDecoder::EncodedData<QByteArrayView> QStringDecoder::operator()(QByteArrayView ba)
+    \fn QStringDecoder::EncodedData<QByteArrayView> QStringDecoder::decode(QByteArrayView ba)
+
+    Converts \a ba and returns a struct that is implicitly convertible to QString.
+
 
-    Converts \a ba and returns the data as a QString.
+    \snippet code/src_corelib_text_qstringconverter.cpp 4
 */
 
 /*!
diff --git a/src/corelib/text/qstringconverter.h b/src/corelib/text/qstringconverter.h
index a61973ca17..1e9141c008 100644
--- a/src/corelib/text/qstringconverter.h
+++ b/src/corelib/text/qstringconverter.h
@@ -34,12 +34,6 @@ public:
         : QStringConverter(name, flags)
     {}
 
-#if defined(Q_QDOC)
-    QByteArray operator()(const QString &in);
-    QByteArray operator()(QStringView in);
-    QByteArray encode(const QString &in);
-    QByteArray encode(QStringView in);
-#else
     template<typename T>
     struct DecodedData
     {
@@ -57,7 +51,6 @@ public:
     { return DecodedData<const QString &>{this, str}; }
     DecodedData<QStringView> encode(QStringView in)
     { return DecodedData<QStringView>{this, in}; }
-#endif
 
     qsizetype requiredSpace(qsizetype inputLength) const
     { return iface ? iface->fromUtf16Len(inputLength) : 0; }
@@ -103,12 +96,6 @@ public:
         : QStringConverter(name, f)
     {}
 
-#if defined(Q_QDOC)
-    QString operator()(const QByteArray &ba);
-    QString operator()(QByteArrayView ba);
-    QString decode(const QByteArray &ba);
-    QString decode(QByteArrayView ba);
-#else
     template<typename T>
     struct EncodedData
     {
@@ -126,7 +113,6 @@ public:
     { return EncodedData<const QByteArray &>{this, ba}; }
     EncodedData<QByteArrayView> decode(QByteArrayView ba)
     { return EncodedData<QByteArrayView>{this, ba}; }
-#endif
 
     qsizetype requiredSpace(qsizetype inputLength) const
     { return iface ? iface->toUtf16Len(inputLength) : 0; }