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>

1 files changed, 198 insertions, 0 deletions

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