Document shell-friendly data tags as best practice

Also follow this best practice in testlib's own documentation and
examples.

Change-Id: I8b57dfa8f88835adae8fceeb122a16635708e338
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
(cherry picked from commit f94f1653368bf8c499fa9a6eeba81736bb2a7710)
Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>

examples/qtestlib/tutorial2/testqstring.cpp

@@ -20,9 +20,9 @@ void TestQString::toUpper_data()
     QTest::addColumn<QString>("string");
     QTest::addColumn<QString>("result");
 
-    QTest::newRow("all lower") << "hello" << "HELLO";
+    QTest::newRow("all-lower") << "hello" << "HELLO";
     QTest::newRow("mixed")     << "Hello" << "HELLO";
-    QTest::newRow("all upper") << "HELLO" << "HELLO";
+    QTest::newRow("all-upper") << "HELLO" << "HELLO";
 }
 //! [1]
 

examples/qtestlib/tutorial4/testgui.cpp

@@ -28,7 +28,7 @@ void TestGui::testGui_data()
     QTestEventList list2;
     list2.addKeyClick('a');
     list2.addKeyClick(Qt::Key_Backspace);
-    QTest::newRow("there and back again") << list2 << "";
+    QTest::newRow("there+back-again") << list2 << "";
 }
 //! [1]
 

examples/qtestlib/tutorial5/benchmarking.cpp

@@ -33,8 +33,8 @@ void TestBenchmark::simple()
 void TestBenchmark::multiple_data()
 {
     QTest::addColumn<bool>("useLocaleCompare");
-    QTest::newRow("locale aware compare") << true;
+    QTest::newRow("locale-aware-compare") << true;
-    QTest::newRow("standard compare") << false;
+    QTest::newRow("standard-compare") << false;
 }
 //! [1]
 
@@ -66,9 +66,8 @@ void TestBenchmark::series_data()
     QTest::addColumn<int>("stringSize");
 
     for (int i = 1; i < 10000; i += 2000) {
-        QByteArray size = QByteArray::number(i);
+        QTest::addRow("locale-aware-compare:%d", i) << true << i;
-        QTest::newRow(("locale aware compare--" + size).constData()) << true << i;
+        QTest::addRow("standard-compare:%d", i) << false << i;
-        QTest::newRow(("standard compare--" + size).constData()) << false << i;
     }
 }
 //! [4]

src/testlib/doc/snippets/code/doc_src_qtestlib.qdoc

@@ -54,9 +54,9 @@ Totals: 3 passed, 0 failed, 0 skipped
 ********* Start testing of TestQString *********
 Config: Using QtTest library %VERSION%, Qt %VERSION%
 PASS   : TestQString::initTestCase()
-PASS   : TestQString::toUpper(all lower)
+PASS   : TestQString::toUpper(all-lower)
 PASS   : TestQString::toUpper(mixed)
-PASS   : TestQString::toUpper(all upper)
+PASS   : TestQString::toUpper(all-upper)
 PASS   : TestQString::cleanupTestCase()
 Totals: 5 passed, 0 failed, 0 skipped, 0 blacklisted, 0ms
 ********* Finished testing of TestQString *********
@@ -77,7 +77,7 @@ Totals: 3 passed, 0 failed, 0 skipped, 0 blacklisted, 20ms
 Config: Using QtTest library %VERSION%, Qt %VERSION%
 PASS   : TestGui::initTestCase()
 PASS   : TestGui::testGui(char)
-PASS   : TestGui::testGui(there and back again)
+PASS   : TestGui::testGui(there+back-again)
 PASS   : TestGui::cleanupTestCase()
 Totals: 4 passed, 0 failed, 0 skipped, 0 blacklisted, 18ms
 ********* Finished testing of TestGui *********
@@ -90,12 +90,12 @@ PASS   : TestBenchmark::initTestCase()
 PASS   : TestBenchmark::simple()
 RESULT : TestBenchmark::simple():
      0.00030 msecs per iteration (total: 79, iterations: 262144)
-PASS   : TestBenchmark::multiple(locale aware compare)
+PASS   : TestBenchmark::multiple(locale-aware-compare)
-RESULT : TestBenchmark::multiple():"locale aware compare":
+RESULT : TestBenchmark::multiple():"locale-aware-compare":
      0.00029 msecs per iteration (total: 78, iterations: 262144)
 .....
-PASS   : TestBenchmark::series(locale aware compare--8001)
+PASS   : TestBenchmark::series(locale-aware-compare:8001)
-RESULT : TestBenchmark::series():"locale aware compare--8001":
+RESULT : TestBenchmark::series():"locale-aware-compare:8001":
      0.039 msecs per iteration (total: 81, iterations: 2048)
 Totals: 15 passed, 0 failed, 0 skipped, 0 blacklisted, 3971ms
 ********* Finished testing of TestBenchmark *********

src/testlib/doc/snippets/code/doc_src_qtqskip.cpp

@@ -13,8 +13,8 @@ void tst_Skip::test_data()
 {
 //! [1]
     QTest::addColumn<bool>("bool");
-    QTest::newRow("local 1") << false;
+    QTest::newRow("local.1") << false;
-    QTest::newRow("local 2") << true;
+    QTest::newRow("local.2") << true;
 
     QSKIP("skipping all");
 //! [1]

src/testlib/doc/snippets/code/src_qtestlib_qtestcase.cpp

@@ -56,8 +56,8 @@ void TestQString::toInt_data()
     QTest::addColumn<QString>("aString");
     QTest::addColumn<int>("expected");
 
-    QTest::newRow("positive value") << "42" << 42;
+    QTest::newRow("positive+value") << "42" << 42;
-    QTest::newRow("negative value") << "-42" << -42;
+    QTest::newRow("negative-value") << "-42" << -42;
     QTest::newRow("zero") << "0" << 0;
 }
 //! [3]
@@ -135,8 +135,8 @@ dir.mkdir("");
 void MyTestClass::addSingleStringRows()
 {
     QTest::addColumn<QString>("aString");
-    QTest::newRow("just hello") << QString("hello");
+    QTest::newRow("just.hello") << QString("hello");
-    QTest::newRow("a null string") << QString();
+    QTest::newRow("a.null.string") << QString();
 }
 //! [20]
 

src/testlib/doc/src/qttest-best-practices.qdoc

@@ -108,7 +108,11 @@
     Do not simply number the test-case, or use bug-tracking identifiers. Someone
     reading the test output will have no idea what the numbers or identifiers
     mean. You can add a comment on the test-row that mentions the bug-tracking
-    identifier, when relevant.
+    identifier, when relevant. It's best to avoid spacing characters and
+    characters that may be significant to command-line shells on which you may
+    want to run tests. This makes it easier to specify the test and tag on \l{Qt
+    Test Command Line Arguments}{the command-line} to your test program - for
+    example, to limit a test run to just one test-case.
 
     \section2 Write Self-contained Test Functions
 

src/testlib/doc/src/qttestlib-manual.qdoc

@@ -671,7 +671,7 @@
         \li result
     \row
         \li 0
-        \li all lower
+        \li all-lower
         \li "hello"
         \li HELLO
     \row
@@ -681,7 +681,7 @@
         \li HELLO
     \row
         \li 2
-        \li all upper
+        \li all-upper
         \li "HELLO"
         \li HELLO
     \endtable