Doc: Update documentation for QML module definition file

A qmldir is unique for each major version of the module, which
was not made explicit in the documentation.

Task-number: QTBUG-60053
Change-Id: I53285c541981ae328373875704e98014a5889c4b
Reviewed-by: Michael Brasser <michael.brasser@live.com>
Reviewed-by: Robin Burchell <robin.burchell@crimson.no>
Reviewed-by: Shawn Rutledge <shawn.rutledge@qt.io>

1 files changed, 36 insertions, 29 deletions

diff --git a/src/qml/doc/src/qmllanguageref/modules/qmldir.qdoc b/src/qml/doc/src/qmllanguageref/modules/qmldir.qdoc
index 201cee16e6..f4046c91ac 100644
--- a/src/qml/doc/src/qmllanguageref/modules/qmldir.qdoc
+++ b/src/qml/doc/src/qmllanguageref/modules/qmldir.qdoc
@@ -35,9 +35,9 @@ There are two distinct types of \c qmldir 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
+This documentation covers only the second form of \c qmldir file, which
+lists the QML types, JavaScript files, and plugins that are available under a
+module. For more information about the first form of \c qmldir file, see
 \l{qtqml-syntax-directoryimports.html#directory-listing-qmldir-files}
 {directory listing qmldir files}.
 
@@ -280,22 +280,33 @@ 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
+All QML types that are exported for a particular major version are available
+with the latest version of the same major version. For example, if a module
+provides a \c MyButton type in version 1.0 and \c MyWindow type in version 1.1,
+clients importing version \c 1.1 of the module get to use the \c MyButton and
+\c MyWindow types. However, the reverse is not true: a type exported for a
+particular minor version cannot be used by importing an older or earlier minor
+version. In the example mentioned earlier, if the client had imported version
+\c 1.0 of the module, they can use the \c MyButton type only but not the
 \c MyWindow type.
 
+A module can offer multiple major versions but the clients have access
+to one major version only at a time. For example, importing
+\c{MyExampleModule 2.0} provides access to that major version only and not
+the previous major version. Although you can organize the artifacts that belong
+to different major versions under a sigle directory and a \c qmldir file, it is
+recommended to use different directories for each major version. If you
+choose to go with the earlier approach (one directory and a \c qmldir file),
+try to use the version suffix for the file names. For example, artifacts
+that belong to \c{MyExampleModule 2.0} can use \c .2 suffix in their file name.
+
 A version cannot be imported if no types have been explicitly exported for that
 version. If a module provides a \c MyButton type in version 1.0 and a
 \c MyWindow type in version 1.1, you cannot import version 1.2 or version 2.0 of
 that module.
 
-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.
+A type can be defined by different files in different minor versions. In this case,
+the most closely matching version is used when imported by clients.
 For example, if a module had specified the following types via its \c qmldir
 file:
 
@@ -304,17 +315,15 @@ 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
+a client who imports version \c 1.2 of \c ExampleModule can use the \c MyButton
+type definition provided by \c MyButton11.qml as it is the latest version of that
 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
+The version system ensures that a given QML file works regardless of the
+version of installed software, as a versioned import only imports types
 for that version, leaving other identifiers available, even if the actual
 installed version might otherwise provide those identifiers.
 
@@ -324,7 +333,6 @@ 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
@@ -332,16 +340,16 @@ 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
+the \c CustomButton QML object type in versions 2.0 and 2.1 of the
+module, with different implementations for each version. It specifies a plugin
+that 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.
+On Unix-like systems the QML engine attempts to load \c libexamplemodule.so
+as a QQmlExtensionPlugin, and on Windows it loads \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 a later version (under the same major version)
+of the module is imported.
 
 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
@@ -368,7 +376,6 @@ 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