Update imports and module documentation

Recently, the qmldir syntax was modified to allow a module identifier
directive to be specified.  This allows us to guarantee that types
provided in that namespace are not overridden by other modules.

Given this fundamental change, the documentation needed to be updated
to reflect the new terminology surrounding imports:
   - modules
       - identified vs legacy
   - directories
       - local and remote directory imports
   - JavaScript resources
       - scripts which can be imported directly

Change-Id: I5a3d38de93d0186e79b87f2b3050f2b802088348
Reviewed-by: Bea Lam <bea.lam@nokia.com>

2 files changed, 379 insertions, 61 deletions

diff --git a/src/qml/doc/src/syntax/directoryimports.qdoc b/src/qml/doc/src/syntax/directoryimports.qdoc
new file mode 100644
index 0000000000..eb100c60f0
--- /dev/null
+++ b/src/qml/doc/src/syntax/directoryimports.qdoc
@@ -0,0 +1,203 @@
+/****************************************************************************
+**
+** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** GNU Free Documentation License
+** 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.
+**
+** Other Usage
+** Alternatively, this file may be used in accordance with the terms
+** and conditions contained in a signed written agreement between you
+** and Nokia.
+**
+**
+**
+**
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+/*!
+\page qtqml-syntax-directoryimports.html
+\title Importing QML Document Directories
+\brief Description of directory import statements in QML
+
+A local directory of QML files can be imported without any additional setup or
+configuration.  A remote directory of QML files can also be imported, but
+requires a directory listing \c qmldir file to exist.  A local directory may
+optionally contain a directory listing \c qmldir file in order to define the
+type names which should be provided to clients which import the directory, and
+to specify JavaScript resources which should be made available to importers.
+
+
+\section1 Local Directory Imports
+
+Any QML file on the local file system can import a local directory as using an
+import statement that refers to the directory's absolute or relative file
+system path, enabling the file to use the \l{qtqml-typesystem-objecttypes.html}
+{object types} defined within that directory.
+
+If the local directory contains a directory listing \c qmldir file, the types
+will be made available with the type names specified in the \c qmldir file;
+otherwise, they will be made available with type names derived from the
+filenames of the QML documents.  Only filenames beginning with an uppercase
+letter and ending with ".qml" will be exposed as types if no \c qmldir file
+is specified in the directory.
+
+\section2 An Example
+
+Consider the following QML project directory structure. Under the top level directory \c myapp,
+there are a set of common UI components in a sub-directory named \c mycomponents, and the main
+application code in a sub-directory named \c main, like this:
+
+\code
+myapp
+    |- mycomponents
+        |- CheckBox.qml
+        |- DialogBox.qml
+        |- Slider.qml
+    |- main
+        |- application.qml
+\endcode
+
+The \c main/application.qml file can import the \c mycomponents directory using
+the relative path to that directory, allowing it to use the QML object types
+defined within that directory:
+
+\qml
+import "../mycomponents"
+
+DialogBox {
+    CheckBox {
+        // ...
+    }
+    Slider {
+        // ...
+    }
+}
+\endqml
+
+The directory may be imported into a qualified local namespace, in which case
+uses of any types provided in the directory must be qualified:
+
+\qml
+import "../mycomponents" as MyComponents
+
+MyComponents.DialogBox {
+    // ...
+}
+\endqml
+
+The ability to import a local directory is convenient for cases such as
+in-application component sets and application prototyping, although any code
+that imports such modules must must update their relevant \c import statements
+if the module directory moves to another location.  This can be avoided if
+\l{qtqml-modules-identifiedmodules.html}{QML modules} are used instead,
+as an installed module is imported with a unique identifier string rather than
+a file system path.
+
+
+\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.
+
+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
+contained a \c qmldir file defined as follows:
+
+\code
+CheckBox CheckBox.qml
+DialogBox DialogBox.qml
+Slider Slider.qml
+\endcode
+
+Then, the directory could be imported using the URL to the remote
+\c mycomponents directory:
+
+\qml
+import "http://www.my-example-server.com/myapp/mycomponents"
+
+DialogBox {
+    CheckBox {
+        // ...
+    }
+    Slider {
+        // ...
+    }
+}
+\endqml
+
+Note that when a file imports a directory over a network, it can only access QML
+and JavaScript files specified in the \c qmldir file located in the directory.
+
+\warning When importing directories from a remote server, developers should
+always be careful to only load directories from trusted sources to avoid
+loading malicious code.
+
+
+\section1 Directory Listing qmldir Files
+
+A directory listing \c qmldir file distinctly different from a
+\l{qtqml-modules-qmldir.html}{module definition qmldir file}.  A directory
+listing \c qmldir file allows a group of QML documents to be quickly and easily
+shared, but it does not define a type namespace into which the QML object types
+defined by the documents are registered, nor does it support versioning of
+those QML object types.
+
+The syntax of a directory listing \c qmldir file is as follows:
+\table
+    \header
+    \li Command
+    \li Syntax
+    \li Description
+
+    \row
+    \li Object Type Declaration
+    \li <TypeName> <FileName>
+    \li An object type declaration allows a QML document to be exposed with
+        the given \c <TypeName>.
+
+        Example:
+        \code
+RoundedButton RoundedBtn.qml
+        \endcode
+
+    \row
+    \li Internal Object Type Declaration
+    \li internal <TypeName> <FileName>
+    \li An internal object type declaration allows a QML document to be
+        registered as a type which becomes available only to the other
+        QML documents contained in the directory import.  The internal
+        type will not be made available to clients who import the directory.
+
+        Example:
+        \code
+internal HighlightedButton HighlightedBtn.qml
+        \endcode
+
+    \li JavaScript Resource Declaration
+    \li <Identifier> <FileName>
+    \li A JavaScript resource declaration allows a JavaScript file to be
+        exposed via the given identifier.
+
+        Example:
+        \code
+MathFunctions mathfuncs.js
+        \endcode
+\endtable
+
+A local file system directory may optionally include a \c qmldir file. This
+allows the engine to only expose certain QML types to clients who import the
+directory.  Additionally, JavaScript resources in the directory are not exposed
+to clients unless they are declared in a \c qmldir file.
+
+*/
+
diff --git a/src/qml/doc/src/syntax/imports.qdoc b/src/qml/doc/src/syntax/imports.qdoc
index 3519b3cc2f..51c80ea6c8 100644
--- a/src/qml/doc/src/syntax/imports.qdoc
+++ b/src/qml/doc/src/syntax/imports.qdoc
@@ -31,71 +31,122 @@
 
 \section1 Syntax of an Import Statement
 
