Document what QtTest's various loggers do

Provide basic (internal) documentation of each logging class and link
the command-line documentation to pages relevant to the formats not
defined by Qt.

Change-Id: I3251dd1304203c6ab87dfe1f2dec0e9787ab69f8
Reviewed-by: Tor Arne Vestbø <tor.arne.vestbo@qt.io>

9 files changed, 87 insertions, 10 deletions

diff --git a/src/testlib/doc/src/qttestlib-manual.qdoc b/src/testlib/doc/src/qttestlib-manual.qdoc
index d969cb1e0a..f1fd8a5d1c 100644
--- a/src/testlib/doc/src/qttestlib-manual.qdoc
+++ b/src/testlib/doc/src/qttestlib-manual.qdoc
@@ -258,14 +258,14 @@
     \li \c -lightxml \br
     Outputs results as a stream of XML tags.
     \li \c -junitxml \br
-    Outputs results as an JUnit XML document.
+    Outputs results as an \l{JUnit XML} document.
     \li \c -csv \br
     Outputs results as comma-separated values (CSV). This mode is only suitable for
     benchmarks, since it suppresses normal pass/fail messages.
     \li \c -teamcity \br
-    Outputs results in TeamCity format.
+    Outputs results in \l{TeamCity} format.
     \li \c -tap \br
-    Outputs results in Test Anything Protocol (TAP) format.
+    Outputs results in \l{Test Anything Protocol} (TAP) format.
     \endlist
 
     The first version of the \c -o option may be repeated in order to log
