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 7bcae3bf74..42dd082214 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 a044d5628a..efc3e41149 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()
 */