Provide some more documentation for modules in QJSEngine

A little example goes a long way :)

Change-Id: I5aaac011e5a3e1348d7a084b669ec66349d441fa
Reviewed-by: Mitch Curtis <mitch.curtis@qt.io>
Reviewed-by: Paul Wicking <paul.wicking@qt.io>

1 files changed, 39 insertions, 0 deletions

diff --git a/src/qml/jsapi/qjsengine.cpp b/src/qml/jsapi/qjsengine.cpp
index d20f7eb97c..f96414ea3f 100644
--- a/src/qml/jsapi/qjsengine.cpp
+++ b/src/qml/jsapi/qjsengine.cpp
@@ -115,6 +115,45 @@ Q_DECLARE_METATYPE(QList<int>)
   argument is a general-purpose string that is stored in the \c Error
   object for debugging purposes.
 
+  For larger pieces of functionality, you may want to encapsulate
+  your code and data into modules. A module is a file that contains
+  script code, variables, etc., and uses export statements to describe
+  its interface towards the rest of the application. With the help of
+  import statements, a module can refer to functionality from other modules.
+  This allows building a scripted application from smaller connected building blocks
+  in a safe way. In contrast, the approach of using evaluate() carries the risk
+  that internal variables or functions from one evaluate() call accidentally pollute the
+  global object and affect subsequent evaluations.
+
+  The following example provides a module that can add numbers:
+
+  \code
+  export function sum(left, right)
+  {
+      return left + right
+  }
+  \endcode
+
+  This module can be loaded with QJSEngine::import() if it is saved under
+  the name \c{math.mjs}:
+
+  \code
+  QJSvalue module = myEngine.importModule("./math.mjs");
+  QJSValue sumFunction = module.property("sum");
+  QJSValue result = sumFunction.call(args);
+  \endcode
+
+  Modules can also use functionality from other modules using import
+  statements:
+
+  \code
+  import { sum } from "./math.mjs";
+  export function addTwice(left, right)
+  {
+      return sum(left, right) * 2;
+  }
+  \endcode
+
   \section1 Engine Configuration
 
   The globalObject() function returns the \b {Global Object}