Improve QtQml module documentation

General improvements, including:
  - fixing broken links
  - improving topic page content
  - fixing incorrect qdoc commands

Change-Id: I50b6733b51cdabf9cecd96046f6e7f41260a9a4b
Reviewed-by: Michael Brasser <michael.brasser@nokia.com>

8 files changed, 126 insertions, 50 deletions

diff --git a/src/qml/doc/src/cppintegration/topic.qdoc b/src/qml/doc/src/cppintegration/topic.qdoc
index 1a53345e93..1fd0cd7df4 100644
--- a/src/qml/doc/src/cppintegration/topic.qdoc
+++ b/src/qml/doc/src/cppintegration/topic.qdoc
@@ -48,22 +48,20 @@ You may want to mix QML and C++ for a number of reasons. For example:
 calling functions in a third-party C++ library)
 \li To access functionality in the QtQml or QtQuick modules (for example, to dynamically generate
 images using QQuickImageProvider)
-\li To write your own QML elements (whether for your applications, or for distribution to others)
+\li To write your own QML object types (whether for your applications, or for distribution to others)
 \endlist
 
-
 There are a number of ways to extend your QML application through C++. For example, you could:
 
 \list
 \li Load a QML component and manipulate it (or its children) from C++
 \li Embed a C++ object and its properties directly into a QML component (for example, to make a
 particular C++ object callable from QML, or to replace a dummy list model with a real data set)
-\li Define new QML elements (through QObject-based C++ classes) and create them directly from your
+\li Define new QML object types (through QObject-based C++ classes) and create them directly from your
 QML code
 \endlist
 
 
-
 \section1 Exposing C++ Types To QML
 
 QML types may be implemented in C++ and then exposed to the QML type system via
diff --git a/src/qml/doc/src/documents/topic.qdoc b/src/qml/doc/src/documents/topic.qdoc
index d395270452..ddb4fc4949 100644
--- a/src/qml/doc/src/documents/topic.qdoc
+++ b/src/qml/doc/src/documents/topic.qdoc
@@ -29,30 +29,88 @@
 \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 parts: its imports, and its object
-hierarchy definition. See the \l {qtqml-documents-structure.html}{Structure of a QML Document}
-for more information.
+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}.
 
-\section1 Documents as QML object type definitions
+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.
 
-Any QML document can also define a QML object type.
+\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.
 
-\section2 Defining a component with a .qml file
+In the following example, the client developer defines a \c Button type with
+a document in a file:
 
+\snippet qml/qml-extending-types/components/Button.qml 0
 
-\section2 Attributes exposed by components
+The \c Button type can then be used in an application:
 
+\table
+\row
+\li \snippet qml/qml-extending-types/components/application.qml 0
+\li \image qml-extending-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 Network Transparency
+\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.
+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
@@ -60,5 +118,10 @@ 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.
 
 */
diff --git a/src/qml/doc/src/modules/topic.qdoc b/src/qml/doc/src/modules/topic.qdoc
index 337d8b5acf..9a72d68a1f 100644
--- a/src/qml/doc/src/modules/topic.qdoc
+++ b/src/qml/doc/src/modules/topic.qdoc
@@ -47,7 +47,6 @@ into modules enables:
 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.
 
-
 \section1 Located Modules
 
 A located module is one that is imported by a quoted URL string that refers to the
@@ -83,7 +82,6 @@ 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.
 
-
 \section1 Providing Types And Functionality In A C++ Plugin
 
 An application which has a lot of logic implemented in C++, or which defines
diff --git a/src/qml/doc/src/qmltypereference.qdoc b/src/qml/doc/src/qmltypereference.qdoc
index 0cb3f31ada..01b2578c23 100644
--- a/src/qml/doc/src/qmltypereference.qdoc
+++ b/src/qml/doc/src/qmltypereference.qdoc
@@ -33,36 +33,36 @@ The Qt QML module provides the definition and implementation of the QML
 language, and it also provides some elementary QML types which provide the
 basis for further extensions to the QML language.
 
-
-
 The Qt QML module also provides the \c QtObject and \c Component types which
 may be used in QML documents, by default.  These types are non-visual and
 provide building-blocks for extensions to QML.
 
