Doc: Promote use of ECMAScript modules over Qt.include()

Also, mention that Qt.include() is deprecated.

[ChangeLog][QtQml] Qt.include() is deprecated in favor of ECMAScript
modules.

Task-number: QTBUG-74068
Change-Id: Ia13e4f1577d86b869a9a1cd810a82ff0b27ea0cc
Reviewed-by: Simon Hausmann <simon.hausmann@qt.io>

4 files changed, 40 insertions, 33 deletions

diff --git a/src/qml/doc/snippets/qml/integrating-javascript/includejs/app.qml b/src/qml/doc/snippets/qml/integrating-javascript/includejs/app.qml
index 5339fcddce..e2104f8740 100644
--- a/src/qml/doc/snippets/qml/integrating-javascript/includejs/app.qml
+++ b/src/qml/doc/snippets/qml/integrating-javascript/includejs/app.qml
@@ -49,7 +49,7 @@
 ****************************************************************************/
 //![0]
 import QtQuick 2.0
-import "script.js" as MyScript
+import "script.mjs" as MyScript
 
 Item {
     width: 100; height: 100
diff --git a/src/qml/doc/snippets/qml/integrating-javascript/includejs/factorial.js b/src/qml/doc/snippets/qml/integrating-javascript/includejs/factorial.mjs
index f2e31265e3..d0a09b68ad 100644
--- a/src/qml/doc/snippets/qml/integrating-javascript/includejs/factorial.js
+++ b/src/qml/doc/snippets/qml/integrating-javascript/includejs/factorial.mjs
@@ -48,8 +48,8 @@
 **
 ****************************************************************************/
 //![0]
-// factorial.js
-function factorial(a) {
+// factorial.mjs
+export function factorial(a) {
     a = parseInt(a);
     if (a <= 0)
         return 1;
diff --git a/src/qml/doc/snippets/qml/integrating-javascript/includejs/script.js b/src/qml/doc/snippets/qml/integrating-javascript/includejs/script.mjs
index c44b39abda..ef7688693d 100644
--- a/src/qml/doc/snippets/qml/integrating-javascript/includejs/script.js
+++ b/src/qml/doc/snippets/qml/integrating-javascript/includejs/script.mjs
@@ -49,7 +49,7 @@
 ****************************************************************************/
 //![0]
 // script.js
-Qt.include("factorial.js")
+import { factorial } from "factorial.mjs"
 
 function showCalculations(value) {
     console.log(
diff --git a/src/qml/doc/src/javascript/imports.qdoc b/src/qml/doc/src/javascript/imports.qdoc
index 7da2cd22fe..974f2e154f 100644
--- a/src/qml/doc/src/javascript/imports.qdoc
+++ b/src/qml/doc/src/javascript/imports.qdoc
@@ -99,9 +99,44 @@ A JavaScript resource may import another in the following fashion:
 \endcode
 For example:
 \code
-.import "factorial.js" as MathFunctions
+import * as MathFunctions from "factorial.mjs";
 \endcode
 
+The latter is standard ECMAScript syntax for importing ECMAScript modules, and
+only works from within ECMAScript modules as denoted by the \c mjs file
+extension. The former is an extension to JavaScript provided by the \c QML
+engine and will work also with non-modules.
+
+When a JavaScript file is imported this way, it is imported with a qualifier.
+The functions in that file are then accessible from the importing script via the
+qualifier (that is, as \tt{Qualifier.functionName(params)}).
+
+Sometimes it is desirable to have the functions made available in the importing
+context without needing to qualify them. In this case ECMAScript modules and the
+JavaScript \c import statement should be used without the \c as qualifier.
+
+For example, the QML code below left calls \c showCalculations() in \c script.mjs,
+which in turn can call \c factorial() in \c factorial.mjs, as it has included
+\c factorial.mjs using \c import.
+
+\table
+\row
+\li {1,2} \snippet qml/integrating-javascript/includejs/app.qml 0
+\li \snippet qml/integrating-javascript/includejs/script.mjs 0
+\row
+\li \snippet qml/integrating-javascript/includejs/factorial.mjs 0
+\endtable
+
+The \l{QtQml::Qt::include()} {Qt.include()} function includes one JavaScript
+file from another without using ECMAScript modules and without qualifying the
+import. It makes all functions and variables from the other file available in
+the current file's namespace, but ignores all pragmas and imports defined in
+that file. This is not a good idea as a function call should never modify the
+caller's context.
+
+\l{QtQml::Qt::include()} {Qt.include()} is deprecated and should be avoided. It
+will be removed in a future version of Qt.
+
 \section2 Importing a QML Module from a JavaScript Resource
 
 A JavaScript resource may import a QML module in the following fashion:
@@ -119,32 +154,4 @@ via a singleton type; see qmlRegisterSingletonType() for more information.
 
 \note The .import syntax doesn't work for scripts used in the \l {WorkerScript}
 
-\section1 Including a JavaScript Resource from Another JavaScript Resource
-
-When a JavaScript file is imported, it must be imported with a qualifier.  The
-functions in that file are then accessible from the importing script via the
-qualifier (that is, as \tt{Qualifier.functionName(params)}).  Sometimes it is
-desirable to have the functions made available in the importing context without
-needing to qualify them, and in this circumstance the \l{QtQml::Qt::include()}
-{Qt.include()} function may be used to include one JavaScript file from another.
-This copies all functions from the other file into the current file's
-namespace, but ignores all pragmas and imports defined in that file.
-
-For example, the QML code below left calls \c showCalculations() in \c script.js,
-which in turn can call \c factorial() in \c factorial.js, as it has included
-\c factorial.js using \l {QtQml::Qt::include()}{Qt.include()}.
-
-\table
-\row
-\li {1,2} \snippet qml/integrating-javascript/includejs/app.qml 0
-\li \snippet qml/integrating-javascript/includejs/script.js 0
-\row
-\li \snippet qml/integrating-javascript/includejs/factorial.js 0
-\endtable
-
-Notice that calling \l {QtQml::Qt::include()}{Qt.include()} copies all functions
-from \c factorial.js into the \c MyScript namespace, which means the QML
-component can also access \c factorial() directly as \c MyScript.factorial().
-
-
 */