diff --git a/src/testlib/qappletestlogger.cpp b/src/testlib/qappletestlogger.cpp
index 8764e84aed..4de0045af5 100644
--- a/src/testlib/qappletestlogger.cpp
+++ b/src/testlib/qappletestlogger.cpp
@@ -1,6 +1,6 @@
 /****************************************************************************
 **
-** Copyright (C) 2021 The Qt Company Ltd.
+** Copyright (C) 2022 The Qt Company Ltd.
 ** Contact: https://www.qt.io/licensing/
 **
 ** This file is part of the QtTest module of the Qt Toolkit.
@@ -47,6 +47,14 @@ QT_BEGIN_NAMESPACE
 
 using namespace QTestPrivate;
 
+/*! \internal
+    \class QAppleTestLogger
+    \inmodule QtTest
+
+    QAppleTestLogger reports test results through Apple's unified system logging.
+    Results can be viewed in the Console app.
+*/
+
 bool QAppleTestLogger::debugLoggingEnabled()
 {
     // Debug-level messages are only captured in memory when debug logging is
diff --git a/src/testlib/qcsvbenchmarklogger.cpp b/src/testlib/qcsvbenchmarklogger.cpp
index f410ec6e3d..6f4a25d8d2 100644
--- a/src/testlib/qcsvbenchmarklogger.cpp
+++ b/src/testlib/qcsvbenchmarklogger.cpp
@@ -41,6 +41,16 @@
 #include "qtestresult_p.h"
 #include "qbenchmark_p.h"
 
+/*! \internal
+    \class QCsvBenchmarkLogger
+    \inmodule QtTest
+
+    QCsvBenchmarkLogger implements a comma-separated value format for benchmarks.
+
+    This is intended to be suitable for import into spreadsheets.
+    It does not print test failures, debug messages, warnings or any other details.
+*/
+
 QCsvBenchmarkLogger::QCsvBenchmarkLogger(const char *filename)
     : QAbstractTestLogger(filename)
 {
diff --git a/src/testlib/qjunittestlogger.cpp b/src/testlib/qjunittestlogger.cpp
index cea7fa8b14..c185e652c9 100644
--- a/src/testlib/qjunittestlogger.cpp
+++ b/src/testlib/qjunittestlogger.cpp
@@ -1,6 +1,6 @@
 /****************************************************************************
 **
-** Copyright (C) 2021 The Qt Company Ltd.
+** Copyright (C) 2022 The Qt Company Ltd.
 ** Contact: https://www.qt.io/licensing/
 **
 ** This file is part of the QtTest module of the Qt Toolkit.
@@ -57,6 +57,16 @@
 #include <string.h>
 
 QT_BEGIN_NAMESPACE
+/*! \internal
+    \class QJUnitTestLogger
+    \inmodule QtTest
+
+    QJUnitTestLogger implements logging in a JUnit-compatible XML format.
+
+    The \l{JUnit XML} format was originally developed for Java testing.
+    It is supported by \l{Squish Test Center}.
+*/
+// QTBUG-95424 links to further useful documentation.
 
 QJUnitTestLogger::QJUnitTestLogger(const char *filename)
     : QAbstractTestLogger(filename)
diff --git a/src/testlib/qplaintestlogger.cpp b/src/testlib/qplaintestlogger.cpp
index d5296eae79..4e38a2edce 100644
--- a/src/testlib/qplaintestlogger.cpp
+++ b/src/testlib/qplaintestlogger.cpp
@@ -1,6 +1,6 @@
 /****************************************************************************
 **
-** Copyright (C) 2021 The Qt Company Ltd.
+** Copyright (C) 2022 The Qt Company Ltd.
 ** Contact: https://www.qt.io/licensing/
 **
 ** This file is part of the QtTest module of the Qt Toolkit.
@@ -213,6 +213,15 @@ namespace QTest {
     }
 }
 
+/*! \internal
+    \class QPlainTestLogger
+    \inmodule QtTest
+
+    QPlainTestLogger implements basic logging of test results.
+
+    The format is Qt-specific and aims to be be easy to read.
+*/
+
 void QPlainTestLogger::outputMessage(const char *str)
 {
 #if defined(Q_OS_WIN)
diff --git a/src/testlib/qtaptestlogger.cpp b/src/testlib/qtaptestlogger.cpp
index d3795b2bca..77c00f826e 100644
--- a/src/testlib/qtaptestlogger.cpp
+++ b/src/testlib/qtaptestlogger.cpp
@@ -48,6 +48,17 @@
 #endif
 
 QT_BEGIN_NAMESPACE
+/*! \internal
+    \class QTapTestLogger
+    \inmodule QtTest
+
+    QTapTestLogger implements the Test Anything Protocol v13.
+
+    The \l{Test Anything Protocol} (TAP) is a simple plain-text interface
+    between testing code and systems for reporting and analyzing test results.
+
+    \sa QAbstractTestLogger
+*/
 
 QTapTestLogger::QTapTestLogger(const char *filename)
     : QAbstractTestLogger(filename)
@@ -76,7 +87,7 @@ void QTapTestLogger::stopLogging()
 
     QTestCharBuffer testPlanAndStats;
     QTest::qt_asprintf(&testPlanAndStats,
-        "1..%d\n"
+        "1..%d\n" // The plan (last non-diagnostic line)
         "# tests %d\n"
         "# pass %d\n"
         "# fail %d\n",
@@ -265,4 +276,3 @@ void QTapTestLogger::addMessage(MessageTypes type, const QString &message,
 }
 
 QT_END_NAMESPACE
-
diff --git a/src/testlib/qteamcitylogger.cpp b/src/testlib/qteamcitylogger.cpp
index c124d3ef0e..5bd6b4f429 100644
--- a/src/testlib/qteamcitylogger.cpp
+++ b/src/testlib/qteamcitylogger.cpp
@@ -1,6 +1,6 @@
 /****************************************************************************
 **
-** Copyright (C) 2021 The Qt Company Ltd.
+** Copyright (C) 2022 The Qt Company Ltd.
 ** Copyright (C) 2017 Borgar Ovsthus
 ** Contact: https://www.qt.io/licensing/
 **
@@ -99,6 +99,13 @@ namespace QTest {
     }
 }
 
+/*! \internal
+    \class QTeamCityLogger
+    \inmodule QtTest
+
+    QTeamCityLogger implements logging in the \l{TeamCity} format.
+*/
+
 QTeamCityLogger::QTeamCityLogger(const char *filename)
     : QAbstractTestLogger(filename)
 {
diff --git a/src/testlib/qxctestlogger.mm b/src/testlib/qxctestlogger.mm
index a40ee5e643..a19501cfd4 100644
--- a/src/testlib/qxctestlogger.mm
+++ b/src/testlib/qxctestlogger.mm
@@ -46,6 +46,9 @@
 
 #import <XCTest/XCTest.h>
 
+// This XCode logging integration has probably bit-rotted since it was written.
+// It is not even compiled as part of normal builds.
+
 // ---------------------------------------------------------
 
 @interface XCTestProbe (Private)
diff --git a/src/testlib/qxmltestlogger.cpp b/src/testlib/qxmltestlogger.cpp
index 873e29bc2b..da87276f36 100644
--- a/src/testlib/qxmltestlogger.cpp
+++ b/src/testlib/qxmltestlogger.cpp
@@ -1,6 +1,6 @@
 /****************************************************************************
 **
-** Copyright (C) 2021 The Qt Company Ltd.
+** Copyright (C) 2022 The Qt Company Ltd.
 ** Contact: https://www.qt.io/licensing/
 **
 ** This file is part of the QtTest module of the Qt Toolkit.
@@ -101,6 +101,26 @@ namespace QTest {
 
 }
 
+/*! \internal
+    \class QXmlTestLogger
+    \inmodule QtTest
+
+    QXmlTestLogger implements two XML formats specific to Qt.
+
+    The two formats are distinguished by the XmlMode enum.
+*/
+/*! \internal
+    \enum QXmlTestLogger::XmlMode
+
+    This enumerated type selects the type of XML output to produce.
+
+    \value Complete A full self-contained XML document
+    \value Light XML content suitable for embedding in an XML document
+
+    The Complete form wraps the Light form in a <TestCase> element whose name
+    attribute identifies the test class whose private slots are to be run. It
+    also includes the usual <?xml ...> preamble.
+*/
 
 QXmlTestLogger::QXmlTestLogger(XmlMode mode, const char *filename)
     : QAbstractTestLogger(filename), xmlmode(mode)