-
-
 \section1 The QtQml Import
 
 The types provided by the Qt QML module are only available in a QML document
 if that document imports the QtQml namespace (or if the document imports the
-QtQuick namespace, as noted below).
+\c QtQuick namespace, as noted below).
 
 The current version of the import provided by the Qt QML module is version 2.0,
 and thus it may be imported via the following statement:
 
-\tt{import QtQml 2.0}
+\qml
+import QtQml 2.0
+\endqml
 
-Most clients will never need to use the QtQml import, as all of the types and
-functionality provided by the QtQml namespace are also provided by the QtQuick
-namespace which may be imported as follows:
+Most clients will never need to use the \c QtQml import, as all of the types
+and functionality provided by the \c QtQml namespace are also provided by the
+\c QtQuick namespace which may be imported as follows:
 
-\tt{import QtQuick 2.0}
+\qml
+import QtQuick 2.0
+\endqml
 
-See the \l{Qt Quick} module documentation for more information about the
-QtQuick namespace and what it provides to QML application developers.
+See the \l{QtQuick}{Qt Quick} module documentation for more information about the
+\c QtQuick namespace and what it provides to QML application developers.
 
 The documentation for the types below applies equally to the types of the same
-name provided by the Qt Quick module, as they are in fact identical.
+name provided by the \l{QtQuick}{Qt Quick} module, as they are in fact identical.
 
 \section1 QtObject
 
@@ -96,8 +96,9 @@ instances of another type to be instantiated on-demand.  It may be given an
 \c id and it has a default property which is the object type to instantiate,
 but no other properties may be added to it.
 
-For example, the following QtObject has two different Component properties,
-and it uses those components to dynamically construct objects at run-time:
+For example, the following QtObject has two different \l Component
+properties, and it uses those components to dynamically construct objects at
+run-time:
 
 \code
     import QtQuick 2.0
diff --git a/src/qml/doc/src/qtqml.qdoc b/src/qml/doc/src/qtqml.qdoc
index 61df39245f..d3682e7de1 100644
--- a/src/qml/doc/src/qtqml.qdoc
+++ b/src/qml/doc/src/qtqml.qdoc
@@ -79,9 +79,9 @@ types, animation classes, and canvas integration) for the QML language.
 
     \li \l{qtqml-typesystem-topic.html}{The QML Type System}
         \list
