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

diff --git a/src/qml/doc/src/qmllanguageref/documents/topic.qdoc b/src/qml/doc/src/qmllanguageref/documents/topic.qdoc
new file mode 100644
index 0000000000..f8a402476c
--- /dev/null
+++ b/src/qml/doc/src/qmllanguageref/documents/topic.qdoc
@@ -0,0 +1,127 @@
+/****************************************************************************
+**
+** 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-documents-topic.html
+\title QML Documents
+\brief Description of QML documents
+
+A QML document is a string which conforms to QML document syntax.  A document
+defines a QML object type.  A document is generally loaded from a \c ".qml"
+file stored either locally or remotely, but can be constructed manually in
+code.  An instance of the object type defined by a document may be created
+using a \l Component in QML code, or a \l QQmlComponent in C++.
+Alternatively, if the object type is explicitly exposed to the QML type system
+with a particular type name, the type may be used directly in object
+declarations in other documents.
+
+The ability to define re-usable QML object types in documents is an important
+enabler to allow clients to write modular, highly readable and maintainable
+code.
+
+\section1 Structure of a QML Document
+
+A QML document consists of two sections: the imports section, and the object
+declaration section.  The imports section in a document contains import
+statements that define which QML object types and JavaScript resources the
+document is able to use.  The object declaration section defines the object
+tree to be created when instantiating the object type defined by the document.
+
+An example of a simple document is as follows:
+
+\qml
+import QtQuick 2.0
+
+Rectangle {
+    width: 300
+    height: 200
+    color: "blue"
+}
+\endqml
+
+See the \l {qtqml-documents-structure.html}{Structure of a QML Document}
+for more information on the topic.
+
+\section2 Syntax of the QML Language
+
+The object declaration section of the document must specify a valid object
+hierarchy with appropriate \l {qtqml-syntax-basics.html}{QML syntax}.  An
+object declaration may include the specification of custom
+\l{qtqml-syntax-objectattributes.html}{object attributes}.  Object method
+attributes may be specified as JavaScript functions, and object property
+attributes may be assigned \l{qtqml-syntax-propertybinding.html}
+{property binding expressions}.
+
+Please see the documentation about the \l{qtqml-syntax-basics.html}
+{syntax of QML} for more information about valid syntax, and see the
+documentation about \l{qtqml-javascript-topic.html}
+{integrating QML and JavaScript} for in-depth information on that topic.
+
+\section1 Defining Object Types through QML Documents
+
+As described briefly in the previous section, a document implicitly defines
+a QML object type.  One of the core principles of QML is the ability to define
+and then re-use object types.  This improves the maintainability of QML code,
+increases the readability of object hierarchy declarations, and promotes
+separation between UI definition and logic implementation.
+
+In the following example, the client developer defines a \c Button type with
+a document in a file:
+
+\snippet ../src/quick/doc/snippets/qml/qml-extending-types/components/Button.qml 0
+
+The \c Button type can then be used in an application:
+
+\table
+\row
+\li \snippet ../src/quick/doc/snippets/qml/qml-extending-types/components/application.qml 0
+\li \image button-types.png
+\endtable
+
+Please see the documentation about \l{qtqml-documents-definetypes.html}
+{defining object types in documents} for in-depth information on the
+topic.
+
+\section1 Resource Loading and Network Transparency
+
+It is important to note that QML is network-transparent.  Applications can
+import documents from remote paths just as simply as documents from local
+paths.  In fact, any \c url property may be assigned a remote or local URL,
+and the QML engine will handle any network communication involved.
+
+Please see the \l{qtqml-documents-networktransparency.html}
+{Network Transparency} documentation for more information about network
+transparency in imports.
+
+\section1 Scope and Naming Resolution
+
+Expressions in documents usually involve objects or properties of objects,
+and since multiple objects may be defined and since different objects may have
+properties with the same name, some predefined symbol resolution semantics must
+be defined by QML.  Please see the page on \l{qtqml-documents-scope.html}
+{scope and symbol resolution} for in-depth information about the topic.
+
+*/