Document qmltc output format

Make understanding qmltc output easier by showing how it
works on a trivial example. Add a paragraph on the generated
code location as an addition

Fixes: QTBUG-100051
Pick-to: 6.3
Change-Id: I0fa0f2c6c60fef7accbe855159275591d9e8bbc6
Reviewed-by: Fabian Kosmale <fabian.kosmale@qt.io>
Reviewed-by: Ulf Hermann <ulf.hermann@qt.io>

4 files changed, 241 insertions, 12 deletions

diff --git a/src/qml/doc/snippets/qmltc/CMakeLists.txt b/src/qml/doc/snippets/qmltc/CMakeLists.txt
index d4ef2d0fc1..4eb60fce38 100644
--- a/src/qml/doc/snippets/qmltc/CMakeLists.txt
+++ b/src/qml/doc/snippets/qmltc/CMakeLists.txt
@@ -3,6 +3,8 @@ set(application_name tst_qmltc_examples)
 #! [qmltc-app-name]
 # Use "my_qmltc_example" as an application name:
 set(application_name my_qmltc_example)
+
+# Create a CMake target, add C++ source files, link libraries, etc...
 #! [qmltc-app-name]
 ]]
 
@@ -18,17 +20,31 @@ qt_internal_add_test(${application_name}
         Qt::Gui
 )
 
-#! [qmltc-add-qml-module]
-# Create a CMake target, add C++ source files, link libraries, etc...
+#! [qmltc-qml-files]
+# Specify a list of QML files to be compiled:
+set(application_qml_files
+    myApp.qml
+    MyButton.qml
+    MySlider.qml
+)
+#! [qmltc-qml-files]
 
+# files "invisible" to the documentation:
+list(APPEND application_qml_files
+    special/HelloWorld.qml
+)
+target_compile_definitions(${application_name} PRIVATE
+    QT_USE_QSTRINGBUILDER
+    QMLTC_TESTS_SOURCE_DIR="${CMAKE_CURRENT_SOURCE_DIR}"
+    QMLTC_TESTS_BINARY_DIR="${CMAKE_CURRENT_BINARY_DIR}"
+)
+
+#! [qmltc-add-qml-module]
 # Make the application into a proper QML module:
 qt6_add_qml_module(${application_name}
     VERSION 1.0
     URI QmltcExample
-    QML_FILES
-        myApp.qml
-        MyButton.qml
-        MySlider.qml
+    QML_FILES ${application_qml_files}
 )
 #! [qmltc-add-qml-module]
 