+An import statement allows clients to tell the engine which modules, JavaScript
+resources and component directories are used within a QML document.  The types
+which may be used within a document depends on which modules, resources and
+directories are imported by the document.
 
-The \c import statement is used to provide the QML engine with access to the modules that define the types that are referred to from within the QML file.
+\section2 Import Types
 
-The syntax for the \c import statement is:
+There are three different types of imports.  Each import type has a slightly
+different syntax, and different semantics apply to different import types.
 
-\code
-import <module> <major version>.<minor version> [as <namespace>]
-\endcode
+\section3 Module (Namespace) Imports
 
-When a QML file is loaded by the engine, the only QML types that are automatically made available to that file are those that are \l{Defining Object Types through QML Documents}{defined by .qml files} within the same directory. Any types defined elsewhere are not accessible unless an \c import statement has imported the module that contains the required type. For example, the \c QtQuick module must be imported in order to use any of its QML types:
+The most common type of import is a module import.  Clients can import
+\l{qtqml-modules-identifiedmodules.html}{QML modules} which register QML object
+types and JavaScript resources into a given namespace.
 
+The generic form of a module import is as follows:
 \qml
-import QtQuick 2.0
-
-Rectangle {}    // won't work if import line is missing, engine will refuse to load the file
+import <ModuleIdentifier> <Version.Number> [as <Qualifier>]
 \endqml
 
-The \c <module> can be either a filesystem path to the module, or an identifier for the module if it is accessible to the import path. For example:
-
-\code
-import "../relative/path/to/module"
-import "/absolute/path/to/module"
-import com.company.module
-\endcode
+\list
+  \li The \c <ModuleIdentifier> is an identifier specified in dotted URI
+      notation, which uniquely identifies the type namespace provided by the
+      module.
+  \li The \c <Version.Number> is a version of the form
+      \c {MajorVersion.MinorVersion} which specifies which definitions of
+      various object types and JavaScript resources will be made available due
+      to the import.
+  \li The \c <Qualifier> is an optional local namespace identifier into which
+      the object types and JavaScript resources provided by the module will be
+      installed, if given.  If omitted, the object types and JavaScript
+      resources provided by the module will be installed into the global
+      namespace.
+\endlist
 
-(See \l {QML Modules} for more information on defining and importing located and installed modules.)
+An example of an unqualified module import is as follows:
+\qml
+import QtQuick 2.0
+\endqml
 
+This import allows the use of all of the types provided by the \c QtQuick
+module without needing to specify a qualifier.  For example, the client code to
+create a rectangle is as follows:
 
-\note Import paths are network transparent: applications can import documents from remote paths just as simply as documents from local paths. See the general URL resolution rules for \l{qtqml-documents-networktransparency.html}{Network Transparency} in QML documents.
+\qml
+import QtQuick 2.0
 
+Rectangle {
+    width: 200
+    height: 100
+    color: "red"
+}
+\endqml
 
