From 9e5df4ae5344374eaae0cbdaa526d4dd49ed3a13 Mon Sep 17 00:00:00 2001
From: Ahmad Samir <a.samirh78@gmail.com>
Date: Thu, 5 Oct 2023 17:28:35 +0300
Subject: [PATCH] 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
Pick-to: 6.6 6.5
Change-Id: Ibb22a1e54fffce8f5f20aaabe47983870ccfba1e
Reviewed-by: Thiago Macieira <thiago.macieira@intel.com>
---
 .../src_corelib_text_qstringconverter.cpp     | 24 ++++++++++++++++++
 src/corelib/text/qstringconverter.cpp         | 25 +++++++++++--------
 src/corelib/text/qstringconverter.h           | 14 -----------
 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 075f39b07d..293c0b5208 100644
--- a/src/corelib/text/qstringconverter.cpp
+++ b/src/corelib/text/qstringconverter.cpp
@@ -2313,12 +2313,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
 */
 
 /*!
@@ -2402,12 +2404,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 the data as a QString.
+    Converts \a ba and returns a struct that is implicitly convertible to QString.
+
+
+    \snippet code/src_corelib_text_qstringconverter.cpp 4
 */
 
 /*!
diff --git a/src/corelib/text/qstringconverter.h b/src/corelib/text/qstringconverter.h
index 148501288c..055019836a 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; }