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, 429 insertions, 0 deletions

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