Improve documentation for JavaScript expressions and imports

This commit splits the import documentation out of the expression
documentation, and corrects various ambiguities or errors in the
JavaScript-related documentation.

Change-Id: I351b0676f7271efba7cbff90c133dfe008321fb8
Reviewed-by: Michael Brasser <michael.brasser@nokia.com>

1 files changed, 155 insertions, 0 deletions

diff --git a/src/qml/doc/src/javascript/imports.qdoc b/src/qml/doc/src/javascript/imports.qdoc
index 138120345c..9e71368f81 100644
--- a/src/qml/doc/src/javascript/imports.qdoc
+++ b/src/qml/doc/src/javascript/imports.qdoc
@@ -28,4 +28,159 @@
 \page qtqml-javascript-imports.html
 \title Importing JavaScript Files In QML Documents
 \brief Description of how to import and use JavaScript files in QML documents
+
+Both relative and absolute JavaScript URLs can be imported in QML documents.
+In the case of a relative URL, the location is resolved relative to the
+location of the \l {QML Document} that contains the import.  If the script
+file is not accessible, an error will occur.  If the JavaScript needs to be
+fetched from a network resource, the component's
+\l {QQmlComponent::status()}{status} is set to "Loading" until the script has
+been downloaded.
+
+Imported JavaScript files are always qualified using the "as" keyword.  The
+qualifier for JavaScript files must be unique, so there is always a one-to-one
+mapping between qualifiers and JavaScript files. (This also means qualifiers
+cannot be named the same as built-in JavaScript objects such as \c Date and
+\c Math).
+
+The functions defined in an imported JavaScript file are available to objects
+defined in the importing QML document, via the \c{"Qualifier.functionName()"}
+syntax.
+
+\section1 Importing One JavaScript File From Another
+
+In QtQuick 2.0, support has been added to allow JavaScript files to import
+other JavaScript files and also QML type namespaces using a variation of the
+standard QML import syntax (where all of the previously described rules and
+qualifications apply).
+
+A JavaScript file may import another in the following fashion:
+\code
+.import "filename.js" as Qualifier
+\endcode
+For example:
+\code
+.import "factorial.js" as MathFunctions
+\endcode
+
+A JavaScript file may import a QML type namespace in the following fashion:
+\code
+.import TypeNamespace MajorVersion.MinorVersion as Qualifier
+\endcode
+
+For example:
+\code
+.import Qt.test 1.0 as JsQtTest
+\endcode
+
+In particular, this may be useful in order to access functionality provided
+via a module API; see qmlRegisterModuleApi() for more information.
+
+Due to the ability of a JavaScript file to import another script or QML module
+in this fashion in QtQuick 2.0, some extra semantics are defined:
+\list
+\li a script with imports will not inherit imports from the QML file which imported it (so accessing Component.error will fail, for example)
+\li a script without imports will inherit imports from the QML file which imported it (so accessing Component.error will succeed, for example)
+\li a shared script (i.e., defined as .pragma library) does not inherit imports from any QML file even if it imports no other scripts
+\endlist
+
+The first semantic is conceptually correct, given that a particular script
+might be imported by any number of QML files.  The second semantic is retained
+for the purposes of backwards-compatibility.  The third semantic remains
+unchanged from the current semantics for shared scripts, but is clarified here
+in respect to the newly possible case (where the script imports other scripts
+or modules).
+
+
+\section2 Code-Behind Implementation Files
+
+Most JavaScript files imported into a QML file are stateful implementations
+for the QML file importing them.  In these cases, for QML component instances
+to behave correctly each instance requires a separate copy of the JavaScript
+objects and state.
+
+The default behavior when importing JavaScript files is to provide a unique,
+isolated copy for each QML component instance.  If that JavaScript file does
+not import any other JavaScript files or QML type namespaces, its code will run
+in the same scope as the QML component instance and consequently can can access
+and manipulate the objects and properties declared in that QML component.
+Otherwise, it will have its own unique scope, and objects and properties of the
+QML component should be passed to the functions of the JavaScript file as
+parameters if they are required.
+
+\section2 Shared JavaScript Files (Libraries)
+
+Some JavaScript files act more like libraries - they provide a set of helper
+functions that take input and compute output, but never manipulate QML
+component instances directly.
+
+As it would be wasteful for each QML component instance to have a unique copy of
+these libraries, the JavaScript programmer can indicate a particular file is a
+shared library through the use of a pragma, as shown in the following example.
+
+\code
+// factorial.js
+.pragma library
+
+var factorialCount = 0;
+
+function factorial(a) {
+    a = parseInt(a);
+
+    // factorial recursion
+    if (a > 0)
+        return a * factorial(a - 1);
+
+    // shared state
+    factorialCount += 1;
+
+    // recursion base-case.
+    return 1;
+}
+
+function factorialCallCount() {
+    return factorialCount;
+}
+\endcode
+
+The pragma declaration must appear before any JavaScript code excluding comments.
+
+Note that multiple QML documents can import \c{"factorial.js"} and call the
+factorial and factorialCallCount functions that it provides.  The state of the
+JavaScript import is shared across the QML documents which import it, and thus
+the return value of the factorialCallCount function may be non-zero when called
+within a QML document which never calls the factorial function.
+
+As they are shared, .pragma library files cannot access QML component instance
+objects or properties directly, although QML values can be passed as function
+parameters.
+
+\section1 Including One JavaScript File From Another
+
+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{QML: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 {QML: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 {QML: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().
+
+
 */