doc

Task-number: QTBUG-7125

2 files changed, 59 insertions, 18 deletions

diff --git a/doc/src/declarative/extending.qdoc b/doc/src/declarative/extending.qdoc
index 056b8ab..84d7089 100644
--- a/doc/src/declarative/extending.qdoc
+++ b/doc/src/declarative/extending.qdoc
@@ -54,6 +54,7 @@ QML for their own independent use.
 \tableofcontents
 
 \section1 Adding Types
+\target adding-types
 
 \snippet examples/declarative/extending/adding/example.qml 0
 
@@ -71,11 +72,11 @@ Custom C++ types are made available to QML using these two macros:
 \quotation
 \code
 #define QML_DECLARE_TYPE(T)
-#define QML_DEFINE_TYPE(URI,VMAJ,VFROM,VTO,QmlName,T)
+#define QML_DEFINE_TYPE(URI,VMAJ,VMIN,QmlName,T)
 \endcode
 
 Register the C++ type \a T with the QML system, and make it available in QML
-under the name \a QmlName in library URI version VMAJ.VFROM to VMAJ.VTO.
+under the name \a QmlName in library URI version VMAJ.VMIN.
 \a T and \a QmlName may be the same.
 
 Generally the QML_DECLARE_TYPE() macro should be included immediately following
@@ -87,6 +88,9 @@ Type \a T must be a concrete type that inherits QObject and has a default
 constructor.
 \endquotation
 
+Types can be registered by libraries (such as Qt does), application code,
+or by plugins (see QmlModulePlugin).
+
 Once registered, all of the \l {Qt's Property System}{properties} of a supported
 type are available for use within QML.  QML has intrinsic support for properties
 of these types:
diff --git a/doc/src/declarative/modules.qdoc b/doc/src/declarative/modules.qdoc
index 1491fea..ec36fe7 100644
--- a/doc/src/declarative/modules.qdoc
+++ b/doc/src/declarative/modules.qdoc
@@ -46,24 +46,51 @@
 A \bold module is a collection of QML types.
 
 To use types from a module it must be imported using the \c import statement. Successive
-import statements override earlier import statements.
+import statements override earlier import statements, however, since imports have version
+qualifiers, changes in modules do not alter the semantics of imports.
 
-\section1 Importing Built-in Types
+\section1 Importing Types Defined in C++
 
-To use built-in types, you must import the module defining them.
-For example, to use types from Qt, import it:
+Types \link adding-types defined in C++\endlink can be from types your application defines, standard QML types,
+or types defined in plugins. To use any such types, you must import
+the module defining them.  For example, to use types from Qt, import it:
 
 \code
 import Qt 4.6
 \endcode
 
 This makes available all types in Qt that were available in Qt 4.6, regardless of the
-actual version of Qt executing the QML.
+actual version of Qt executing the QML. So even if Qt 4.7 adds a type that would conflict
+with a type you defined while using 4.6, that type is not imported, so there is no conflict.
 
-Modules can be compiled-in (such as the Qt module), or they can be
-defined in QML files.
+Types defined by plugins are made using QmlModulePlugin.
 
-\section1 Importing QML Files
+
+\section1 Importing Types Defined in QML
+
+When importing types \link components defined using QML\endlink, the syntax depends
+on whether or not the types are installed on the system.
+
+\section2 Installed QML Files
+
+To import types defined in QML files that are installed on the system running the
+QML, a URI import is used:
+
+\code
+import com.nokia.Example 1.0
+\endcode
+
+Files imported in this way are found on the paths added by QmlEngine::addImportPath(),
+which by default only inludes \c $QTDIR/qml, so the above would make available those types
+defined in \c $QTDIR/qml/com/nokia/Example which are specified as being in version 1.0.
+
+The specification of types to versions is given by a special file, \c qmldir which must
+exist in the module directory. The syntax is described below.
+
+The \c -L option to the \l {qmlviewer}{viewer} application also adds paths to the import path.
+
+
+\section2 Local QML Files
 
 To import types defined in QML files in directories relative to the file importing them,
 a quoted import directory is used:
@@ -75,18 +102,27 @@ import "path"
 This allows all components defined in the directory \c path to be used in
 the component where this statement appears.
 
-To import types defined in QML files that are installed somewhere on the system,
-an unquoted URI is used:
+In this case, and only this case, it is not necessary for the module directory to include
+a \c qmldir file, nor is it necessary to provide a version qualifier. The basis of this is
+that the files in the subdirectory are assumed to be packaged with the importer, and therefore
+they form a single versioned unit.
+
+
+\section2 Remote QML Files
+
+To import types defined in QML file at arbitrary network locations, a quoted absolute URL is used:
 
 \code
-import com.nokia.CoolStuff 1.0
+import "http://url/.../" 1.0
 \endcode
 
-This will access file in the directory \c com/nokia/CoolStuff/, found in some
-location determined outside QML. See QmlEngine::addImportPath() and the \c -L option
-to the \l {qmlviewer}{viewer} application.
+This works the same as for relative directory imports, except that the target location \e must
+include a \c qmldir file, and a version qualifier must be given.
+
 
-The directory of installed files must include a file \c qmldir which specifies the
+\section2 The \c qmldir File
+
+Directories of installed files and remote content must include a file \c qmldir which specifies the
 mapping from all type names to versioned QML files. It is a list of lines of the form:
 
 \code
@@ -105,7 +141,7 @@ since the \e first name-version match is used.
 Installed files do not need to import the module of which they are a part, as they can refer
 to the other QML files in the module as relative (local) files.
 
-Installed files \e must be referred to by version information described above,
+Installed and remote files \e must be referred to by version information described above,
 local files \e may have it.
 
 The versioning system ensures that a given QML file will work regardless of the version
@@ -113,6 +149,7 @@ of installed software, since a versioned import \e only imports types for that v
 leaving other identifiers available, even if the actual installed version might otherwise
 use those identifiers.
 
+
 \section1 Namespaces - Named Imports
 
 When importing content it by default imports types into the global namespace.