Add an initial attempt at docs on the new runtime and imports.

1 files changed, 91 insertions, 46 deletions

diff --git a/doc/src/declarative/modules.qdoc b/doc/src/declarative/modules.qdoc
index 53de32c..f90e23b 100644
--- a/doc/src/declarative/modules.qdoc
+++ b/doc/src/declarative/modules.qdoc
@@ -42,14 +42,79 @@
 /*!
 \page qdeclarativemodules.html
 \title Modules
+\section1 QML Modules.
+QUERY: Is a directory with no qmldir really a module? Assumed NO.
 
-A \bold module is a collection of QML types.
+A \bold module is a collection of QML types. These types can be defined in QML, or in C++
+through a QDeclarativeExtensionPlugin. They can then be collected into a directory to comprise
+a module.
+
+Additionally a module can also be a collection of types which was compiled into your application, see \l{Extending QML in C++}.
+
+While a directory containing types can be used to organize QML components, QML modules also contain a \c qmldir file.
+This file provides a manifest of all types available in the module,
+and allows versioned imports (among other things). A directory containing only QML files or plugins behaves similarly
+to a module, but a QML module requires a \c qmldir file (unless it is written in C++ and compiled into your application).
+
+\section2 The \c qmldir File
+
+QML modules containing installed files and remote content require 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
+# <Comment>
+<TypeName> <InitialVersion> <File>
+plugin <Name> [<Path>]
+\endcode
+
+# <Comment> lines are ignored, and can be used for comments.
+
+<TypeName> <InitialVersion> <File> lines are used to add QML files as types.
+<TypeName> is the type being made available; <InitialVersion> is a version
+number like \c 4.0; <File> is the (relative)
+file name of the QML file defining the type. 
+
+plugin <Name> [<Path>] lines are used to add plugins (QDeclarativeExtensionPlugin subclasses
+written in C++) to the module. The line starts with the keyword 'plugin'; <Name> is the
+name of the library; <Path> is an optional argument specifying the full path to the directory
+containing the plugin file, if it is omitted then the directory is assumed to be the same as
+the directory of the qmldir file. Note that <Name> is not usually the same as the file name
+of the plugin binary, which is platform dependent e.g. the library MyAppTypes would produce a libMyAppTypes.so on linux and MyAppTypes.dll on windows. 
+
+The same type can be provided by different files in different versions, in which
+case later earlier versions (eg. 1.2) must precede earlier versions (eg. 1.0),
+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.
+If the module is imported from a remote location, those files must nevertheless be listed in
+the \c qmldir file. Internal files can be marked with the \c internal keyword, to ensure
+they are not visible outside the module:
+
+\code
+internal <TypeName> <File>
+\endcode
+
+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
+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
+use those identifiers.
+
+\section1 Importing Modules
 
 To use types from a module it must be imported using the \c import statement. Successive
 import statements override earlier import statements, however, since imports have version
 qualifiers, changes in modules do not alter the semantics of imports.
 
-\section1 Importing Types Defined in C++
+While it is possible to import some modules without specifying a version this is only advisable
+during prototyping, where version numbers mean very little. The rest of the time it is recommended that
+you take advantage of the versioning capabilities of the language.
+
+You can import a directory in the same way that you import a module, except that you cannot specify a version
+number. This will import all the types in that directory as QML files or as part of plugins.
 
 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
@@ -90,7 +155,7 @@ Installed plugins and QML files can both contribute types to the same module.
 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.
+The \c -L option to the \l {qmlviewer}{runtime} application also adds paths to the import path.
 
 
 \section2 Local QML Files
@@ -103,62 +168,31 @@ import "path"
 \endcode
 
 This allows all components defined in the directory \c path to be used in
-the component where this statement appears.
+the component where this statement appears. Because no version number is specified,
+all types in the directory will be imported.
 
-In this case, and only this case, it is not necessary for the module directory to include
+In this case, and only this case, it is not necessary for the 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:
+they form a single versioned unit. It is however recommended that you add a qmldir file and create
+a QML module, as this provides additional options such as more flexible versioning. If the directory
+is a module then you can use a version qualifier, like below
 
 \code
-import "http://url/.../" 1.0
+import "path" 1.0
 \endcode
 
-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.
-
 
-\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
-# <Comment>
-<TypeName> <InitialVersion> <File>
-\endcode
-
-<TypeName> is the type being made available; <InitialVersion> is a version
-number like \c 4.0; <File> is the (relative)
-file name of the QML file defining the type.
-
-The same type can be provided by different files in different versions, in which
-case later earlier versions (eg. 1.2) must precede earlier versions (eg. 1.0),
-since the \e first name-version match is used.
+\section2 Remote QML Files
 
-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.
-If the module is imported from a remote location, those files must nevertheless be listed in
-the \c qmldir file. Internal files can be marked with the \c internal keyword, to ensure
-they are not visible outside the module:
+To import types defined in QML file at arbitrary network locations, a quoted absolute URL is used:
 
 \code
-internal <TypeName> <File>
+import "http://url/.../" 1.0
 \endcode
 
-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
-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
-use those identifiers.
-
+This works the same as for relative directory imports, except that the target location contain a QML module (\e must
+include a \c qmldir file), and a version qualifier must be given.
 
 \section1 Namespaces - Named Imports
 
@@ -185,6 +219,17 @@ modules can be imported into the global namespace:
 import Qt 4.6 as Nokia
 import Ovi 1.0 as Nokia
 \endcode
+
+There is one special module, called Qt, which contains all of the types that are part of
+Qt Declarative. While it still needs to be imported, this module can be used in all QML
+files.
+
+While import statements are need to make any types available in QML, the directory of the
+current file is implicitly loaded. This is the exact same as if you had added 'import "."' to
+every QML file. The effect of this is that you can automatically use Types defined in C++ plugins
+or QML files if they reside in the same directory.
+
+
 */
 
 /*