-\section1 Debugging
+An example of a qualified module import is as follows:
+\qml
+import QtQuick 2.0 as Quick
+\endqml
 
-The \c QML_IMPORT_TRACE environment variable can be useful for debugging
-when there are problems with finding and loading modules. See
-\l{Debugging module imports} for more information.
+This import allows multiple modules which provide conflicting type names to be
+imported at the same time, however since each usage of a type provided by a
+module which was imported into a qualified namespace must be preceded by the
+qualifier, the conflict is able to be resolved unambiguously by the QML engine.
 
+An example of client code which creates a rectangle after using a qualified
+module import is as follows:
 
-\section1 QML Import Path
+\qml
+import QtQuick 2.0 as Quick
 
-When an \l{qtqml-modules-installedmodules.html}{installed module} is imported, the QML engine
-searches the \e{import path} for a matching module.
+Quick.Rectangle {
+    width: 200
+    height: 100
+    color: "red"
+}
+\endqml
 
-This import path, as returned by QQmlEngine::importPathList(), defines the default
-locations to be searched by the engine. By default, this list contains:
+For more information about qualified imports, see the upcoming section on
+\l{Importing Into A Qualified Local Namespace}.
 
-\list
-\li The directory of the current file
-\li The location specified by QLibraryInfo::ImportsPath
-\li Paths specified by the \c QML_IMPORT_PATH environment variable
-\endlist
+Note that if a QML document does not import a module which provides a
+particular QML object type, but attempts to use that object type anyway,
+an error will occur.  For example, the following QML document does not
+import \c QtQuick and thus attempting to use the \c Rectangle type will fail:
 
-Additional import paths can be added through QQmlEngine::addImportPath() or the
-\c QML_IMPORT_PATH environment variable. When running the \l {Prototyping with qmlscene}{qmlscene}
-tool, you can also use the \c -I option to add an import path.
+\qml
+Rectangle {
+    width: 200
+    height: 100
+    color: "red"
+}
+\endqml
 
+In this case, the engine will emit an error and refuse to load the file.
 
+\section4 Non-module Namespace Imports
 
-\section1 Namespaced Imports
+Types can also be registered into namespaces directly via the various
+registration functions in C++ (such as qmlRegisterType()).  The types which
+have been registered into a namespace in this way may be imported by importing
+the namespace, as if the namespace was a module identifier.
 
+This is most common in client applications which define their own QML object
+types in C++ and register them with the QML type system manually.
 
+\section4 Importing into a Qualified Local Namespace
 
-The \c import statement may optionally use the \c as keyword to specify that the module should be imported into a particular namespace. If a namespace is specified, then any references to the types made available by the module must be prefixed by the namespace qualifier.
+The \c import statement may optionally use the \c as keyword to specify that
+the types should be imported into a particular document-local namespace. If a
+namespace is specified, then any references to the types made available by the
+import must be prefixed by the local namespace qualifier.
 
-Below, the QtQuick module is imported into the namespace "CoreItems". Now, any references to types from the \c QtQuick module must be prefixed with the \c CoreItems name:
+Below, the QtQuick module is imported into the namespace "CoreItems". Now, any
+references to types from the \c QtQuick module must be prefixed with the
+\c CoreItems name:
 
 \qml
 import QtQuick 2.0 as CoreItems
@@ -110,9 +161,14 @@ CoreItems.Rectangle {
 }
 \endqml
 
-A namespace acts as an identifier for a module within the scope of the file. The namespace does not become an attribute of the root object that can be referred to externally as can be done with properties, signals and methods.
+A namespace acts as an identifier for a module within the scope of the file.
+The namespace does not become an attribute of the root object that can be
+referred to externally as can be done with properties, signals and methods.
 
-The namespaced import is useful if there is a requirement to use two QML types that have the same name but are located in different modules. In this case the two modules can be imported into different namespaces to ensure the code is referring to the correct type:
+The namespaced import is useful if there is a requirement to use two QML types
+that have the same name but are located in different modules. In this case the
+two modules can be imported into different namespaces to ensure the code is
+referring to the correct type:
 
 \qml
 import QtQuick 2.0 as CoreItems
@@ -126,58 +182,86 @@ CoreItems.Rectangle {
 }
 \endqml
 
-Note that multiple modules can be imported into the same namespace in the same way that multiple modules can be imported into the global namespace. For example:
+Note that multiple modules can be imported into the same namespace in the same
+way that multiple modules can be imported into the global namespace. For example:
 
 \snippet qml/imports/merged-named-imports.qml imports
 
+\section3 Directory Imports
 
+A directory which contains QML documents may also be imported directly in a
+QML document.  This provides a simple way for QML types to be segmented into
+reusable groupings: directories on the filesystem.
+
+The generic form of a directory import is as follows:
+\qml
+import "<DirectoryPath>" [as <Qualifier>]
+\endqml
 
