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>

1 files changed, 49 insertions, 39 deletions

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.
 
 */