Merge old "Modules" docs into new doc structure

This removes modules/todo.qdoc which contained the old "Modules"
documentation page and merges this content into the new Modules
documentation.

Also cleaned up the structure of the "qmldir" docs.

Task-number: QTBUG-26378
Change-Id: Idc8800d0595647eb7064ecadc5a00254341ed1e8
Reviewed-by: Chris Adams <christopher.adams@nokia.com>

7 files changed, 729 insertions, 313 deletions

diff --git a/src/qml/doc/src/modules/installedmodules.qdoc b/src/qml/doc/src/modules/installedmodules.qdoc
new file mode 100644
index 0000000000..a17b23615f
--- /dev/null
+++ b/src/qml/doc/src/modules/installedmodules.qdoc
@@ -0,0 +1,163 @@
+/****************************************************************************
+**
+** 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-modules-installedmodules.html
+\title Installed Modules
+\brief Creating and importing installed modules
+
+Installed modules are modules that are identifiable to the QML engine by a URI in the form of a
+dotted identifier string. This enables such modules to be imported with a unique identifier that
+remains the same no matter where the module is located on the local file system. This contrasts with
+\l{qtqml-modules-locatedmodules.html}{located modules}, which are imported according to their
+location on the file system.
+
+When importing an installed module, an unquoted URI is used, with a mandatory version number:
+
+\snippet qml/imports/installed-module.qml imports
+
+Installed modules must be made available in the \l{qtqml-syntax-imports.html#qml-import-path}{import
+path} in order to be found by the QML engine.
+
+
+\section1 Locally Installed Modules
+
+A directory of QML and/or C++ files can be shared as an installed module if it contains a
+\l{qtqml-modules-qmldir.html}{qmldir file} with the module metadata. Any QML file on the local file
+system can import this directory as a module by using an \l{qtqml-syntax-imports.html}{import}
+statement that refers to the module's URI, enabling the file to use the
+\l{qtqml-typesystem-objecttypes.html}{QML object types} defined within that directory.
+
+The module's \c qmldir file must reside in a directory structure within the
+\l{qtqml-syntax-imports.html#qml-import-path}{import path} that reflects the URI dotted identifier
+string, where each dot (".") in the identifier reflects a sub-level in the directory tree. For
+example, the \c qmldir file of the module \c com.mycompany.mymodule must be located in the sub-path
+\c com/mycompany/mymodule/qmldir somewhere in the
+\l{qtqml-syntax-imports.html#qml-import-path}{import path}.
+
+It is possible to store different versions of a module in subdirectories of its own. For example, a
+version 2.1 of a module could be located under \c com/mycompany/mymodule.2/qmldir or \c
+com/mycompany/mymodule.2.1/qmldir. The engine will automatically load the module which matches best.
+
+
+\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
+
+To make the \c mycomponents directory available as an installed module, the directory must include a
+\l{qtqml-modules-qmldir.html}{qmldir file} that describes the object types made available by the
+module. For example, to make the \c CheckBox, \c DialogBox and \c Slider types available for version
+1.0 of the module, the \c qmldir file would contain the following:
+
+\code
+CheckBox 1.0 CheckBox.qml
+DialogBox 1.0 DialogBox.qml
+Slider 1.0 Slider.qml
+\endcode
+
+Additionally, the location of the \c qmldir file in the
+\l{qtqml-syntax-imports.html#qml-import-path}{import path} must match the module's dotted identifier
+string. So, say the top level \c myapp directory is located in \c C:\qml\projects, and say the
+module should be identified as "myapp.mycomponents". In this case:
+
+\list
+\li The path \c C:\qml\projects should be added to the
+\l{qtqml-syntax-imports.html#qml-import-path}{import path}
+\li The qmldir file should be located under \c C:\qml\projects\myapp\mycomponents\qmldir
+\endlist
+
+Once this is done, a QML file located anywhere on the local filesystem can import the module by
+referring to its URI and the appropriate version:
+
+\qml
+import myapp.mycomponents 1.0
+
+DialogBox {
+    CheckBox {
+        // ...
+    }
+    Slider {
+        // ...
+    }
+}
+\endqml
+
+
+\section1 Remotely Installed Modules
+
+Installed modules are also accessible as a network resource. In the previous example, if the \c
+C:\qml\projects directory was hosted as \c http://www.some-server.com/qml/projects and this URL was
+added to the QML import path, the module could be imported in exactly the same way.
+
+Note that when a file imports a module over a network, it can only access QML and JavaScript files
+provided by the module; it cannot access any types defined by C++ plugins in the module.
+
+
+\section1 In-application Modules
+
+C++ applications can define installed modules directly within the application using
+qmlRegisterType().
+
+For example, the \l {Tutorial: Extending QML with C++}{Writing QML extensions with C++ tutorial}
+defines a C++ class named \c PieChart and makes this type available to QML by calling
+qmlRegisterType():
+
+\code
+qmlRegisterType<PieChart>("Charts", 1, 0, "PieChart");
+\endcode
+
+This allows the application's QML files to use the \c PieChart type by importing the declared
+\c Charts module:
+
+\snippet qml/imports/chart.qml import
+
+For \l{QQmlExtensionPlugin}{QML plugins}, the
+module URI is automatically passed to QQmlExtensionPlugin::registerTypes(). This method
+can be reimplemented by the developer to register the necessary types for the module. Below is the
+\c registerTypes() implementation from the \l{qml/cppextensions/plugins}{QML plugins}
+example:
+
+\snippet examples/qml/cppextensions/plugins/plugin.cpp plugin
+
+Once the plugin is built and installed, and includes a \l{Syntax of a qmldir file}{qmldir file},
+the module can be imported from QML, like this:
+
+\snippet qml/imports/timeexample.qml import
+
+*/
+
diff --git a/src/qml/doc/src/modules/locatedmodules.qdoc b/src/qml/doc/src/modules/locatedmodules.qdoc
new file mode 100644
index 0000000000..b42b1a2c42
--- /dev/null
+++ b/src/qml/doc/src/modules/locatedmodules.qdoc
@@ -0,0 +1,148 @@
+/****************************************************************************
+**
+** 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-modules-locatedmodules.html
+\title Located Modules
+\brief Creating and importing located modules
+
+Located modules are modules that reside on the the local file system or a
+network resource and can be referred to by a URL that specifies the file system
+path or network URL. This allows any directory with QML content to be
+\l{qtqml-syntax-imports.html}{imported} as a module, regardless of whether the
+directory is on the local file system or a remote server.
+
+
+\section1 Locally Located Modules
+
+A directory of QML files can immediately be shared as a module without any additional setup or
+configuration.
+
+Any QML file on the local file system can import this directory as a module by using an
+\l{qtqml-syntax-imports.html}{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.
+
+\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 as a module 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
+
+It is not necessary to pass a version number to the \c import statement when importing a locally
+located module. Additionally, the module could be imported with a
+\l{qtqml-syntax-imports.html#namespaced-import}{namespaced import} to qualify any references to the
+types in the module:
+
+\qml
+import "../mycomponents" as MyComponents
+
+MyComponents.DialogBox {
+    // ...
+}
+\endqml
+
+A local file system module may optionally include a \l{qtqml-modules-qmldir.html}{qmldir file}. This
+allows the module to only expose certain QML types to external parties. Additionally, JavaScript
+files in the module directory are not exposed to external parties unless they are declared in a
+qmldir file.
+
+The ability to import a local module using its file system path is convenient for cases such as
+in-application modules and application prototyping, though 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-installedmodules.html}{installed modules} are used instead,
+as an installed module is imported with a unique identifier string rather than a file system path.
+
+
+\section1 Remotely Located Modules
+
+A directory of QML files can also be imported from a remote location if the directory contains a
+\l{qtqml-modules-qmldir.html}{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 1.0 CheckBox.qml
+DialogBox 1.0 DialogBox.qml
+Slider 1.0 Slider.qml
+\endcode
+
+Then, the module 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
+
+In this case the module could optionally be imported with a "1.0" version specification as that is
+the version specified in the \c qmldir file. The import would fail if any later version was used as
+the \c qmldir file specifies that these elements are only available in version 1.0.
+
+Note that when a file imports a module over a network, it can only access QML and JavaScript files
+provided by the module; it cannot access any types defined by C++ plugins in the module.
+
+\warning When importing modules from a remote server, developers should always be careful to only
+load modules from trusted sources to avoid loading malicious code.
+
+*/
+
diff --git a/src/qml/doc/src/modules/qmldir.qdoc b/src/qml/doc/src/modules/qmldir.qdoc
new file mode 100644
index 0000000000..354dfb0573
--- /dev/null
+++ b/src/qml/doc/src/modules/qmldir.qdoc
@@ -0,0 +1,333 @@
+/****************************************************************************
+**
+** 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-modules-qmldir.html
+\title Adding Module Metadata with a qmldir File
+\brief How to write a qmldir file for a module
+
+A \e qmldir file is a metadata file for a module that maps all type names in the module to
+versioned QML files. It is required for \l{qtqml-modules-installedmodules.html}{installed modules},
+as well as \l{qtqml-modules-locatedmodules.html}{located modules} that are loaded from a network
+source.
+
+This file is defined by a plain text file named "qmldir" within the module. For
+\l{qtqml-modules-locatedmodules.html}{located modules}, this file should be in the module's root
+directory. For \l{qtqml-modules-installedmodules.html}{installed modules}, the file should be in a
+directory within the module according to the named identifier for the module; see the \l{Installed
+Modules} documentation for more information.
+
+
+\section1 Writing a qmldir file
+
+A \c qmldir file contains one or more lines of the following commands:
+
+\table
+    \header
+        \li Command Syntax
+        \li Usage
+
+    \row
+        \li
+            \code
+<TypeName> [<InitialVersion>] <File>
+            \endcode
+        \li Declares an \l{qtqml-typesystem-objecttypes.html}{object type} to be made available by
+            the module.
+                \list
+                \li \c <TypeName> is the type being made available
+                \li \c <InitialVersion> (optional) is the module version for which the type is to be
+                    made available
+                \li \c <File> is the (relative) file name of the QML file that defines the type
+                \endlist
+
+            Example:
+            \code
+MyCustomType 1.0 MyCustomType.qml
+            \endcode
+    \row
+        \li
+            \code
+internal <TypeName> <File>
+            \endcode
+        \li Declares an object type that is in the module but should not be made available to users
+            of the module.
+
+            Example:
+            \code
+internal MyPrivateType MyPrivateType.qml
+         \endcode
+
+            This is necessary if the module may be imported remotely (see \l{Remotely Located
+            Modules} and \l{Remotely Installed Modules}) because if an exported type depends on an
+            non-exported type within the module, the engine must also load the non-exported type.
+
+    \row
+        \li
+            \code
+<Namespace> <InitialVersion> <File>
+            \endcode
+        \li Declares a JavaScript file to be made available by the module. The file will be made
+            available through the specified namespace and verison number.
+
+            Example:
+            \code
+MyScript 1.0 MyScript.js
+            \endcode
+
+            See \l{qtqml-javascript-imports.html}{Importing JavaScript Files In QML Documents} for
+            more information.
+
+    \row
+        \li
+            \code
+plugin <Name> [<Path>]
+            \endcode
+        \li Declares a plugin to be made available by the module.
+
+            \list
+            \li \c <Name> is the plugin library name. This is usually not the same as the file name
+                of the plugin binary, which is platform dependent; e.g. the library \c MyAppTypes
+                would produce \c libMyAppTypes.so on Linux and \c MyAppTypes.dll on Windows.
+            \li \c <Path> (optional) specifes either:
+                \list
+                \li an absolute path to the directory containing the plugin file, or
+                \li a relative path from the directory containing the \c qmldir file to the
+                    directory containing the plugin file.
+                \endlist
+
+                By default the engine searches for the plugin library in the directory that contains
+                the \c qmldir file. (The plugin search path can be queried with
+                QQmlEngine::pluginPathList() and modified using QQmlEngine::addPluginPath().)
+            \endlist
+
+            Example:
+            \code
+plugin MyPluginLibrary
+           \endcode
+
+    \row
+        \li
+            \code
+typeinfo <File>
+            \endcode
+        \li Declares a \l{Writing a qmltypes file}{type description file} for the module that can be
+            read by QML tools such as Qt Creator to access information about the types defined by the module's plugins. \c <File> is the (relative) file name of a \c .qmltypes file.
+
+            Example:
+            \code
+typeinfo mymodule.qmltypes
+            \endcode
+
+            Without such a file, QML tools may be unable to offer features such as code completion
+            for the types defined in your plugins.
+
+    \row
+        \li
+            \code
+# <Comment>
+            \endcode
+        \li Declares a comment. These are ignored by the engine.
+
+            Example:
+            \code
+# this is a comment
+            \endcode
+\endtable
+
+For example, suppose a module's \c qmldir file should export a \c MyButton type in version 1.0, a \c
+MyWindow type in version 1.1 and a JavaScript file to a \c MyScript namespace in version 1.1.
+Providing the relevant files are in the same directory as the \c qmldir file, the contents of the \c
+qmldir file would look like this:
+
+\code
+MyButton 1.0 MyButton.qml
+MyWindow 1.1 MyWindow.qml
+MyScript 1.1 myscript.js
+\endcode
+
+If these files were part of an \l{qtqml-modules-installedmodules.html}{installed module} named \c
+com.mycompany.module then the module could be imported and its exported types used as follows:
+
+\qml
+import com.mycompany.module 1.1
+
+MyWindow {
+    function doStuff() {
+        MyScript.doSomething();
+    }
+
+    MyButton {
+        // ...
+    }
+}
+\endqml
+
+Types which are exported for a particular version are still made available if a later version is
+imported: in the above example, the code imports version 1.1 of the module but still has access to
+the \c MyButton type that was exported for version 1.0. However, the reverse is not true: a type
+exported for a particular version cannot be used if an earlier version is imported. If the code
+above imported version 1.0 of the module, it could not have used the \c MyWindow type and \c
+MyScript namespace as these are declared for version 1.1.
+
+A type can be defined by different files in different versions. In this case, later versions (e.g.
+1.2) must precede earlier versions (e.g. 1.0) within the \c qmldir file, since the engine loads the
+first type it finds with a matching name and version.
+
+The versioning system ensures that a given QML file will work regardless of the version
+of installed software, since a versioned import \e only imports types for that version,
+leaving other identifiers available, even if the actual installed version might otherwise
+provide those identifiers.
+
+See \l{Located Modules} and \l{Installed Modules} for more example \c qmldir file content, and see
+\l{examples/qml/cppextensions/plugins} for an example that uses C++ plugins.
+
+
+\section1 Writing a qmltypes file
+
+QML modules may refer to one or more type information files in their
+\c qmldir file. These usually have the \c .qmltypes
+extension and are read by external tools to gain information about
+types defined in plugins.
+
+As such qmltypes files have no effect on the functionality of a QML module.
+Their only use is to allow tools such as Qt Creator to provide code completion,
+error checking and other functionality to users of your module.
+
+Any module that uses plugins should also ship a type description file.
+
+The best way to create a qmltypes file for your module is to generate it
+using the \c qmlplugindump tool that is provided with Qt.
+
+Example:
+If your module is in \c /tmp/imports/My/Module, you could run
+\code
+qmlplugindump My.Module 1.0 /tmp/imports > /tmp/imports/My/Module/mymodule.qmltypes
+\endcode
+to generate type information for your module. Afterwards, add the line
+\code
+typeinfo mymodule.qmltypes
+\endcode
+to \c /tmp/imports/My/Module/qmldir to register it.
+
+While the qmldump tool covers most cases, it does not work if:
+\list
+\li The plugin uses a \l{QQmlCustomParser}. The component that uses
+   the custom parser will not get its members documented.
+\li The plugin can not be loaded. In particular if you cross-compiled
+   the plugin for a different architecture, qmldump will not be able to
+   load it.
+\endlist
+
+In case you have to create a qmltypes file manually or need to adjust
+an existing one, this is the file format:
+
+\qml
+import QtQuick.tooling 1.1
+
+// There always is a single Module object that contains all
+// Component objects.
+Module {
+    // A Component object directly corresponds to a type exported
+    // in a plugin with a call to qmlRegisterType.
+    Component {
+
+        // The name is a unique identifier used to refer to this type.
+        // It is recommended you simply use the C++ type name.
+        name: "QQuickAbstractAnimation"
+
+        // The name of the prototype Component.
+        prototype: "QObject"
+
+        // The name of the default property.
+        defaultProperty: "animations"
+
+        // The name of the type containing attached properties
+        // and methods.
+        attachedType: "QDeclarativeAnimationAttached"
+
+        // The list of exports determines how a type can be imported.
+        // Each string has the format "URI/Name version" and matches the
+        // arguments to qmlRegisterType. Usually types are only exported
+        // once, if at all.
+        // If the "URI/" part of the string is missing that means the
+        // type should be put into the package defined by the URI the
+        // module was imported with.
+        // For example if this module was imported with 'import Foo 4.8'
+        // the Animation object would be found in the package Foo and
+        // QtQuick.
+        exports: [
+            "Animation 4.7",
+            "QtQuick/Animation 1.0"
+        ]
+
+        // The meta object revisions for the exports specified in 'exports'.
+        // Describes with revisioned properties will be visible in an export.
+        // The list must have exactly the same length as the 'exports' list.
+        // For example the 'animations' propery described below will only be
+        // available through the QtQuick/Animation 1.0 export.
+        exportMetaObjectRevisions: [0, 1]
+
+        Property {
+            name: "animations";
+            type: "QQuickAbstractAnimation"
+            // defaults to false, whether this property is read only
+            isReadonly: true
+            // defaults to false, whether the type of this property was a pointer in C++
+            isPointer: true
+            // defaults to false: whether the type actually is a QQmlListProperty<type>
+            isList: true
+            // defaults to 0: the meta object revision that introduced this property
+            revision: 1
+        }
+        Property { name: "loops"; type: "int" }
+        Property { name: "name"; type: "string" }
+        Property { name: "loopsEnum"; type: "Loops" }
+
+        Enum {
+            name: "Loops"
+            values: {
+                "Infinite": -2,
+                "OnceOnly": 1
+            }
+        }
+
+        // Signal and Method work the same way. The inner Parameter
+        // declarations also support the isReadonly, isPointer and isList
+        // attributes which mean the same as for Property
+        Method { name: "restart" }
+        Signal { name: "started"; revision: 2 }
+        Signal {
+            name: "runningChanged"
+            Parameter { type: "bool" }
+            Parameter { name: "foo"; type: "bool" }
+        }
+    }
+}
+\endqml
+
+*/
+
diff --git a/src/qml/doc/src/modules/todo.qdoc b/src/qml/doc/src/modules/todo.qdoc
deleted file mode 100644
index f7eb48d39f..0000000000
--- a/src/qml/doc/src/modules/todo.qdoc
+++ /dev/null
@@ -1,266 +0,0 @@
-/****************************************************************************
-**
-** 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 qmllanguage-modules.html
-\title QML Modules
-\brief creating and importing QML modules
-
-\section1 Modules
-
-A module is a set of QML content files that can be imported as a unit into a QML
-application. Modules can be used to organize QML content into independent units,
-and they can use a versioning mechanism that allows for independent
-upgradability of the modules.
-
-While QML component files within the same directory are automatically accessible
-within the global namespace, components defined elsewhere must be imported
-explicitly using the \c import statement to import them as modules. For
-example, an \c import statement is required to use:
-
-\list
-\li A component defined in another QML file that is not in the same directory
-\li A component defined in a QML file located on a remote server
-\li A \l{QQmlExtensionPlugin}{QML extension plugin} library (unless the plugin is installed in the same directory)
-\li A JavaScript file (note this must be imported using \l {#namespaces}{named imports})
-\endlist
-
-An \c import statement includes the module name, and possibly a version number.
-This can be seen in the snippet commonly found at the top of QML files:
-
-\snippet qml/imports/qtquick-1.0.qml import
-
-This imports version 1.0 of the "QtQuick" module into the global namespace. (The QML
-library itself must be imported to use any of the \l {QML Elements}, as they
-are not included in the global namespace by default.)
-
-The \c Qt module is an \e installed module; it is found in the
-\l{#import-path}{import path}. There are two types of QML modules:
-located modules (defined by a URL) and installed modules (defined by a URI).
-
-
-\section1 Located Modules
-
-Located modules can reside on the local filesystem or a network resource,
-and are referred to by a quoted location URL that specifies the filesystem
-or network URL. They allow any directory with QML content to be imported
-as a module, whether the directory is on the local filesystem or a remote
-server.
-
-For example, a QML project may have a separate directory for a set of
-custom UI components. These components can be accessed by importing the
-directory using a relative or absolute path, like this:
-
-\table
-\row
-\li Directory structure
-\li Contents of application.qml
-
-\row
-\li
-\code
-MyQMLProject
-    |- MyComponents
-        |- CheckBox.qml
-        |- Slider.qml
-        |- Window.qml
-    |- Main
-        |- application.qml
-\endcode
-
-\li
-\qml
-import "../MyComponents"
-
-Window {
-    Slider {
-        // ...
-    }
-    CheckBox {
-        // ...
-    }
-}
-\endqml
-
-\endtable
-
-Similarly, if the directory resided on a network source, it could
-be imported like this:
-
-\snippet qml/imports/network-imports.qml imports
-
-A located module can also be imported as a network resource if it has a
-\l{Syntax of a qmldir file}{qmldir file} in the directory that specifies the QML files
-to be made available by the module. For example, if the \c MyComponents directory
-contained a \c qmldir file defined like this:
-
-\code
-Slider 1.0 Slider.qml
-CheckBox 1.0 CheckBox.qml
-Window 1.0 Window.qml
-\endcode
-
-If the \c MyComponents directory was then hosted as a network resource, it could
-be imported as a module, like this:
-
-\qml
-import "http://the-server-name.com/MyQMLProject/MyComponents"
-
-Window {
-    Slider {
-        // ...
-    }
-    CheckBox {
-        // ...
-    }
-}
-\endqml
-
-with an optional "1.0" version specification. Notice the import would fail if
-a later version was used, as the \c qmldir file specifies that these elements
-are only available in the 1.0 version.
-
-Note that modules imported as a network resource allow only access to components
-defined in QML files; components defined by C++ \l{QQmlExtensionPlugin}{QML extension plugins}
-are not available.
-
-
-\target import-path
-\section1 Installed Modules
-
-Installed modules are modules that are made available through the QML import path,
-as defined by QQmlEngine::importPathList(), or modules defined within
-C++ application code. An installed module is referred to by a URI, which allows
-the module to be imported from QML code without specifying a complete filesystem
-path or network resource URL.
-
-When importing an installed module, an un-quoted URI is
-used, with a mandatory version number:
-
-\snippet qml/imports/installed-module.qml imports
-
-When a module is imported, the QML engine searches the QML import path for a matching
-module. The root directory of the module must contain a
-\l{Syntax of a qmldir file}{qmldir file} that defines the QML files
-and/or C++ QML extension plugins that are made available to the module.
-
-Modules that are installed into the import path translate the URI into
-directory names. For example, the qmldir file of the module \c com.nokia.qml.mymodule
-must be located in the subpath \c com/nokia/qml/mymodule/qmldir somewhere in the
-QML import path. In addition it is possible to store different versions of the
-module in subdirectories of its own. For example, a version 2.1 of the
-module could be located under \c com/nokia/qml/mymodule.2/qmldir or
-\c com/nokia/qml/mymodule.2.1/qmldir. The engine will automatically load
-the module which matches best.
-
-The import path, as returned by QQmlEngine::importPathList(), defines the default
-locations to be searched by the QML engine for a matching module. 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}, you
-can also use the \c -I option to add an import path.
-
-
-\section2 Creating Installed Modules
-
-As an example, suppose the \c MyQMLProject directory in the \l{Located Modules}{previous example}
-was located on the local filesystem at \c C:\qml\projects\MyQMLProject. The \c MyComponents
-subdirectory could be made available as an installed module by adding a
-\l{Syntax of a qmldir file}{qmldir file} to the \c MyComponents directory that looked like this:
-
-\code
-Slider 1.0 Slider.qml
-CheckBox 1.0 CheckBox.qml
-Window 1.0 Window.qml
-\endcode
-
-Providing the path \c C:\qml is added to the QML import path using any of the methods listed previously,
-a QML file located anywhere on the local filesystem can then import the module as shown below,
-without referring to the module's absolute filesystem location:
-
-\qml
-import projects.MyQMLProject.MyComponents 1.0
-
-Window {
-    Slider {
-        // ...
-    }
-    CheckBox {
-        // ...
-    }
-}
-\endqml
-
-Installed modules are also accessible as a network resource. If the \c C:\qml directory was hosted
-as \c http://www.some-server.com/qml and this URL was added to the QML import path, the above
-QML code would work just the same.
-
-Note that modules imported as a network resource allow only access to components
-defined in QML files; components defined by C++ \l{QQmlExtensionPlugin}{QML extension plugins}
-are not available.
-
-
-\section2 Creating Installed Modules in C++
-
-C++ applications can define installed modules directly within the application using qmlRegisterType().
-For example, the \l {Tutorial: Extending QML with C++}{Writing QML extensions with C++ tutorial}
-defines a C++ class named \c PieChart and makes this type available to QML by calling qmlRegisterType():
-
-\code
-qmlRegisterType<PieChart>("Charts", 1, 0, "PieChart");
-\endcode
-
-This allows the application's QML files to use the \c PieChart type by importing the declared
-\c Charts module:
-
-\snippet qml/imports/chart.qml import
-
-For \l{QQmlExtensionPlugin}{QML plugins}, the
-module URI is automatically passed to QQmlExtensionPlugin::registerTypes(). This method
-can be reimplemented by the developer to register the necessary types for the module. Below is the
-\c registerTypes() implementation from the \l{qml/cppextensions/plugins}{QML plugins}
-example:
-
-\snippet examples/qml/cppextensions/plugins/plugin.cpp plugin
-
-Once the plugin is built and installed, and includes a \l{Syntax of a qmldir file}{qmldir file},
-the module can be imported from QML, like this:
-
-\snippet qml/imports/timeexample.qml import
-
-Unlike QML types defined by QML files, a QML type defined in a C++ extension plugin cannot be loaded by
-a module that is imported as a network resource.
-
-*/
-
diff --git a/src/qml/doc/src/modules/topic.qdoc b/src/qml/doc/src/modules/topic.qdoc
index 0356c3da73..337d8b5acf 100644
--- a/src/qml/doc/src/modules/topic.qdoc
+++ b/src/qml/doc/src/modules/topic.qdoc
@@ -26,47 +26,63 @@
 ****************************************************************************/
 /*!
 \page qtqml-modules-topic.html
-\title Writing Extension Modules For QML
-\brief Description of how to write extension modules for QML
+\title QML Modules
+\brief Description of how to write modules for QML
 
-A QML module is an extension to QML which can be imported by clients.  A QML
-module can contain QML documents which provide type definitions, JavaScript
-files which provide functionality, and C++ plugins which can provide QML types,
-invokable functions, and other functionality.  The module system provided by
-QML allows functionality to be grouped into modules which can be loaded by
-applications which need them, with zero impact upon applications which do not.
+A module is a collection of content files that can be imported as a unit into a QML
+application. Modules can be used to organize QML content into independent groups,
+and they use a versioning mechanism that allows modules to be independently upgraded.
 
-A QML module must be imported by client QML application developers using an
-\l{qtqml-syntax-imports.html}{Import Statements}.  Some imports must be
-qualified (that is, the imported type or file must be given an identifier),
-while others do not.
+Modules may contain QML files, JavaScript files and/or QML plugins written in C++. Grouping files
+into modules enables:
 
-The Qt Quick module provides a QML module called QtQuick which can be imported
-via the familiar
-\code
-import QtQuick 2.0
-\endcode
+\list
+\li The sharing of common QML types within a project - for example, a group of UI components that
+    are used by different windows
+\li The distribution of QML-based libraries
+\li The modularization of distinct features, so that applications only load the libraries necessary
+    for their individual needs
+\endlist
 
-import statement.
+A module may contain QML, JavaScript and/or C++ files. To access the types and functionality within
+a module, the module must be imported with an \l{Import Statements}{import} statement.
 
-QML modules are exposed to the QML type system via a module description file
-called a "qmldir" file.
 
-\section1 Packaging QML and JavaScript Files
+\section1 Located Modules
 
-A QML document implicitly defines a QML object type.  Clients can create
-reusable components by defining types as QML documents and exposing them
-to the type system directly.  QML extension module developers can provide
-QML object types defined in QML documents to clients also.
+A located module is one that is imported by a quoted URL string that refers to the
+local file system path of the module or the network URL location of the module.
 
-QML extension module developers can also provide functionality in JavaScript
-files.  When imported directly, JavaScript files must be imported with a
-qualifier; conversely, when providing a JavaScript file in a QML extension
-module, the module author must provide the qualifier.
+Using this mechanism, any directory of QML files can easily be shared as a module without any
+configuration or installation. Additionally, such modules can be loaded remotely as a network
+resource if it includes a qmldir file with the necessary metadata.
+
+See \l{qtqml-modules-locatedmodules.html}{Located Modules} for more information.
+
+
+\section1 Installed Modules
+
+An installed module is one that is imported by a URI in the form of a dotted identifier string - for
+example, "com.mycompany.mymodule" - that uniquely identifies the module to the QML engine. This
+allows a module to be imported by an identifier rather than a file system path.
+
+To enable the engine to find an installed module, the module should be available in the
+\l{qtqml-syntax-imports.html#qml-import-path}{import path}.
+
+See \l{qtqml-modules-installedmodules.html}{Installed Modules} for more information.
+
+
+\section1 Adding Module Metadata with a qmldir File
+
+A qmldir file is a plain text file that describes a module's metadata and contents. This file and
+the associated module contents (QML documents, JavaScript files, and C++ plugins) must be placed
+somewhere into the \l{qtqml-syntax-imports.html#qml-import-path}{QML import path}.
+
+This is required for a module if it is to be imported by URI or as a network resource. It is also
+necessary for exporting JavaScript files and object types defined in C++.
+
+See \l{qtqml-modules-qmldir.html}{Adding Module Metadata with a qmldir File} for more information.
 
-See the documentation about \l{qtqml-javascript-topic.html}
-{integrating QML and JavaScript} for more information about what types of
-functionality can be implemented in JavaScript.
 
 \section1 Providing Types And Functionality In A C++ Plugin
 
@@ -81,12 +97,6 @@ the QML engine when it loads the plugin.  This initialization function must
 register any types that the plugin provides, but must not do anything else
 (for example, instantiating QObjects is not allowed).
 
-\section1 Syntax Of A qmldir File
-
-The standard way to expose a QML extension module to the QML type system is to
-write a \c qmldir file which describes to the QML engine what the module
-contains.  The qmldir file and the associated content (QML documents,
-JavaScript files, and C++ plugins) must be placed somewhere into the
-\l{qtqml-syntax-imports.html#qml-import-path}{QML import path}.
+See \l{qtqml-modules-cppplugins.html}{Creating C++ Plugins For QML} for more information.
 
 */