+\note Import paths are network transparent: applications can import documents
+from remote paths just as simply as documents from local paths. See the general
+URL resolution rules for \l{qtqml-documents-networktransparency.html}
+{Network Transparency} in QML documents.  If the directory is remote, it must
+contain a \l{qtqml-syntax-directoryimports.html#directory-listing-qmldir-files}
+{directory import listing qmldir file} as the QML engine cannot determine
+the contents of a remote directory if that \c qmldir file does not exist.
 
-\section1 Relative Directory Imports
+Similar semantics for the \c <Qualifier> apply to directory imports as for
+module imports; for more information on the topic, please see the previous
+section about \l{Importing into a Qualified Local Namespace}.
 
-\section1 JavaScript File Imports
+For more information about directory imports, please see the in-depth
+documentation about \l{qtqml-syntax-directoryimports.html}{directory imports}.
 
+\section3 JavaScript Resource Imports
 
-JavaScript files must always be imported with a named import:
+JavaScript resources may be imported directly in a QML document.  Every
+JavaScript resource must have an identifier by which it is accessed.
 
+The generic form of a JavaScript resource import is as follows:
 \qml
-import "somescript.js" as MyScript
-
-Item {
-    //...
-    Component.onCompleted: MyScript.doSomething()
-}
+import "<JavaScriptFile>" as <Identifier>
 \endqml
 
-The qualifier ("MyScript" in the above example) must be unique within the QML document.
-Unlike ordinary modules, multiple scripts cannot be imported into the same namespace.
+Note that the \c <Identifier> must be unique within a QML document, unlike the
+local namespace qualifier which can be applied to module imports.
 
-Javascript files can be provided by modules, by adding Namespace definitions to the
-\l{Adding Module Metadata with a qmldir file}{qmldir file} for the module.  For example:
+\section4 JavaScript Resources from Modules
 
+Javascript files can be provided by modules, by adding identifier
+definitions to the \c qmldir file which specifies the module.
+
+For example, if the \c projects.MyQMLProject.MyFunctions module is specified
+with the following \c qmldir file, and installed into the QML import path:
 \code
+module projects.MyQMLProject.MyFunctions
 SystemFunctions 1.0 SystemFunctions.js
 UserFunctions 1.0 UserFunctions.js
 \endcode
 
-Javascript can be imported from a module, where they will have the namespace defined
-for them in the module's \c qmldir file:
+a client application is able to import the JavaScript resources declared in the
+module by importing the module and using the identifier associated with a
+declared resource:
 
 \qml
+import QtQuick 2.0
 import projects.MyQMLProject.MyFunctions 1.0
 
-Window {
+Item {
     Component.onCompleted: { SystemFunctions.cleanUp(); }
 }
 \endqml
 
-Javascript provided by modules can also be imported into namespaces:
+If the module was imported into a document-local namespace, the JavaScript
+resource identifiers must be prefixed with the namespace qualifier in order
+to be used:
 
 \qml
+import QtQuick 2.0
 import projects.MyQMLProject.MyFunctions 1.0 as MyFuncs
 import org.example.Functions 1.0 as TheirFuncs
 
-Window {
+Item {
     Component.onCompleted: {
         MyFuncs.SystemFunctions.cleanUp();
         TheirFuncs.SystemFunctions.shutdown();
@@ -185,9 +269,40 @@ Window {
 }
 \endqml
 
+\section4 Further Information
+
+For more information about JavaScript resources, please see the documentation
+about \l{qtqml-javascript-resources.html}
+{defining JavaScript resources in QML}, and for more information about how
+to import JavaScript resources, and how imports can be used from within
+JavaScript resources, please see the in-depth documentation about
+\l{qtqml-javascript-imports.html}{importing JavaScript resources in QML}.
+
+
+\section1 QML Import Path
+
+When an \l{qtqml-modules-installedmodules.html}{installed module} is imported,
+the QML engine searches the \e{import path} for a matching module.
+
+This import path, as returned by QQmlEngine::importPathList(), defines the
+default locations to be searched by the engine. By default, this list contains:
+
+\list
+\li The directory of the current file
+\li The location specified by QLibraryInfo::ImportsPath
+\li Paths specified by the \c QML_IMPORT_PATH environment variable
+\endlist
+
+Additional import paths can be added through QQmlEngine::addImportPath() or the
+\c QML_IMPORT_PATH environment variable. When running the
+\l{Prototyping with qmlscene}{qmlscene} tool, you can also use the \c -I option
+to add an import path.
+
 
-\section1 Version Specification
+\section1 Debugging
 
-\section1 Import Qualifier
+The \c QML_IMPORT_TRACE environment variable can be useful for debugging
+when there are problems with finding and loading modules. See
+\l{Debugging module imports} for more information.
 
 */