Doc: Make documented QML imports follow Qt versioning

We can now pass parameters to qdoc commands - use them to automate
the version bumps for documented QML imports.

Also, improve the structure and language on QML module pages.

Change-Id: Id56d36a9bc550ab9a1aea1af6ff8da83e5e1feb9
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
Reviewed-by: Paolo Angelelli <paolo.angelelli@qt.io>

3 files changed, 113 insertions, 87 deletions

diff --git a/src/location/doc/src/qtlocation-qml.qdoc b/src/location/doc/src/qtlocation-qml.qdoc
index 38f43ef1..90f19c5a 100644
--- a/src/location/doc/src/qtlocation-qml.qdoc
+++ b/src/location/doc/src/qtlocation-qml.qdoc
@@ -1,6 +1,6 @@
 /****************************************************************************
 **
-** Copyright (C) 2017 The Qt Company Ltd.
+** Copyright (C) 2018 The Qt Company Ltd.
 ** Contact: https://www.qt.io/licensing/
 **
 ** This file is part of the documentation of the Qt Toolkit.
@@ -26,83 +26,103 @@
 ****************************************************************************/
 
 /*!
-    \qmlmodule QtLocation 5.11
+    \qmlmodule QtLocation \QtVer
     \title Qt Location QML Types
     \ingroup qmlmodules
-    \brief Provides QML types for mapping and location information
+    \brief Provides QML types for mapping and location information.
 
-\section1 Overview
+    \section1 Overview
 
-Provided that a position has been obtained, this module can add a
-\l{QtLocation::Map}{Map} with Places of Interest (POI) and
-\l{QtLocation::Place}{Places}. The user can be made aware of nearby features
-and related information, displayed graphically. Features on the \l Map can be
-places of business, entertainment, and so on.  They may include paths, roads,
-or forms of transport, enabling navigation optimization and assistance.
+    Provided that a position has been obtained, the Qt Location module
+    can add a \l{QtLocation::}{Map} with Places of Interest (POI) and
+    \l{QtLocation::Place}{Places}. The user can be made aware of nearby
+    features and related information, displayed on the map. These features
+    can be places of business, entertainment, and so on. They may include
+    paths, roads, or forms of transport, enabling navigation optimization
+    and assistance.
 
-To perform navigation we need \l {Route}s from start to destination. These routes
-are made up of segments, where each \l {QtLocation::RouteSegment}{RouteSegment}
-can be considered a navigation subtask: drive 100 meters, turn left. The beginning and
-end of each segment is a \e waypoint, that is, one part of our journey.
+    To perform navigation we need \l {Route}s from start to destination.
+    These routes are made up of segments, where each \l {QtLocation::}
+    {RouteSegment} can be considered a navigation subtask; for example,
+    "drive 100 meters", or "turn left". The beginning and end of each
+    segment is a \e waypoint, that is, one part of the journey.
 
-A typical use case for the API is a user looking for a particular type of
-place, say a restaurant. The user could enter a search string into the map
-application and respond to a list or display of results for restaurants
-"near" the device. The application could then be used to navigate to the
-restaurant using an optimized route that is aware of features in the
-environment that can help or hinder the journey. The navigation then
-proceeds with the user's progress monitored by means of the current
-\l Location. In the context of this API the map application would be aware
-of the location and size of various places and the location of the user.
-Plugins would supply the data required by the application to determine routes
-and navigation instructions. The \l Place types would hold information about the
-destination and surrounding objects including displayable representations.
-The \l Map type would enable this information to be displayed, panned,
-zoomed and so on. The \l Route would be determined by a plugin with each
-\l RouteSegment holding the navigation instructions guided by the updated
-current \l Location.
+    A typical use case for the API is a user looking for a particular type of
+    place, such as a restaurant; the user enters a search string into the map
+    application and is presented with a list of results for restaurants
+    "near" the device. The application can then be used to navigate to the
+    chosen destination using a route that is optimized according to features
+    in the environment that may help or hinder the journey. The navigation then
+    proceeds with the user's progress monitored by means of the current
+    location.
 
-\l {Plugin}s are a means of specifying which location-based service to use. For
-example, a plugin may allow connection to a provider's service that provides
-geocoding and routing information, which can be consumed by the application.
-There may be various GeoServices plugins for various tasks with some plugins
-providing more than one service. One QML \l Plugin must be created for each
-required GeoService plugin. Plugins are required for maps, routing and geocoding,
-and places, however the default plugin handles all four of these services. A plugin may
-require online access or may support on-board maps and data.
+    In short, the main QML types and their roles are as follows:
 
-\note Plugins may not provide features such as paging or relevance hints.
+    \list
 
-The following links provide more detailed information about maps and places:
+        \li The \l [QML] Place instances hold information about the
+            destination and surrounding objects, including displayable
+            representations.
 
-\table
-    \row
-        \li \l {Maps and Navigation (QML)}{Maps and Navigation}
-        \li Displaying maps and finding routes.
-    \row
-        \li \l {QML PLaces API} {Places}
-        \li Searching for and managing points of interest.
-\endtable
+        \li The \l [QML] Map enables the information contained in
+            \l [QML] {Place} objects to be displayed, panned, zoomed,
+            and so on.
 
-\section1 Common QML Types
+        \li The \l [QML] Route is be determined by a \e plugin, with each
+            \l [QML] RouteSegment holding the navigation instructions,
+            guided by the continuously updated current \l [QML] Location.
 
-\annotatedlist qml-QtLocation5-common
+    \endlist
 
-\section1 Maps QML Types
+    \section2 Plugins
 
-\annotatedlist qml-QtLocation5-maps
+    \l {Plugin}s supply the data required to calculate routes and navigation
+    instructions, and they are typically tied to a specific location-based
+    service. For example, a plugin may allow connecting to a service that
+    provides geocoding and routing information, which can be consumed by the
+    application.
 
-\section1 Navigation and Routing QML Types
+    There may be various GeoServices plugins for various tasks, with some
+    plugins providing more than one service. One QML \l Plugin instance must
+    be created for each GeoService plugin. Plugins are required for routing
+    and geocoding, maps, and places, however the default plugin handles all
+    four of these services. A plugin may require online access or it may
+    support on-board maps and data.
 
-\annotatedlist qml-QtLocation5-routing
+    \note Plugins may not provide features such as paging or relevance hints.
 
-\section1 Geocoding QML Types
+    \section2 Related Information
 
-\annotatedlist qml-QtLocation5-geocoding
+    The following links provide more information about maps and places:
 
-\section1 Places QML Types
+    \table
+        \row
+            \li \l {Maps and Navigation (QML)}{Maps and Navigation}
+            \li Displaying maps and finding routes
+        \row
+            \li \l {QML Places API} {Places}
+            \li Searching for and managing points of interest
+    \endtable
 
-\annotatedlist qml-QtLocation5-places
+    \section1 Common QML Types
 
-\section1 Alphabetical Listing of All QML Types
+    \annotatedlist qml-QtLocation5-common
+
+    \section1 Maps QML Types
+
+    \annotatedlist qml-QtLocation5-maps
+
+    \section1 Navigation and Routing QML Types
+
+    \annotatedlist qml-QtLocation5-routing
+
+    \section1 Geocoding QML Types
+
+    \annotatedlist qml-QtLocation5-geocoding
+
+    \section1 Places QML Types
+
+    \annotatedlist qml-QtLocation5-places
+
+    \section1 Alphabetical Listing of All QML Types
 */
