Improve documentation of BLACKLIST file format.

In particular, make sure the word BLACKLIST appears in it so it can
actually be *found*.  Mention the comment format, mention version
suffixes, mention negation; expand and clarify the description.
Break it up into paragraphs for ease of reading.

Corrected the example to use osx, not its old platform name.  Gave it
a comment that I wish I'd found in the BLACKLIST file that obliged me
to come looking for this in the first place.  Illustrated the use of
comments to document reasons for ignoring tests.

Change-Id: I78d49b4706c0f70b714f7a410f850fb42ebb77c0
Reviewed-by: Lars Knoll <lars.knoll@theqtcompany.com>
Reviewed-by: Timur Pocheptsov <timur.pocheptsov@theqtcompany.com>
Reviewed-by: Jędrzej Nowacki <jedrzej.nowacki@theqtcompany.com>

1 files changed, 32 insertions, 15 deletions

diff --git a/src/testlib/qtestblacklist.cpp b/src/testlib/qtestblacklist.cpp
index 9300cb58af..9dfd5065ad 100644
--- a/src/testlib/qtestblacklist.cpp
+++ b/src/testlib/qtestblacklist.cpp
@@ -46,21 +46,38 @@
 QT_BEGIN_NAMESPACE
 
 /*
- The file format is simply a grouped listing of keywords
- Ungrouped entries at the beginning apply to the whole testcase
- Groups define testfunctions or specific test data to ignore.
- After the groups come a list of entries (one per line) that define
- for which platform/os combination to ignore the test result.
- All keys in a single line have to match to blacklist the test.
-
- mac
- [testFunction]
- linux
- windows 64bit
- [testfunction2:testData]
- msvc
-
- The known keys are listed below:
+  The BLACKLIST file format is a grouped listing of keywords.
+
+  Blank lines and lines starting with # are simply ignored.  An initial #-line
+  referring to this documentation is kind to readers.  Comments can also be used
+  to indicate the reasons for ignoring particular cases.
+
+  A key names a platform, O/S, distribution, tool-chain or architecture; a !
+  prefix reverses what it checks.  A version, joined to a key (at present, only
+  for distributions and for msvc) with a hyphen, limits the key to the specific
+  version.  A keyword line matches if every key on it applies to the present
+  run.  Successive lines are alternate conditions for ignoring a test.
+
+  Ungrouped lines at the beginning of a file apply to the whole testcase.
+  A group starts with a [square-bracketed] identification of a test function,
+  optionally with (after a colon, the name of) a specific data set, to ignore.
+  Subsequent lines give conditions for ignoring this test.
+
+        # See qtbase/src/testlib/qtestblacklist.cpp for format
+        osx
+
+        # QTBUG-12345
+        [testFunction]
+        linux
+        windows 64bit
+
+        # Needs basic C++11 support
+        [testfunction2:testData]
+        msvc-2010
+
+  Keys are lower-case.  Distribution name and version are supported if
+  QSysInfo's productType() and productVersion() return them.
+  The other known keys are listed below:
 */
 
 static QSet<QByteArray> keywords()