Doc: update QDebug documentation to talk about the escaping

Task-number: QTBUG-47316
Change-Id: Ib306f8f647014b399b87ffff13f303badb2a7a63
Reviewed-by: Martin Smith <martin.smith@digia.com>
Reviewed-by: Lars Knoll <lars.knoll@theqtcompany.com>

1 files changed, 95 insertions, 8 deletions

diff --git a/src/corelib/io/qdebug.cpp b/src/corelib/io/qdebug.cpp
index 8eeac26d3b..30086b2dac 100644
--- a/src/corelib/io/qdebug.cpp
+++ b/src/corelib/io/qdebug.cpp
@@ -425,6 +425,9 @@ QDebug &QDebug::resetFormat()
     Disables automatic insertion of quotation characters around QChar, QString and QByteArray
     contents and returns a reference to the stream.
 
+    When quoting is disabled, these types are printed without quotation
+    characters and without escaping of non-printable characters.
+
     \sa quote(), maybeQuote()
 */
 
@@ -444,7 +447,11 @@ QDebug &QDebug::resetFormat()
     \fn QDebug &QDebug::operator<<(QChar t)
 
     Writes the character, \a t, to the stream and returns a reference to the
-    stream.
+    stream. Normally, QDebug prints control characters and non-US-ASCII
+    characters as their C escape sequences or their Unicode value (\\u1234). To
+    print non-printable characters without transformation, enable the noquote()
+    functionality, but note that some QDebug backends may not be 8-bit clean
+    and may not be able to represent \c t.
 */
 
 /*!
@@ -535,34 +542,114 @@ QDebug &QDebug::resetFormat()
     \fn QDebug &QDebug::operator<<(const char *s)
 
     Writes the '\\0'-terminated string, \a s, to the stream and returns a
-    reference to the stream.
+    reference to the stream. The string is never quoted nor transformed to the
+    output, but note that some QDebug backends might not be 8-bit clean.
 */
 
 /*!
     \fn QDebug &QDebug::operator<<(const QString &s)
 
-    Writes the string, \a s, to the stream and returns a reference to the stream.
+    Writes the string, \a s, to the stream and returns a reference to the
+    stream. Normally, QDebug prints the string inside quotes and transforms
+    non-printable characters to their Unicode values (\\u1234).
+
+    To print non-printable characters without transformation, enable the
+    noquote() functionality. Note that some QDebug backends might not be 8-bit
+    clean.
+
+    Output examples:
+    \code
+        QString s;
+
+        s = "a";
+        qDebug().noquote() << s;    // prints: a
+        qDebug() << s;              // prints: "a"
+
+        s = "\"a\r\n\"";
+        qDebug() << s;              // prints: "\"a\r\n\""
+
+        s = "\033";                 // escape character
+        qDebug() << s;              // prints: "\u001B"
+
+        s = "\u00AD";               // SOFT HYPHEN
+        qDebug() << s;              // prints: "\u00AD"
+
+        s = "\u00E1";               // LATIN SMALL LETTER A WITH ACUTE
+        qDebug() << s;              // prints: "á"
+
+        s = "a\u0301";              // "a" followed by COMBINING ACUTE ACCENT
+        qDebug() << s;              // prints: "á";
+
+        s = "\u0430\u0301";         // CYRILLIC SMALL LETTER A followed by COMBINING ACUTE ACCENT
+        qDebug() << s;              // prints: "а́"
+    \endcode
 */
 
 /*!
     \fn QDebug &QDebug::operator<<(const QStringRef &s)
 
-    Writes the string reference, \a s, to the stream and returns a reference to
-    the stream.
+    Writes the string, \a s, to the stream and returns a reference to the
+    stream. Normally, QDebug prints the string inside quotes and transforms
+    non-printable characters to their Unicode values (\\u1234).
+
+    To print non-printable characters without transformation, enable the
+    noquote() functionality. Note that some QDebug backends might not be 8-bit
+    clean.
+
+    See the QString overload for examples.
 */
 
 /*!
     \fn QDebug &QDebug::operator<<(QLatin1String s)
 
-    Writes the Latin1-encoded string, \a s, to the stream and returns a reference
-    to the stream.
+    Writes the string, \a s, to the stream and returns a reference to the
+    stream. Normally, QDebug prints the string inside quotes and transforms
+    non-printable characters to their Unicode values (\\u1234).
+
+    To print non-printable characters without transformation, enable the
+    noquote() functionality. Note that some QDebug backends might not be 8-bit
+    clean.
+
+    See the QString overload for examples.
 */
 
 /*!
     \fn QDebug &QDebug::operator<<(const QByteArray &b)
 
     Writes the byte array, \a b, to the stream and returns a reference to the
-    stream.
+    stream. Normally, QDebug prints the array inside quotes and transforms
+    control or non-US-ASCII characters to their C escape sequences (\\xAB). This
+    way, the output is always 7-bit clean and the string can be copied from the
+    output and pasted back into C++ sources, if necessary.
+
+    To print non-printable characters without transformation, enable the
+    noquote() functionality. Note that some QDebug backends might not be 8-bit
+    clean.
+
+    Output examples:
+    \code
+        QByteArray ba;
+
+        ba = "a";
+        qDebug().noquote() << ba;    // prints: a
+        qDebug() << ba;              // prints: "a"
+
+        ba = "\"a\r\n\"";
+        qDebug() << ba;              // prints: "\"a\r\n\""
+
+        ba = "\033";                 // escape character
+        qDebug() << ba;              // prints: "\x1B"
+
+        ba = "\xC3\xA1";
+        qDebug() << ba;              // prints: "\xC3\xA1"
+
+        ba = QByteArray("a\0b", 3);
+        qDebug() << ba               // prints: "\a\x00""b"
+    \endcode
+
+    Note how QDebug needed to close and reopen the string in the way C and C++
+    languages concatenate string literals so that the letter 'b' is not
+    interpreted as part of the previous hexadecimal escape sequence.
 */
 
 /*!