From bac0796308e0cd76519ac76dfe06e7a749c20c0a Mon Sep 17 00:00:00 2001
From: Marc Mutz <marc.mutz@kdab.com>
Date: Tue, 6 Jan 2015 20:59:16 +0100
Subject: [PATCH] QTest: update docs for toString()

Following c61f8df4047a616ffcb5e775fa8e5981b13e193f, we now prefer overloading
toString() in the type's namespace over specializing the primary template.

Let the docs reflect that and add an example. Also suggest to delegate the messy
raw char pointer handling to the existing toString(QString)/toString(QBA)
overloads.

Change-Id: Id76181faba86aea52588611ea64ea9b95371a733
Reviewed-by: Thiago Macieira <thiago.macieira@intel.com>
---
 .../snippets/code/src_qtestlib_qtestcase.cpp    | 13 +++++++++++++
 src/testlib/qtestcase.cpp                       | 17 ++++++++++++++---
 2 files changed, 27 insertions(+), 3 deletions(-)

diff --git a/src/testlib/doc/snippets/code/src_qtestlib_qtestcase.cpp b/src/testlib/doc/snippets/code/src_qtestlib_qtestcase.cpp
index 7bcae3bf742..42dd0822141 100644
--- a/src/testlib/doc/snippets/code/src_qtestlib_qtestcase.cpp
+++ b/src/testlib/doc/snippets/code/src_qtestlib_qtestcase.cpp
@@ -153,6 +153,19 @@ namespace QTest {
 }
 //! [16]
 
+//! [toString-overload]
+namespace MyNamespace {
+    char *toString(const MyPoint &point)
+    {
+        // bring QTest::toString overloads into scope:
+        using QTest::toString;
+        // delegate char* handling to QTest::toString(QByteArray):
+        return toString("MyPoint(" +
+                        QByteArray::number(point.x()) + ", " +
+                        QByteArray::number(point.y()) + ')');
+    }
+}
+//! [toString-overload]
 
 //! [17]
 int i = 0;
diff --git a/src/testlib/qtestcase.cpp b/src/testlib/qtestcase.cpp
index a044d5628a0..efc3e411494 100644
--- a/src/testlib/qtestcase.cpp
+++ b/src/testlib/qtestcase.cpp
@@ -902,14 +902,21 @@ using QtMiscUtils::toHexUpper;
     Returns a textual representation of \a value. This function is used by
     \l QCOMPARE() to output verbose information in case of a test failure.
 
-    You can add specializations of this function to your test to enable
+    You can add specializations or overloads of this function to your test to enable
     verbose output.
 
+    \b {Note:} Starting with Qt 5.5, you should prefer to provide a toString() function
+    in the type's namespace instead of specializing this template.
+    If your code needs to continue to work with the QTestLib from Qt 5.4 or
+    earlier, you need to continue to use specialization.
+
     \b {Note:} The caller of toString() must delete the returned data
     using \c{delete[]}.  Your implementation should return a string
-    created with \c{new[]} or qstrdup().
+    created with \c{new[]} or qstrdup(). The easiest way to do so is to
+    create a QByteArray or QString and calling QTest::toString() on it
+    (see second example below).
 
-    Example:
+    Example for specializing (Qt ≤ 5.4):
 
     \snippet code/src_qtestlib_qtestcase.cpp 16
 
@@ -918,6 +925,10 @@ using QtMiscUtils::toHexUpper;
     MyPoint fails, \l QCOMPARE() will call this function to output the
     contents of \c MyPoint to the test log.
 
+    Same example, but with overloading (Qt ≥ 5.5):
+
+    \snippet code/src_qtestlib_qtestcase.cpp toString-overload
+
     \sa QCOMPARE()
 */