@@ -39,9 +55,6 @@ target_link_libraries(${application_name} PRIVATE Qt::QmlPrivate Qt::QuickPrivat
 # Compile qml files (listed in FILES) to C++ using qmltc and add these files to
 # the application binary:
 qt6_target_compile_qml_to_cpp(${application_name}
-    FILES
-        myApp.qml
-        MyButton.qml
-        MySlider.qml
+    FILES ${application_qml_files}
 )
 #! [qmltc-compile-to-cpp]
diff --git a/src/qml/doc/snippets/qmltc/special/HelloWorld.qml b/src/qml/doc/snippets/qmltc/special/HelloWorld.qml
new file mode 100644
index 0000000000..9b85f02dde
--- /dev/null
+++ b/src/qml/doc/snippets/qmltc/special/HelloWorld.qml
@@ -0,0 +1,66 @@
+/****************************************************************************
+**
+** Copyright (C) 2022 The Qt Company Ltd.
+** Contact: https://www.qt.io/licensing/
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:BSD$
+** Commercial License Usage
+** Licensees holding valid commercial Qt licenses may use this file in
+** accordance with the commercial license agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and The Qt Company. For licensing terms
+** and conditions see https://www.qt.io/terms-conditions. For further
+** information use the contact form at https://www.qt.io/contact-us.
+**
+** BSD License Usage
+** Alternatively, you may use this file under the terms of the BSD license
+** as follows:
+**
+** "Redistribution and use in source and binary forms, with or without
+** modification, are permitted provided that the following conditions are
+** met:
+**   * Redistributions of source code must retain the above copyright
+**     notice, this list of conditions and the following disclaimer.
+**   * Redistributions in binary form must reproduce the above copyright
+**     notice, this list of conditions and the following disclaimer in
+**     the documentation and/or other materials provided with the
+**     distribution.
+**   * Neither the name of The Qt Company Ltd nor the names of its
+**     contributors may be used to endorse or promote products derived
+**     from this software without specific prior written permission.
+**
+**
+** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+//! [qmltc-hello-world-qml]
+// HelloWorld.qml
+import QtQml
+
+QtObject {
+    id: me
+    property string hello: "Hello, qmltc!"
+
+    function printHello(prefix: string, suffix: string) {
+        console.log(prefix + me.hello + suffix);
+    }
+
+    signal created()
+    Component.onCompleted: me.created();
+}
+//! [qmltc-hello-world-qml]
diff --git a/src/qml/doc/snippets/qmltc/special/HelloWorld.qml.cpp b/src/qml/doc/snippets/qmltc/special/HelloWorld.qml.cpp
new file mode 100644
index 0000000000..f0a2e7ba39
--- /dev/null
+++ b/src/qml/doc/snippets/qmltc/special/HelloWorld.qml.cpp
@@ -0,0 +1,84 @@
+/****************************************************************************
+**
+** Copyright (C) 2022 The Qt Company Ltd.
+** Contact: https://www.qt.io/licensing/
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:BSD$
+** Commercial License Usage
+** Licensees holding valid commercial Qt licenses may use this file in
+** accordance with the commercial license agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and The Qt Company. For licensing terms
+** and conditions see https://www.qt.io/terms-conditions. For further
+** information use the contact form at https://www.qt.io/contact-us.
+**
+** BSD License Usage
+** Alternatively, you may use this file under the terms of the BSD license
+** as follows:
+**
+** "Redistribution and use in source and binary forms, with or without
+** modification, are permitted provided that the following conditions are
+** met:
+**   * Redistributions of source code must retain the above copyright
+**     notice, this list of conditions and the following disclaimer.
+**   * Redistributions in binary form must reproduce the above copyright
+**     notice, this list of conditions and the following disclaimer in
+**     the documentation and/or other materials provided with the
+**     distribution.
+**   * Neither the name of The Qt Company Ltd nor the names of its
+**     contributors may be used to endorse or promote products derived
+**     from this software without specific prior written permission.
+**
+**
+** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/* Disclaimer: This file is an "as is" copy of the C++ header generated for the
+   accompanying HelloWorld.qml. Its pieces are used to:
+
+   * verify that the generated code is similar to what is contained in this file
+   * provide documentation snippets for the qmltc docs
+
+   Note: all the stuff below MAGIC_QMLTC_TEST_DELIMITER_LINE comment
+   participates in the aforementioned activities. Prefer to put arbitrary stuff
+   before that comment.
+*/
+
+// MAGIC_QMLTC_TEST_DELIMITER_LINE
+
+//! [qmltc-hello-world-generated]
+class HelloWorld : public QObject
+{
+    Q_OBJECT
+    QML_ELEMENT
+    Q_PROPERTY(QString hello WRITE setHello READ hello BINDABLE bindableHello)
+public:
+    HelloWorld(QQmlEngine * engine, QObject * parent = nullptr);
+signals:
+    void created();
+
+public:
+    void setHello(const QString& hello_);
+    QString hello();
+    QBindable<QString> bindableHello();
+
+    Q_INVOKABLE void printHello(QString prefix, QString suffix);
+
+    // ...
+};
+//! [qmltc-hello-world-generated]
diff --git a/src/qml/doc/snippets/qmltc/tst_qmltc_examples.cpp b/src/qml/doc/snippets/qmltc/tst_qmltc_examples.cpp
index 8de430de86..50436dc26f 100644
--- a/src/qml/doc/snippets/qmltc/tst_qmltc_examples.cpp
+++ b/src/qml/doc/snippets/qmltc/tst_qmltc_examples.cpp
@@ -52,10 +52,12 @@
 //       test sources license. This is intentional to comply with default
 //       snippet license.
 
-#include <QtGui/qguiapplication.h>
-#include <QtCore/qtimer.h>
 #include <QtTest/qtest.h>
+#include <QtCore/qstring.h>
+#include <QtCore/qtimer.h>
+#include <QtGui/qguiapplication.h>
 #include <QtQuick/qquickwindow.h>
+
 //! [qqmlcomponent-include]
 #include <QtQml/qqmlcomponent.h>
 //! [qqmlcomponent-include]
@@ -64,6 +66,8 @@
 #include "myapp.h" // include generated C++ header
 //! [qmltc-include]
 
+#include <algorithm>
+
 class tst_qmltc_examples : public QObject
 {
     Q_OBJECT
@@ -77,6 +81,8 @@ public:
 private slots:
     void app();
     void appComponent();
+
+    void helloWorld();
 };
 
 #define CREATE_DUMMY_ARGC_ARGV() \
@@ -147,6 +153,66 @@ void tst_qmltc_examples::appComponent()
     app.exec();
 }
 
