Doc: Fix Qt Quick Test documentation

- Add qtquicktest-cppapi.qdoc for the C++ API landing page.
- Add qtquicktest.qdoc for the QQuickTest namespace.
- Add qtquicktest-qmltypes.qdoc for the QML types landing page.
- Add ../../imports/testlib to the sourcedirs variable so that
  the QML files can be found.
- Add a "Reference" section to qtquicktest-index.qdoc that
  has links to the QML and C++ pages.
- Add more targets so that we can reliably link to them
  while keeping the nice short section names.
- Fix minor issues in existing documentation.
- Link to the QML API docs from the C++ API docs.

Change-Id: I5fc3c90105b095d9ea84c3f76e6c7ba0a47c2695
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
Reviewed-by: Paul Wicking <paul.wicking@qt.io>

1 files changed, 16 insertions, 32 deletions

diff --git a/src/qmltest/doc/src/qtquicktest-index.qdoc b/src/qmltest/doc/src/qtquicktest-index.qdoc
index 48b41d4f0a..283e88e2e4 100644
--- a/src/qmltest/doc/src/qtquicktest-index.qdoc
+++ b/src/qmltest/doc/src/qtquicktest-index.qdoc
@@ -30,6 +30,7 @@
     \title Qt Quick Test
     \brief Unit testing framework for QML.
 
+    \target Introduction to Qt Quick Test
     \section1 Introduction
 
     \l {Qt Quick Test QML Types}{Qt Quick Test} is a unit test framework for QML applications.
@@ -62,15 +63,13 @@
           only guaranteed to work with the Qt version it was developed against.
           However, source compatibility is guaranteed.
 
+    \target Running Qt Quick Tests
     \section1 Running Tests
 
     Test cases are launched by a C++ harness that consists of
     the following code:
 
-    \code
-    #include <QtQuickTest/quicktest.h>
-    QUICK_TEST_MAIN(example)
-    \endcode
+    \snippet src_qmltest_qquicktest.cpp 1
 
     Where "example" is the identifier to use to uniquely identify
     this set of tests. Finally, add \c{CONFIG += qmltestcase} to the project
@@ -139,7 +138,7 @@
     \section1 Executing C++ Before QML Tests
 
     To execute C++ code before any of the QML tests are run, the
-    \c QUICK_TEST_MAIN_WITH_SETUP macro can be used. This can be useful for
+    \l QUICK_TEST_MAIN_WITH_SETUP macro can be used. This can be useful for
     setting context properties on the QML engine, amongst other things.
 
     The macro is identical to \l QUICK_TEST_MAIN, except that it takes an
@@ -151,53 +150,31 @@
             \li Name
             \li Purpose
         \row
-            \li void applicationAvailable()
+            \li \c {void applicationAvailable()}
             \li Called right after the QApplication object was instantiated.
                 Use this function to setup everything that is not related
                 to QML directly.
         \row
-            \li void qmlEngineAvailable(QQmlEngine*)
+            \li \c {void qmlEngineAvailable(QQmlEngine *)}
             \li Called when the QML engine is available.
                 Any \l {QQmlEngine::addImportPath}{import paths},
                 \l {QQmlEngine::addPluginPath}{plugin paths},
                 and \l {QQmlFileSelector::setExtraSelectors}{extra file selectors}
                 will have been set on the engine by this point.
         \row
-            \li void cleanupTestCase()
+            \li \c {void cleanupTestCase()}
             \li Called right after the test execution has finished.
                 Use this function to clean up before everything will start to be destructed.
     \endtable
 
-    Each function will be called once for each \c tst_*.qml file, so any
+    Each function will be called once for each \c {tst_*.qml} file, so any
     arguments are unique to that test. For example, this means that each QML
     test file will have its own QML engine.
 
     The following example demonstrates how the macro can be used to set context
     properties on the QML engine:
 
-    \code
-    #include <QtQuickTest>
-    #include <QQmlEngine>
-    #include <QQmlContext>
-
-    class Setup : public QObject
-    {
-        Q_OBJECT
-
-    public:
-        Setup() {}
-
-    public slots:
-        void qmlEngineAvailable(QQmlEngine *engine)
-        {
-            engine->rootContext()->setContextProperty("myContextProperty", QVariant(true));
-        }
-    };
-
-    QUICK_TEST_MAIN_WITH_SETUP(mytest, Setup)
-
-    #include "tst_mytest.moc"
-    \endcode
+    \snippet src_qmltest_qquicktest.cpp 2
 
     The \c .moc include is based on the file name of the \c .cpp file.
     For example, in the example above, the \c .cpp file is named
@@ -208,6 +185,13 @@
     #include "MyTest.moc"
     \endcode
 
+    \section1 Reference
+
+    \list
+      \li \l{Qt Quick Test QML Types}{QML Types}
+      \li \l{Qt Quick Test C++ API}{C++ API}
+    \endlist
+
     \section1 Licenses
 
     Qt Quick Tests is available under commercial licenses from \l{The Qt Company}.