Doc: explain how QXmlStream{Reader,Writer} deal with encoding in QString

QXmlStreamWriter does not: it just writes the QString inputs to the
output.

QXmlStreamReader does: it first converts the QString to UTF-8 and stores
locally. Then it tries to decode using the XML encoding header.

Change-Id: I39332e0a867442d58082fffd1503d7652cb9fbff
Reviewed-by: Martin Smith <martin.smith@qt.io>

1 files changed, 20 insertions, 0 deletions

diff --git a/src/corelib/serialization/qxmlstream.cpp b/src/corelib/serialization/qxmlstream.cpp
index 9b5295a17e..a92dd71df5 100644
--- a/src/corelib/serialization/qxmlstream.cpp
+++ b/src/corelib/serialization/qxmlstream.cpp
@@ -409,6 +409,11 @@ QXmlStreamReader::QXmlStreamReader(const QByteArray &data)
 /*!
   Creates a new stream reader that reads from \a data.
 
+  This function should only be used if the XML header either says the encoding
+  is "UTF-8" or lacks any encoding information (the latter is the case of
+  QXmlStreamWriter writing to a QString). Any other encoding is likely going to
+  cause data corruption ("mojibake").
+
   \sa addData(), clear(), setDevice()
  */
 QXmlStreamReader::QXmlStreamReader(const QString &data)
@@ -3268,6 +3273,9 @@ QXmlStreamWriter::QXmlStreamWriter(QByteArray *array)
 
 
 /*!  Constructs a stream writer that writes into \a string.
+ *
+ * Note that when writing to QString, QXmlStreamWriter ignores the codec set
+ * with setCodec(). See that function for more information.
  */
 QXmlStreamWriter::QXmlStreamWriter(QString *string)
     : d_ptr(new QXmlStreamWriterPrivate(this))
@@ -3326,6 +3334,12 @@ QIODevice *QXmlStreamWriter::device() const
     gets written when you call writeStartDocument(). Call this
     function before calling writeStartDocument().
 
+    \note When writing the XML to a QString, the codec information is ignored
+    and the XML header will not include any encoding information, since all
+    QStrings are UTF-16. If you later convert the QString to an 8-bit format,
+    you must arrange for the encoding information to be transmitted
+    out-of-band.
+
     \sa codec()
 */
 void QXmlStreamWriter::setCodec(QTextCodec *codec)
@@ -3345,6 +3359,12 @@ void QXmlStreamWriter::setCodec(QTextCodec *codec)
     "ISO 8859-1", "UTF-8", and "UTF-16". If the encoding isn't
     recognized, nothing happens.
 
+    \note When writing the XML to a QString, the codec information is ignored
+    and the XML header will not include any encoding information, since all
+    QStrings are UTF-16. If you later convert the QString to an 8-bit format,
+    you must arrange for the encoding information to be transmitted
+    out-of-band.
+
     \sa QTextCodec::codecForName()
 */
 void QXmlStreamWriter::setCodec(const char *codecName)