+#if !defined(QMLTC_TESTS_SOURCE_DIR) || !defined(QMLTC_TESTS_BINARY_DIR)
+#    error "Tests assume that QMLTC_TESTS_{SOURCE,BINARY}_DIR are specified (through CMake)"
+#endif
+
+// Note: QtTest macros need to be in void-returning function, so use output arg.
+template<typename Predicate>
+void readFileContent(QStringList *content, const QString &url, Predicate filter)
+{
+    QVERIFY(content);
+
+    QFile file(url);
+    QVERIFY(file.exists());
+    QVERIFY(file.open(QIODeviceBase::ReadOnly | QIODeviceBase::Text));
+
+    QTextStream stream(&file);
+    while (!stream.atEnd()) {
+        QString line = stream.readLine();
+        if (filter(line))
+            content->append(std::move(line));
+    }
+}
+
+void tst_qmltc_examples::helloWorld()
+{
+    QStringList generatedCode;
+    readFileContent(&generatedCode,
+                    QStringLiteral(QMLTC_TESTS_BINARY_DIR)
+                            + u"/.qmltc/tst_qmltc_examples/helloworld.h",
+                    [](const QString &) { return true; });
+    if (QTest::currentTestFailed())
+        QFAIL("Reading _generated_ C++ content for special/HelloWorld.qml failed");
+
+    QStringList documentationCode;
+    const auto filterDocumentationLines = [encounteredStart = false](QStringView line) mutable {
+        if (line.startsWith(u"// MAGIC_QMLTC_TEST_DELIMITER_LINE")) {
+            encounteredStart = true;
+            return false; // we don't need this specific line
+        }
+        if (!encounteredStart)
+            return false;
+        line = line.trimmed();
+        return !line.isEmpty() && !line.startsWith(u"//");
+    };
+    readFileContent(&documentationCode,
+                    QStringLiteral(QMLTC_TESTS_SOURCE_DIR) + u"/special/HelloWorld.qml.cpp",
+                    filterDocumentationLines);
+    if (QTest::currentTestFailed())
+        QFAIL("Reading special/HelloWorld.qml.cpp failed");
+
+    QVERIFY(!generatedCode.isEmpty());
+    QVERIFY(!documentationCode.isEmpty());
+
+    auto begin = generatedCode.cbegin();
+    for (const QString &existingString : qAsConst(documentationCode)) {
+        auto pos = std::find(begin, generatedCode.cend(), existingString);
+        QVERIFY2(pos != generatedCode.cend(), qPrintable(u"Could not find: " + existingString));
+        begin = std::next(pos);
+    }
+}
+
 #undef CREATE_DUMMY_ARGC_ARGV
 
 QTEST_APPLESS_MAIN(tst_qmltc_examples)