diff --git a/src/location/doc/src/qtlocation.qdoc b/src/location/doc/src/qtlocation.qdoc
index 77c2cd99..059d03f2 100644
--- a/src/location/doc/src/qtlocation.qdoc
+++ b/src/location/doc/src/qtlocation.qdoc
@@ -87,10 +87,10 @@ The Qt Location API enables you to:
 
 To load the Qt Location module, add the following statement to your .qml files
 
-\code
-    import QtPositioning 5.11
-    import QtLocation 5.11
-\endcode
+\qml \QtVer
+import QtPositioning \1
+import QtLocation \1
+\endqml
 
 The QtLocation QML module depends on the QtPositioning QML module.
 Therefore every QML application that imports the QtLocation QML module must always
diff --git a/src/positioning/doc/src/qtpositioning-qml.qdoc b/src/positioning/doc/src/qtpositioning-qml.qdoc
index 7c9567cb..0c84484b 100644
--- a/src/positioning/doc/src/qtpositioning-qml.qdoc
+++ b/src/positioning/doc/src/qtpositioning-qml.qdoc
@@ -1,6 +1,6 @@
 /****************************************************************************
 **
-** Copyright (C) 2017 The Qt Company Ltd.
+** Copyright (C) 2018 The Qt Company Ltd.
 ** Contact: https://www.qt.io/licensing/
 **
 ** This file is part of the documentation of the Qt Toolkit.
@@ -26,40 +26,46 @@
 ****************************************************************************/
 
 /*!
-    \qmlmodule QtPositioning 5.11
+    \qmlmodule QtPositioning \QtVer
     \title Qt Positioning QML Types
     \ingroup qmlmodules
-    \brief Provides QML types for position information
+    \brief Provides QML types for position information.
 
-\section1 Overview
+    \section1 Overview
 
-The identifying string for this module is \e QtPositioning. To use include the following import
-statement in the QML file.
+    The identifying string for this module is \e QtPositioning. To use the QML
+    from this module, include the following import statement in the QML file:
 
-\snippet doc_src_qtpositioning.qml import
+    \qml \QtVer
+    import QtPositioning \1
+    \endqml
 
-\section2 Positioning QML Concepts
+    \section2 Positioning QML Concepts
 
-Position information can come from a variety of sources including satellites,
-wifi, text files and so on. The position is described by the latitude,
-the longitude, and the altitude in meters. For more information see
-\l {http://en.wikipedia.org/wiki/Geographic_coordinate}{Geographic Coordinate}.
+    Position information can come from a variety of sources including
+    satellites, Wi-Fi, text files and so on. The position is described by the
+    latitude, longitude, and the altitude in meters. For more information, see
+    the Wikipedia page on
+    \l {http://en.wikipedia.org/wiki/Geographic_coordinate}
+    {Geographic Coordinates}.
 
-The QML position is stored in a \l {coordinate} which contains the
-latitude, longitude and altitude of the device.  The \l {QtPositioning::Location}{Location} contains
-this \l {coordinate} and adds an address, it also has a bounding box which
-defines the recommended viewing region when displaying the location.
+    The QML position is stored in a \l {coordinate} which contains the
+    latitude, longitude and altitude of the device.  The \l {QtPositioning::}
+    {Location} contains this \l {coordinate} and adds an address, and also has
+    a bounding box which defines the recommended viewing region when displaying
+    the location.
 
-Now that the device has a position, with regular updates the API can determine
-the speed and heading of the device. It can also define a box or a circle that can
-produce a notification when the device either leaves or enters that region.
+    Now that the device has a position, with regular updates the API can
+    determine the speed and heading of the device. It can also define a
+    box-shaped or circular region that triggers notifications when the device
+    either leaves or enters that region.
 
-More detailed information retrieving the current position can be found under
-\l {Positioning (QML)}{Location Positioning via QML}
+    More detailed information on retrieving the current position can be found
+    under \l {Positioning (QML)}{Location Positioning via QML}.
 
-\section1 Basic Types
+    \section1 Basic Types
 
-\annotatedlist qml-QtPositioning5-basictypes
+    \annotatedlist qml-QtPositioning5-basictypes
 
-\section1 Alphabetical Listing of All QML Types
+    \section1 Alphabetical Listing of All QML Types
 */