1 files changed, 105 insertions, 0 deletions
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.
+
+*/