diff --git a/src/qml/doc/src/qtqml.qdoc b/src/qml/doc/src/qtqml.qdoc
index 9e30ac3d3b..c69a884e2e 100644
--- a/src/qml/doc/src/qtqml.qdoc
+++ b/src/qml/doc/src/qtqml.qdoc
@@ -90,9 +90,10 @@ types, animation classes, and canvas integration) for the QML language.
 
     \li \l{qtqml-modules-topic.html}{QML Modules}
         \list
-        \li \l{qtqml-modules-topic.html#syntax-of-a-qmldir-file}{Packaging QML and JavaScript Files}
-        \li \l{qtqml-modules-cppplugins.html#creating-a-plugin}{Providing Types and Functionality in a C++ Plugin}
-        \li \l{qtqml-modules-qmldir.html}{Syntax of a qmldir File}
+        \li \l{qtqml-modules-locatedmodules.html}{Located Modules}
+        \li \l{qtqml-modules-installedmodules.html}{Installed Modules}
+        \li \l{qtqml-modules-qmldir.html}{Adding Module Metadata with a qmldir file}
+        \li \l{qtqml-modules-cppplugins.html}{Providing Types and Functionality in a C++ Plugin}
         \endlist
 
     \li \l{qtqml-documents-topic.html}{QML Documents}
diff --git a/src/qml/doc/src/syntax/imports.qdoc b/src/qml/doc/src/syntax/imports.qdoc
index 73fe95c768..89eab8979c 100644
--- a/src/qml/doc/src/syntax/imports.qdoc
+++ b/src/qml/doc/src/syntax/imports.qdoc
@@ -62,7 +62,34 @@ import com.company.module
 \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.
 
 
-\section2 Namespace Imports
+\section1 Debugging
+
+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.
+
+
+\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 Namespaced Imports
 
 
 
@@ -106,9 +133,9 @@ Note that multiple modules can be imported into the same namespace in the same w
 
 
 
-\section2 Relative Directory Imports
+\section1 Relative Directory Imports
 
-\section2 JavaScript File Imports
+\section1 JavaScript File Imports
 
 
 JavaScript files must always be imported with a named import:
@@ -159,8 +186,8 @@ Window {
 \endqml
 
 
-\section2 Version Specification
+\section1 Version Specification
 
-\section2 Import Qualifier
+\section1 Import Qualifier
 
 */