Add documentation for qt_import_qml_plugin()

Change-Id: I1f503cd03c35e48f2219e95db57b153c69badb0b
Reviewed-by: Fabian Kosmale <fabian.kosmale@qt.io>
Reviewed-by: Ulf Hermann <ulf.hermann@qt.io>
Reviewed-by: Alexandru Croitor <alexandru.croitor@qt.io>
(cherry picked from commit 9fdb12bdac0efd9875b2d98ae82c3702cf722469)
Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>

4 files changed, 28 insertions, 68 deletions

diff --git a/src/qml/Qt6QmlMacros.cmake b/src/qml/Qt6QmlMacros.cmake
index d970e5b954..2a8c10fecf 100644
--- a/src/qml/Qt6QmlMacros.cmake
+++ b/src/qml/Qt6QmlMacros.cmake
@@ -1854,7 +1854,7 @@ function(qt6_import_qml_plugins target)
     set_target_properties(${target} PROPERTIES _QT_QML_PLUGINS_IMPORTED TRUE)
 
     set(options)
-    set(oneValueArgs "PATH_TO_SCAN")
+    set(oneValueArgs "PATH_TO_SCAN")   # Internal option, may be removed
     set(multiValueArgs)
 
     cmake_parse_arguments(arg "${options}" "${oneValueArgs}" "${multiValueArgs}" ${ARGN})
diff --git a/src/qml/doc/src/cmake/qt_import_qml_plugins.qdoc b/src/qml/doc/src/cmake/qt_import_qml_plugins.qdoc
index e82b3af7d9..b4d4271266 100644
--- a/src/qml/doc/src/cmake/qt_import_qml_plugins.qdoc
+++ b/src/qml/doc/src/cmake/qt_import_qml_plugins.qdoc
@@ -37,17 +37,39 @@
 \section1 Synopsis
 
 \badcode
-qt_import_qml_plugins(...)
-
+qt_import_qml_plugins(target)
 \endcode
 
 \versionlessCMakeCommandsNote qt6_import_qml_plugins()
 
 \section1 Description
 
-TBD
+\note This command only has any effect if Qt was built statically. If called
+      using a non-static Qt, it will do nothing and return immediately.
+
+\c{qt_import_qml_plugins()} runs \c{qmlimportscanner} on the \c target
+immediately as part of the call. It finds the static QML plugins used by the
+\c target and links it to those plugins so that they are part of the executable
+or shared library that \c target represents. The search follows QML module
+imports recursively.
+
+Because the call to \c{qmlimportscanner} runs at configure time rather than
+generation or build time, \c{qt_import_qml_plugins()} only knows about the
+information recorded on the \c target (or other targets it links or imports)
+at the time \c{qt_import_qml_plugins()} is called. Any linking or import
+relationships added after this call will not be considered. Therefore, this
+command should be called as late as possible in the \c{target}'s directory
+scope so that all the linking and import relationships are known.
+
+If \c target was created using \l{qt6_add_executable}{qt_add_executable()},
+projects would not normally need to call \c{qt_import_qml_plugins()} directly.
+When Qt is built statically, the command is called automatically as part of
+\l{qt6_add_executable#Finalization}{target finalization} if \c target links to
+the Qml library. By default, this finalization occurs at the end of the same
+directory scope in which the \c target was created. If the \c target was
+created using the standard CMake \c{add_executable()} command instead, the
+project needs to call \c{qt_import_qml_plugins()} itself.
 
-\section1 Arguments
+\sa Q_IMPORT_QML_PLUGIN
 
-TBD
 */
diff --git a/src/quick/doc/snippets/cmake-macros/examples.cmake b/src/quick/doc/snippets/cmake-macros/examples.cmake
deleted file mode 100644
index cecc59debc..0000000000
--- a/src/quick/doc/snippets/cmake-macros/examples.cmake
+++ /dev/null
@@ -1,6 +0,0 @@
-#! [qt5_import_qml_plugins]
-find_package(Qt5 COMPONENTS Quick QmlImportScanner)
-add_executable(myapp main.cpp)
-target_link_libraries(myapp Qt5::Quick)
-qt5_import_qml_plugins(myapp)
-#! [qt5_import_qml_plugins]
diff --git a/src/quick/doc/src/cmake-macros.qdoc b/src/quick/doc/src/cmake-macros.qdoc
deleted file mode 100644
index b643a9e4e4..0000000000
--- a/src/quick/doc/src/cmake-macros.qdoc
+++ /dev/null
@@ -1,56 +0,0 @@
-/****************************************************************************
-**
-** Copyright (C) 2019 The Qt Company Ltd.
-** Contact: https://www.qt.io/licensing/
-**
-** This file is part of the documentation of the Qt Toolkit.
-**
-** $QT_BEGIN_LICENSE:FDL$
-** 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.
-**
-** GNU Free Documentation License Usage
-** Alternatively, this file may be used under the terms of the GNU Free
-** Documentation License version 1.3 as published by the Free Software
-** Foundation and appearing in the file included in the packaging of
-** this file. Please review the following information to ensure
-** the GNU Free Documentation License version 1.3 requirements
-** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
-** $QT_END_LICENSE$
-**
-****************************************************************************/
-
-/*!
-\page qtqml-cmake-qt5-import-qml-plugins.html
-\ingroup cmake-macros-qtqml
-
-\title qt5_import_qml_plugins
-
-\brief Scans \c{.qml} files and imports required QML static plugins
-
-\section1 Overview
-
-\badcode
-find_package(Qt5QmlImportScanner REQUIRED)
-qt5_import_qml_plugins(<TARGET>)
-\endcode
-
-\section1 Description
-
-Runs \c{qmlimportscanner} at configure time to find the static QML plugins
-used and links them to the given target.
-
-\note When used with a non-static Qt build, this function does nothing.
-
-This CMake command was introduced in Qt 5.14.
-
-\section1 Example
-
-\snippet cmake-macros/examples.cmake qt5_import_qml_plugins
-
-*/