-        \li \l{qtqml-typesystem-topic.html}{Basic Types}
+        \li \l{qtqml-typesystem-basictypes.html}{Basic Types}
         \li \l{qtqml-typesystem-topic.html#javascript-types}{JavaScript Types}
-        \li \l{qtqml-typesystem-topic.html#qml-object-types}{QML Object Types}
+        \li \l{qtqml-typesystem-objecttypes.html}{QML Object Types}
             \list
             \li \l{qtqml-documents-definetypes.html}{Defining Object Types from QML}
             \li \l{qtqml-cppintegration-registercpptypes.html}{Defining Object Types from C++}
diff --git a/src/qml/doc/src/typesystem/basictypes.qdoc b/src/qml/doc/src/typesystem/basictypes.qdoc
index e5f0c21439..060a22d82e 100644
--- a/src/qml/doc/src/typesystem/basictypes.qdoc
+++ b/src/qml/doc/src/typesystem/basictypes.qdoc
@@ -25,7 +25,7 @@
 **
 ****************************************************************************/
 /*!
-\page qtqml-basictypes.html
+\page qtqml-typesystem-basictypes.html
 \title QML Basic Types
 \brief Description of basic types provided by the Qt QML module
 
diff --git a/src/qml/doc/src/typesystem/objecttypes.qdoc b/src/qml/doc/src/typesystem/objecttypes.qdoc
index 9fb3f192a6..7b223f0632 100644
--- a/src/qml/doc/src/typesystem/objecttypes.qdoc
+++ b/src/qml/doc/src/typesystem/objecttypes.qdoc
@@ -32,10 +32,19 @@
 
 A QML object type is a type from which a QML object can be instantiated.
 
-In syntactic terms, a QML object type is one which can be used to declare an object by specifying the \e{type name} followed by a set of curly braces that encompasses the attributes of that object. This differs from \e {basic types}, which cannot be used in the same way. For example, \l Rectangle is a QML object type: it can be used to create \c Rectangle type objects. This cannot be done with primitive types such as \c int and \c bool, which are used to hold simple data types rather than objects.
-
-Custom QML object types can be defined by creating a .qml file that defines the type, as discussed in \l {qtqml-documents-definetypes.html}{Documents as QML object type definitions}, or by defining a QML type from C++ and registering the type with the QML engine, as discussed in \l{qtqml-registercpptypes.html}
-{Registering C++ Types With The QML Type System}.
+In syntactic terms, a QML object type is one which can be used to declare an
+object by specifying the \e{type name} followed by a set of curly braces that
+encompasses the attributes of that object. This differs from \e {basic types},
+which cannot be used in the same way. For example, \l Rectangle is a QML object
+type: it can be used to create \c Rectangle type objects. This cannot be done
+with primitive types such as \c int and \c bool, which are used to hold simple
+data types rather than objects.
+
+Custom QML object types can be defined by creating a .qml file that defines the
+type, as discussed in \l {qtqml-documents-definetypes.html}
+{Documents as QML object type definitions}, or by defining a QML type from C++
+and registering the type with the QML engine, as discussed in
+\l{qtqml-registercpptypes.html}{Registering C++ Types With The QML Type System}.
 
 
 \section1 Creating Object Types from QML
diff --git a/src/qml/doc/src/typesystem/topic.qdoc b/src/qml/doc/src/typesystem/topic.qdoc
index 657a311888..1de87b542d 100644
--- a/src/qml/doc/src/typesystem/topic.qdoc
+++ b/src/qml/doc/src/typesystem/topic.qdoc
@@ -30,12 +30,12 @@
 \brief Description of the QML type system
 
 The types which may be used in the definition of an object hierarchy in a QML
-document can come from various sources.
+document can come from various sources.  They may be:
 
 \list
-\li They may be provided natively by the QML language
-\li They may be registered by C++ plugins for QML
-\li They may be provided as QML documents by a plugin developer
+\li provided natively by the QML language
+\li registered via C++ by QML modules
+\li provided as QML documents by QML modules
 \endlist
 
 Furthermore, application developers can provide their own types, either by
@@ -48,20 +48,21 @@ for properties and instances of those types.
 
 \section1 Basic Types
 
-The Qt QML module provides support for various primitive types including
+The QML language has built-in support for various primitive types including
 integers, double-precision floating point numbers, strings, and boolean values.
 Objects may have properties of these types, and values of these types may be
 passed as arguments to methods of objects.
 
-See the \l{qtqml-basictypes.html}{Basic Types} documentation for more
-information about basic types, or the \l{qtqml-documents-properties.html}
+See the \l{qtqml-typesystem-basictypes.html}{Basic Types} documentation for
+more information about basic types, or the \l{qtqml-documents-properties.html}
 {QML Documents - Object Properties} documentation for more information about
 other available property types.
 
 
 \section1 JavaScript types
 
-JavaScript objects and arrays are supported by the QML engine. Any standard JavaScript type can be created and stored using the generic \l var type.
+JavaScript objects and arrays are supported by the QML engine. Any standard
+JavaScript type can be created and stored using the generic \l var type.
 
 For example, the standard \c Date and \c Array types are available, as below:
 
@@ -86,9 +87,15 @@ See \l {Using JavaScript Expressions with QML} for more details.
 
 \section1 QML Object Types
 
-A QML object type is a type from which a QML object can be instantiated.
-
-
+A QML object type is a type from which a QML object can be instantiated. QML
+object types are derived from \l QtObject, and are provided by QML modules.
+Applications can import these modules to use the object types they provide.
+The \c QtQuick module provides the most common object types needed to create
+user interfaces in QML.
 
+Finally, every QML document implicitly defines a QML object type, which can be
+re-used in other QML documents.  See the documentation about
+\l{qtqml-typesystem-objecttypes.html}{object types in the QML type system} for
+in-depth information about object types.
 
 */