Doc: QtTest - Fix documentation for TestCase and SignalSpy

The property/methods documentation needs to be available in the
components qml file. Thus we now import those components from the
qml files directly instead of using fake header files.

Rename the Qt Quick Test page to Qt Quick Test Qml Types to be
consistent with the other submodules.

Task-number: QTBUG-33587

Change-Id: Ifb1df8e7d15f2e23b4b4268e5df138934e62fc42
Reviewed-by: Topi Reiniö <topi.reinio@digia.com>
Reviewed-by: Sze Howe Koh <szehowe.koh@gmail.com>
Reviewed-by: Martin Smith <martin.smith@digia.com>
Reviewed-by: Alan Alpert <aalpert@blackberry.com>

1 files changed, 129 insertions, 0 deletions

diff --git a/src/imports/testlib/SignalSpy.qml b/src/imports/testlib/SignalSpy.qml
index 5b05778c5d..8318f156a0 100644
--- a/src/imports/testlib/SignalSpy.qml
+++ b/src/imports/testlib/SignalSpy.qml
@@ -42,6 +42,43 @@
 import QtQuick 2.0
 import QtTest 1.0
 
+/*!
+    \qmltype SignalSpy
+    \inqmlmodule QtTest
+    \brief Enables introspection of signal emission
+    \since 4.8
+    \ingroup qtquicktest
+
+    In the following example, a SignalSpy is installed to watch the
+    "clicked" signal on a user-defined Button type.  When the signal
+    is emitted, the \l count property on the spy will be increased.
+
+    \code
+    Button {
+        id: button
+        SignalSpy {
+            id: spy
+            target: button
+            signalName: "clicked"
+        }
+        TestCase {
+            name: "ButtonClick"
+            function test_click() {
+                compare(spy.count, 0)
+                button.clicked();
+                compare(spy.count, 1)
+            }
+        }
+    }
+    \endcode
+
+    The above style of test is suitable for signals that are emitted
+    synchronously.  For asynchronous signals, the wait() method can be
+    used to block the test until the signal occurs (or a timeout expires).
+
+    \sa {QtTest::TestCase}{TestCase}, {Qt Quick Test Reference Documentation}
+*/
+
 Item {
     id: spy
     visible: false
@@ -50,18 +87,101 @@ Item {
         id: util
     }
     // Public API.
+    /*!
+        \qmlproperty object SignalSpy::target
+
+        This property defines the target object that will be used to
+        listen for emissions of the \l signalName signal.
+
+        \sa signalName, count
+    */
     property var target: null
+    /*!
+        \qmlproperty string SignalSpy::signalName
+
+        This property defines the name of the signal on \l target to
+        listen for.
+
+        \sa target, count
+    */
     property string signalName: ""
+    /*!
+        \qmlproperty int SignalSpy::count
+
+        This property defines the number of times that \l signalName has
+        been emitted from \l target since the last call to clear().
+
+        \sa target, signalName, clear()
+        \readonly
+    */
     readonly property alias count: spy.qtest_count
+    /*!
+        \qmlproperty bool SignalSpy::valid
+
+        This property defines the current signal connection status. It will be true when the \l signalName of the \l target is connected successfully, otherwise it will be false.
+
+        \sa count, target, signalName, clear()
+        \readonly
+    */
     readonly property alias valid:spy.qtest_valid
+    /*!
+        \qmlproperty list SignalSpy::signalArguments
+
+        This property holds a list of emitted signal arguments. Each emission of the signal will append one item to the list, containing the arguments of the signal.
+        When connecting to a new \l target or new \l signalName or calling the \l clear() method, the \l signalArguments will be reset to empty.
+
+        \sa signalName, clear()
+        \readonly
+    */
     readonly property alias signalArguments:spy.qtest_signalArguments
 
+    /*!
+        \qmlmethod SignalSpy::clear()
+
+        Clears \l count to 0, resets \l valid to false and clears the \l signalArguments to empty.
+
+        \sa count, wait()
+    */
     function clear() {
         qtest_count = 0
         qtest_expectedCount = 0
         qtest_signalArguments = []
     }
 
+    /*!
+        \qmlmethod SignalSpy::wait(timeout = 5000)
+
+        Waits for the signal \l signalName on \l target to be emitted,
+        for up to \a timeout milliseconds.  The test case will fail if
+        the signal is not emitted.
+
+        \code
+        SignalSpy {
+            id: spy
+            target: button
+            signalName: "clicked"
+        }
+
+        function test_async_click() {
+            ...
+            // do something that will cause clicked() to be emitted
+            ...
+            spy.wait()
+            compare(spy.count, 1)
+        }
+        \endcode
+
+        There are two possible scenarios: the signal has already been
+        emitted when wait() is called, or the signal has not yet been
+        emitted.  The wait() function handles the first scenario by immediately
+        returning if the signal has already occurred.
+
+        The clear() method can be used to discard information about signals
+        that have already occurred to synchronize wait() with future signal
+        emissions.
+
+        \sa clear(), TestCase::tryCompare()
+    */
     function wait(timeout) {
         if (timeout === undefined)
             timeout = 5000
@@ -87,13 +207,21 @@ Item {
         qtest_update()
     }
 
+    /*! \internal */
     property var qtest_prevTarget: null
+    /*! \internal */
     property string qtest_prevSignalName: ""
+    /*! \internal */
     property int qtest_expectedCount: 0
+    /*! \internal */
     property var qtest_signalArguments:[]
+    /*! \internal */
     property int qtest_count: 0
+    /*! \internal */
     property bool qtest_valid:false
+    /*! \internal */
 
+    /*! \internal */
     function qtest_update() {
         if (qtest_prevTarget != null) {
             var prevFunc = qtest_prevTarget[qtest_prevSignalName]
@@ -119,6 +247,7 @@ Item {
         }
     }
 
+    /*! \internal */
     function qtest_activated() {
         ++qtest_count
         spy.qtest_signalArguments[spy.qtest_signalArguments.length] = arguments