Doc: Refactored and focused the Qt QML documentation.

Before it wasn't clear to what the module provided, especially
with the coupling of Qt QML and Qt Quick.

The doc is centered around these documentation:
-QML refernce: the language syntax and the application constructs
-JavaScript environment: the environment provided by the module
-Integration with C++: more about the engine and the C++ API
-QML Types and Classes reference (created by \qmlmodule and \module)

The distinction are made in the directory and the section titles in
the Qt QML landing page.

Change-Id: I033bfcbf8368b94ffa5ee4b1225bee74347f53eb
Reviewed-by: Martin Smith <martin.smith@digia.com>

5 files changed, 951 insertions, 0 deletions

diff --git a/src/qml/doc/src/qmllanguageref/modules/cppplugins.qdoc b/src/qml/doc/src/qmllanguageref/modules/cppplugins.qdoc
new file mode 100644
index 0000000000..af2a36c903
--- /dev/null
+++ b/src/qml/doc/src/qmllanguageref/modules/cppplugins.qdoc
@@ -0,0 +1,136 @@
+/****************************************************************************
+**
+** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/legal
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** Commercial License Usage
+** Licensees holding valid commercial Qt licenses may use this file in
+** accordance with the commercial license agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and Digia.  For licensing terms and
+** conditions see http://qt.digia.com/licensing.  For further information
+** use the contact form at http://qt.digia.com/contact-us.
+**
+** GNU Free Documentation License Usage
+** 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.  Please review the following information to ensure
+** the GNU Free Documentation License version 1.3 requirements
+** will be met: http://www.gnu.org/copyleft/fdl.html.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+\page qtqml-modules-cppplugins.html
+\title Creating C++ Plugins for QML
+\brief Description of how to write C++ plugins for QML
+
+\section1 Creating a Plugin
+
+    The \l{QQmlEngine}{QML engine} load C++ plugins for QML.
+    Such plugins are usually provided in a QML extension module, and can
+    provide types and functionality for use by clients in QML documents
+    which import the module.
+
+    QQmlExtensionPlugin is a plugin interface that makes it possible to
+    create QML extensions that can be loaded dynamically into QML applications.
+    These extensions allow custom QML types to be made available to the
+    QML engine.
+
+    To write a QML extension plugin:
+    \list 1
+    \li Subclass QQmlExtensionPlugin
+        \list
+            \li Use the Q_PLUGIN_METADATA() macro to register the plugin with
+                the Qt meta object system
+            \li Override the \l{QQmlExtensionPlugin::}{registerTypes()} method
+                and call qmlRegisterType() to register the types to be exported
+                by the plugin
+        \endlist
+    \li Write a project file for the plugin
+    \li Create a \l{Module Definition qmldir Files}{qmldir file} to
+        describe the plugin
+    \endlist
+
+    QML extension plugins are for either application-specific or library-like
+    plugins. Library plugins should limit themselves to registering types, as
+    any manipulation of the engine's root context may cause conflicts or other
+    issues in the library user's code.
+
+\section1 Plugin Example
+
+    Suppose there is a new \c TimeModel C++ class that should be made available
+    as a new QML type. It provides the current time through \c hour and \c minute
+    properties.
+
+    \snippet qml/plugins/plugin.cpp 0
+    \dots
+
+    To make this type available, we create a plugin class named \c QExampleQmlPlugin
+    which is a subclass of \l QQmlExtensionPlugin. It overrides the
+    \l{QQmlExtensionPlugin::}{registerTypes()} method in order to register the \c TimeModel
+    type using qmlRegisterType(). It also uses the Q_PLUGIN_METADATA() macro in the class
+    definition to register the plugin with the Qt meta object system using a unique
+    identifier for the plugin.
+
+    \snippet qml/plugins/plugin.cpp plugin
+
+    The \c TimeModel class receives a \c{1.0} version of this plugin library, as
+    a QML type called \c Time. The Q_ASSERT() macro can ensure the type namespace is
+    imported correctly by any QML components that use this plugin. The
+    \l{Defining QML Types from C++} article has more information about registering C++
+    types into the runtime.
+
+    For this example, the TimeExample source directory is in
+    \c{imports/TimeExample}.  The plugin's type namespace will mirror
+    this structure, so the types are registered into the namespace
+    "TimeExample".
+
+    Additionally, the project file, in a \c .pro file, defines the project as a plugin library,
+    specifies it should be built into the \c imports/TimeExample directory, and registers
+    the plugin target name and various other details:
+
+    \code
+    TEMPLATE = lib
+    CONFIG += qt plugin
+    QT += qml
+
+    DESTDIR = imports/TimeExample
+    TARGET = qmlqtimeexampleplugin
+    SOURCES += qexampleqmlplugin.cpp
+    \endcode
+
+    Finally, a \l{Module Definition qmldir Files}{qmldir file} is required
+    in the \c imports/TimeExample directory to describe the plugin and the types that it
+    exports. The plugin includes a \c Clock.qml file along with the \c qmlqtimeexampleplugin
+    that is built by the project (as shown above in the \c .pro file) so both of these
+    need to be specified in the \c qmldir file:
+
+    \quotefile qml/plugins/imports/TimeExample/qmldir
+
+    Once the project is built and installed, the new \c Time component is
+    accessible by any QML component that imports the \c TimeExample
+    module
+
+    \snippet qml/plugins/plugins.qml 0
+
+    The full source code is available in the \l {qml/plugins}{plugins example}.
+
+
+\section1 Reference
+
+    \list
+    \li \l {Writing QML Extensions with C++} - contains a chapter
+    on creating QML plugins.
+    \li \l{Defining QML Types from C++} - information about registering C++ types into
+    the runtime.
+    \li \l{How to Create Qt Plugins} - information about Qt plugins
+    \endlist
+
+
+*/
diff --git a/src/qml/doc/src/qmllanguageref/modules/identifiedmodules.qdoc b/src/qml/doc/src/qmllanguageref/modules/identifiedmodules.qdoc
new file mode 100644
index 0000000000..34d4b864a8
--- /dev/null
+++ b/src/qml/doc/src/qmllanguageref/modules/identifiedmodules.qdoc
@@ -0,0 +1,198 @@
+/****************************************************************************
+**
+** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/legal
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** Commercial License Usage
+** Licensees holding valid commercial Qt licenses may use this file in
+** accordance with the commercial license agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and Digia.  For licensing terms and
+** conditions see http://qt.digia.com/licensing.  For further information
+** use the contact form at http://qt.digia.com/contact-us.
+**
+** GNU Free Documentation License Usage
+** 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.  Please review the following information to ensure
+** the GNU Free Documentation License version 1.3 requirements
+** will be met: http://www.gnu.org/copyleft/fdl.html.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+/*!
+\page qtqml-modules-identifiedmodules.html
+\title Identified Modules
+\brief Creating and importing identified modules
+
+Identified modules are modules that are installed and identifiable to the QML
+engine by a URI in the form of a dotted identifier string, which should be
+specified by the module in its \c qmldir file.  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.
+
+When importing an identified module, an unquoted identifier is used, with a
+mandatory version number:
+
+\snippet qml/imports/installed-module.qml imports
+
+Identified modules must be installed into the
+\l{qtqml-syntax-imports.html#qml-import-path}{import path} in order to be found
+by the QML engine.
+
+\section1 Locally Installed Identified Modules
+
+A directory of QML and/or C++ files can be shared as an identified module if it
+contains a \l{qtqml-modules-qmldir.html}{qmldir file} with the module metadata
+and is installed into the QML import path.  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} and \l{qtqml-javascript-resources.html}
+{JavaScript resources} defined by the module.
+
+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.
+
+Alternatively, versioning for different types can be defined within a qmldir
+file itself, however this can make updating such a module more difficult (as a
+\c qmldir file merge must take place as part of the update procedure).
+
+
+\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 identified module, the
+directory must include a \l{qtqml-modules-qmldir.html}{qmldir file} that
+defines the module identifier, and 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
+module myapp.mycomponents
+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 Identified Modules
+
+Identified 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 resources provided by the module; it cannot access any types
+defined by C++ plugins in the module.
+
+
+\section1 Semantics of Identified Modules
+
+An identified module is provided with the following guarantees by the QML
+engine:
+\list
+\li other modules are unable to modify or override types in the module's
+    namespace
+\li other modules are unable to register new types into the module's
+    namespace
+\li usage of type names by clients will resolve deterministically to a given
+    type definition depending on the versioning specified and the import order
+\endlist
+
+This ensures that clients which use the module can be certain that the
+object types defined in the module will behave as the module author documented.
+
+An identified module has several restrictions upon it:
+\list
+\li an identified module must must be installed into the
+    \l{qtqml-syntax-imports.html#qml-import-path}{QML import path}
+\li the module identifier specified in the \l{qtqml-modules-qmldir.html}
+    {module identifier directive} must match the install path of the module
+    (relative to the QML import path, where directory separators are replaced
+    with period characters)
+\li the module must register its types into the module identifier type
+    namespace
+\li the module may not register types into any other module's namespace
+\li clients must specify a version when importing the module
+\endlist
+
+For example, if an identified module is installed into
+\c{$QML2_IMPORT_PATH/ExampleModule}, the module identifier directive must be:
+\code
+module ExampleModule
+\endcode
+
+If the strict module is installed into
+\c{$QML2_IMPORT_PATH/com/example/CustomUi}, the module identifier directive
+must be:
+\code
+module com.example.CustomUi
+\endcode
+
+Clients will then be able to import the above module with the following import
+statement (assuming that the module registers types into version 1.0 of its
+namespace):
+\qml
+import com.example.CustomUi 1.0
+\endqml
+
+*/
+
diff --git a/src/qml/doc/src/qmllanguageref/modules/legacymodules.qdoc b/src/qml/doc/src/qmllanguageref/modules/legacymodules.qdoc
new file mode 100644
index 0000000000..26981334b7
--- /dev/null
+++ b/src/qml/doc/src/qmllanguageref/modules/legacymodules.qdoc
@@ -0,0 +1,83 @@
+/****************************************************************************
+**
+** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/legal
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** Commercial License Usage
+** Licensees holding valid commercial Qt licenses may use this file in
+** accordance with the commercial license agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and Digia.  For licensing terms and
+** conditions see http://qt.digia.com/licensing.  For further information
+** use the contact form at http://qt.digia.com/contact-us.
+**
+** GNU Free Documentation License Usage
+** 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.  Please review the following information to ensure
+** the GNU Free Documentation License version 1.3 requirements
+** will be met: http://www.gnu.org/copyleft/fdl.html.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+\page qtqml-modules-legacymodules.html
+\title Legacy Modules
+\brief Description of legacy QML modules
+
+Legacy modules are modules whose specification \c qmldir file does not contain
+a module identifier directive.  A legacy module may be either installed into
+the QML import path (as an installed legacy module) or imported by clients with
+a relative import (as a located legacy module).  Clients are advised to avoid
+using legacy modules if possible.  Module developers should ensure they create
+identified modules and not legacy modules.
+
+\section1 Installed Legacy Modules
+
+An installed, non-identified module is automatically given an identifier by the
+QML engine.  This implicitly defined identifier is equal to the install path of
+the module (relative to the QML import path) where directory-separator
+characters are replaced with period characters.
+
+A non-identified module which is installed into the QML import path has the
+following semantics:
+\list
+\li it may be imported by clients via the implicit module identifier
+\li clients must specify a version when importing the module
+\li conflicting type names are resolved arbitrarily by the QML engine, and the
+    way in which conflicts are resolved is not guaranteed to stay the same
+    between different versions of QML
+\li other legacy modules may modify or override type definitions provided by
+    the installed legacy module
+\endlist
+
+\section1 Located Legacy Modules
+
+A non-identified module which is imported via a relative directory path
+import statement is loaded by the engine as a located legacy module.  The
+following semantics apply to located legacy modules:
+\list
+\li it may be imported by clients via a relative import path
+\li it is not mandatory for clients to specify a version when importing the
+    module
+\li if no import version is supplied by the client in the import statement,
+    no guarantees are given by the QML engine about which version of the
+    definition of a given type name will be imported
+\li conflicting type names are resolved arbitrarily by the QML engine, and the
+    way in which conflicts are resolved is not guaranteed to stay the same
+    between different versions of QML
+\li other legacy modules may modify or override type definitions provided by
+    the located legacy module
+\endlist
+
+A located legacy module may reside on the local file system or on the
+network and can be referred to by a URL that specifies the file system path or
+network URL.
+
+*/
+
diff --git a/src/qml/doc/src/qmllanguageref/modules/qmldir.qdoc b/src/qml/doc/src/qmllanguageref/modules/qmldir.qdoc
new file mode 100644
index 0000000000..de3698c533
--- /dev/null
+++ b/src/qml/doc/src/qmllanguageref/modules/qmldir.qdoc
@@ -0,0 +1,429 @@
+/****************************************************************************
+**
+** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/legal
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** Commercial License Usage
+** Licensees holding valid commercial Qt licenses may use this file in
+** accordance with the commercial license agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and Digia.  For licensing terms and
+** conditions see http://qt.digia.com/licensing.  For further information
+** use the contact form at http://qt.digia.com/contact-us.
+**
+** GNU Free Documentation License Usage
+** 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.  Please review the following information to ensure
+** the GNU Free Documentation License version 1.3 requirements
+** will be met: http://www.gnu.org/copyleft/fdl.html.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+/*!
+\page qtqml-modules-qmldir.html
+\title Module Definition qmldir Files
+\brief How to write a qmldir file which defines a QML module
+
+There are two distinct types of \c qmldir files:
+\list
+\li QML document directory listing files
+\li QML module definition files
+\endlist
+
+This documentation covers only the second form of \c qmldir file.  For more
+information about the first form of \c qmldir file, please see the
+documentation about
+\l{qtqml-syntax-directoryimports.html#directory-listing-qmldir-files}
+{directory listing qmldir files}.
+
+\section1 Contents of a Module Definition qmldir File
+
+A \c qmldir file which defines a module is a plain-text file which consists
+of the following commands:
+
+\table
+    \header
+        \li Command
+        \li Syntax
+        \li Usage
+
+    \row
+        \li Module Identifier Directive
+        \li
+            \code
+module <ModuleIdentifier>
+            \endcode
+        \li Declares the module identifier of the module.
+            The <ModuleIdentifier> is the (dotted URI notation) identifier
+            for the module, which must match the module's install path.
+
+            The \l{qtqml-modules-topic.html#the-module-identifier-directive}
+            {module identifier directive} must be the first line of the file.
+            Exactly one module identifier directive may exist in the \c qmldir
+            file.
+
+            Example:
+            \code
+module ExampleModule
+            \endcode
+
+    \row
+        \li Object Type Declaration
+        \li
+            \code
+<TypeName> <InitialVersion> <File>
+            \endcode
+        \li Declares a \l{qtqml-typesystem-objecttypes.html}{QML object type}
+            to be made available by the module.
+                \list
+                \li \c <TypeName> is the type being made available
+                \li \c <InitialVersion> 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
+
+            Zero or more object type declarations may exist in the \c qmldir
+            file, however each object type must have a unique type name within
+            any particular version of the module.
+
+            Example:
+            \code
+MyCustomType 1.0 MyCustomType.qml
+            \endcode
+
+    \row
+        \li Internal Object Type Declaration
+        \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.
+
+            Zero or more internal object type declarations may exist in the
+            \c qmldir file.
+
+            Example:
+            \code
+internal MyPrivateType MyPrivateType.qml
+         \endcode
+
+            This is necessary if the module may be imported remotely (see
+            \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 JavaScript Resource Declaration
+        \li
+            \code
+<ResourceIdentifier> <InitialVersion> <File>
+            \endcode
+        \li Declares a JavaScript file to be made available by the module.
+            The resource will be made available via the specified identifier
+            with the specified version number.
+
+            Zero or more JavaScript resource declarations may exist in the
+            \c qmldir file, however each JavaScript resource must have a unique
+            identifier within any particular version of the module.
+
+            Example:
+            \code
+MyScript 1.0 MyScript.js
+            \endcode
+
+            See the documentation about \l{qtqml-javascript-resources.html}
+            {defining JavaScript resources} and
+            \l{qtqml-javascript-imports.html}
+            {Importing JavaScript Resources In QML} for more information.
+
+    \row
+        \li C++ Plugin Declaration
+        \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
+
+            Zero or more C++ plugin declarations may exist in the \c qmldir
+            file, however since plugin loading is a relatively expensive
+            operation, clients are advised to specify at most a single plugin.
+
+            Example:
+            \code
+plugin MyPluginLibrary
+           \endcode
+
+    \row
+        \li Type Information Description File Declaration
+        \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 Comment
+        \li
+            \code
+# <Comment>
+            \endcode
+        \li Declares a comment. These are ignored by the engine.
+
+            Example:
+            \code
+# this is a comment
+            \endcode
+\endtable
+
+Each command in a \c qmldir file must be on a separate line.
+
+\section1 Versioning Semantics
+
+Types which are exported for a particular version are still made available if a
+later version is imported.  If a module provides a \c MyButton type in version
+1.0 and a \c MyWindow type in version 1.1, clients which import version 1.1 of
+the module will be able to use the \c MyButton type and the \c MyWindow type.
+However, the reverse is not true: a type exported for a particular version
+cannot be used if an earlier version is imported. If the client had imported
+version 1.0 of the module, they can use the \c MyButton type but \b not the
+\c MyWindow type.
+
+A type can be defined by different files in different versions. In this case,
+the most closely matching version will be used when imported by clients.
+For example, if a module had specified the following types via its \c qmldir
+file:
+
+\code
+module ExampleModule
+MyButton 1.0 MyButton.qml
+MyButton 1.1 MyButton11.qml
+MyButton 1.3 MyButton13.qml
+MyButton 2.0 MyButton20.qml
+MyRectangle 1.2 MyRectangle12.qml
+\endcode
+
+a client who imports version 1.2 of ExampleModule will get the \c MyButton
+type definition provided by \c MyButton11.qml as it is the most closely
+matching (i.e., latest while not being greater than the import) version of the
+type, and the \c MyRectangle type definition provided by \c MyRectangle12.qml.
+
+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{examples/qml/plugins} for an example that uses C++
+plugins.
+
+
+\section1 Example of a qmldir File
+
+One example of a \c qmldir file follows:
+
+\code
+module ExampleModule
+CustomButton 1.0 CustomButton.qml
+CustomButton 2.0 CustomButton20.qml
+CustomButton 2.1 CustomButton21.qml
+plugin examplemodule
+MathFunctions 2.0 mathfuncs.js
+\endcode
+
+The above \c qmldir file defines a module called "ExampleModule".  It defines
+the \c CustomButton QML object type in versions 1.1, 2.0 and 2.1 of the
+module, with different implementations in each version.  It specifies a plugin
+which must be loaded by the engine when the module is imported by clients, and
+that plugin may register various C++-defined types with the QML type system.
+On Unix-like systems the QML engine will attempt to load \c libexamplemodule.so
+as a QQmlExtensionPlugin, and on Windows it will attempt to load
+\c examplemodule.dll as a QQmlExtensionPlugin.  Finally, the \c qmldir file
+specifies a \l{qtqml-javascript-resources.html}{JavaScript resource} which is
+only available if version 2.0 or greater of the module is imported, accessible
+via the \c MathFunctions identifier.
+
+If the module is \l{qtqml-modules-identifiedmodules.html}{installed} into the
+QML import path, clients could import and use the module in the following
+manner:
+
+\qml
+import QtQuick 2.0
+import ExampleModule 2.1
+
+Rectangle {
+    width: 400
+    height: 400
+    color: "lightsteelblue"
+
+    CustomButton {
+        color: "gray"
+        text: "Click Me!"
+        onClicked: MathFunctions.generateRandom() > 10 ? color = "red" : color = "gray";
+    }
+}
+\endqml
+
+The \c CustomButton type used above would come from the definition specified in
+the \c CustomButton21.qml file, and the JavaScript resource identified by the
+\c MathFunctions identifier would be defined in the \c mathfuncs.js file.
+
+
+\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 \c{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/qmllanguageref/modules/topic.qdoc b/src/qml/doc/src/qmllanguageref/modules/topic.qdoc
new file mode 100644
index 0000000000..597e7b7ca3
--- /dev/null
+++ b/src/qml/doc/src/qmllanguageref/modules/topic.qdoc
@@ -0,0 +1,105 @@
+/****************************************************************************
+**
+** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/legal
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** Commercial License Usage
+** Licensees holding valid commercial Qt licenses may use this file in
+** accordance with the commercial license agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and Digia.  For licensing terms and
+** conditions see http://qt.digia.com/licensing.  For further information
+** use the contact form at http://qt.digia.com/contact-us.
+**
+** GNU Free Documentation License Usage
+** 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.  Please review the following information to ensure
+** the GNU Free Documentation License version 1.3 requirements
+** will be met: http://www.gnu.org/copyleft/fdl.html.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+\page qtqml-modules-topic.html
+\title QML Modules
+\brief Description of how to write modules for QML
+
+A QML module provides versioned types and JavaScript resources in a type
+namespace which may be used by clients who import the module.  The types which
+a module provides may be defined in C++ within a plugin, or in QML documents.
+Modules make use of the QML versioning system which allows modules to be
+independently updated.
+
+Defining of a QML module allows:
+\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
+\li Versioning of types and resources so that the module can be updated safely
+    without breaking client code
+\endlist
+
+
+\section1 Defining a QML Module
+
+A module is defined by a \l{qtqml-modules-qmldir.html}
+{module definition qmldir file}.  Each module has an associated type
+namespace, which is the module's identifier.  A module can provide QML object
+types (defined either by QML documents or via a C++ plugin) and JavaScript
+resources, and may be imported by clients.
+
+To define a module, a developer should gather together the various QML
+documents, JavaScript resources and C++ plugins which belong in the module
+into a single directory, and write an appropriate \l{qtqml-modules-qmldir.html}
+{module definition qmldir file} which should also be placed into the directory.
+The directory can then be installed into the
+\l{qtqml-syntax-imports.html#qml-import-path}{QML import path} as a module.
+
+Note that defining a module is not the only way to share common QML types
+within a project - a simple \l{qtqml-syntax-imports.html#directory-import}
+{QML document directory import} may also be used for this purpose.
+
+\section1 Supported QML Module Types
+
+There are two different types of modules supported by QML:
+\list
+\li \l{qtqml-modules-identifiedmodules.html}{Identified Modules}
+\li \l{qtqml-modules-legacymodules.html}{Legacy Modules} (deprecated)
+\endlist
+
+Identified modules explicitly define their identifier and are installed into
+QML import path.  Identified modules are more maintainable (due to type
+versioning) and are provided with type registration guarantees by the QML
+engine which are not provided to legacy modules.  Legacy modules are only
+supported to allow legacy code to continue to work with the latest version of
+QML, and should be avoided by clients if possible.
+
+Clients may import a QML module from within QML documents or JavaScript files.
+Please see the documentation about
+\l{qtqml-syntax-imports.html#module-namespace-imports}{importing a QML module}
+for more information on the topic.
+
+\section1 Providing Types and Functionality in a C++ Plugin
+
+An application which has a lot of logic implemented in C++, or which defines
+types in C++ and exposes them to QML, may wish to implement a QML plugin.  A
+QML extension module developer may wish to implement some types in a C++ plugin
+(as opposed to defining them via QML documents) to achieve better performance
+or for greater flexibility.
+
+Every C++ plugin for QML has an initialiatization function which is called by
+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).
+
+See \l{qtqml-modules-cppplugins.html}{Creating C++ Plugins For QML} for more information.
+
+*/