Doc: Recommend putting QML files in the same directory as their modules

Otherwise things quickly get messy.

Pick-to: 6.5
Task-number: QTBUG-106929
Change-Id: I9426f3ad3766cad5b133e8ef063696873bb9b7c9
Reviewed-by: Fabian Kosmale <fabian.kosmale@qt.io>

3 files changed, 24 insertions, 5 deletions

diff --git a/src/qml/doc/src/qmllanguageref/syntax/directoryimports.qdoc b/src/qml/doc/src/qmllanguageref/syntax/directoryimports.qdoc
index 06cc5e13e1..f653ba452b 100644
--- a/src/qml/doc/src/qmllanguageref/syntax/directoryimports.qdoc
+++ b/src/qml/doc/src/qmllanguageref/syntax/directoryimports.qdoc
@@ -85,15 +85,29 @@ as an installed module is imported with a unique identifier string rather than
 a file system path.
 
 
+\section1 The Implicit Import
+
+The directory a QML document resides in is automatically imported. You do
+not have to explicitly import \c{"."} or similar.
+
+\note You should make sure that the qmldir file that specifies the module a QML
+document belongs to resides in the same directory as the QML document itself.
+Otherwise the implicit import is different from the module the document belongs
+to. Then, for example, another QML document may be a singleton in the context of
+the module, but not a singleton in the context of the implicit import. This is a
+frequent source of mistakes.
+
+
 \section1 Remotely Located Directories
 
 A directory of QML files can also be imported from a remote location if the
 directory contains a directory listing \c qmldir file.
 
-\note This also holds for the implicit import of the directory a QML document
-resides in. If your QML documents are loaded from a remote location, you need
-to add qmldir files even if they don't contain any explicit directory import
-statements. Otherwise your QML documents won't see each other.
+\note This also holds for the \l{The Implicit Import}{implicit import} of the
+directory a QML document resides in. If your QML documents are loaded from a
+remote location, you need to add qmldir files even if they don't contain any
+explicit directory import statements. Otherwise your QML documents won't see
+each other.
 
 For example, if the \c myapp directory in the previous example was hosted at
 "http://www.my-example-server.com", and the \c mycomponents directory
diff --git a/src/qml/qml/qqml.cpp b/src/qml/qml/qqml.cpp
index c752adc5a0..6140a532f1 100644
--- a/src/qml/qml/qqml.cpp
+++ b/src/qml/qml/qqml.cpp
@@ -261,7 +261,7 @@ static QTypeRevision resolveModuleVersion(int moduleMajor)
 
 /*!
  * \relates QQmlEngine
- * Registers an implicit import for module \a uri of major version \a moduleMajor.
+ * Registers a qmldir-import for module \a uri of major version \a moduleMajor.
  *
  * This has the same effect as an \c import statement in a qmldir file: Whenever
  * \a uri of version \a moduleMajor is imported, \a import of version
diff --git a/src/quick/doc/src/guidelines/qtquick-bestpractices.qdoc b/src/quick/doc/src/guidelines/qtquick-bestpractices.qdoc
index 2e2fc05aac..3fd2a12ef5 100644
--- a/src/quick/doc/src/guidelines/qtquick-bestpractices.qdoc
+++ b/src/quick/doc/src/guidelines/qtquick-bestpractices.qdoc
@@ -88,6 +88,11 @@ qt_add_qml_module(my_module
 
 All QML files listed under \c {QML_FILES} will automatically get compiled \l {Ahead-of-Time Compilation}{ahead of time}.
 
+You should keep the QML files in the same directory as the CMakeLists.txt with
+the qt_add_qml_module. Otherwise their \l{The Implicit Import}{implicit imports}
+will be different from the \l{QML Modules} they belong to. This is a frequent
+source of mistakes.
+
 \section2 Related Information
 \list
  \li \l{The Qt Resource System}