Unify the doc pages of all QtLocation examples

- Add the "Running the Example" section
- Reorder existing information as a consequence of the new section
- Reduce duplicated qdoc content

Change-Id: I1df91a385ce17394da4f2debb4171ade63ce3fcc
Reviewed-by: Venugopal Shivashankar <venugopal.shivashankar@digia.com>

5 files changed, 39 insertions, 28 deletions

diff --git a/src/location/doc/src/examples/declarative-mapviewer.qdoc b/src/location/doc/src/examples/declarative-mapviewer.qdoc
index f62f535d..8ba48112 100644
--- a/src/location/doc/src/examples/declarative-mapviewer.qdoc
+++ b/src/location/doc/src/examples/declarative-mapviewer.qdoc
@@ -33,22 +33,17 @@
     \brief The Map Viewer example shows how to display and interact with a map,
            search for an address, and find driving directions.
 
+    \image example-mapviewer.png
+
     This is a large example covering many basic uses of maps, positioning, and
     navigation services in Qt Location. This page is divided into sections
     covering each of these areas of functionality with snippets from the code.
 
-    The Map Viewer example can work with any of the available geo services plugins.  However, some
-    plugins may require additional \l {QtLocation::PluginParameter}{plugin parameters} in order to
-    function correctly.  \l {QtLocation::PluginParameter}{Plugin parameters} can be passed on the
-    command line using the \c {--plugin} argument, which takes the form:
+    \include examples-run.qdocinc
 
-    \code
-        --plugin.<parameter name> <parameter value>
-    \endcode
+    \include example-parameters.qdocinc
 
-    Refer to the documentation for each of the geo services plugins for details on what plugin
-    parameters they support. The default plugin used by this example is
-    \l {Qt Location Open Street Map Plugin}, which does not require any parameters.
+    \section1 Overview
 
     QML types shown in this example:
 
@@ -72,9 +67,7 @@
         \endlist
     \endlist
 
-    \image ../images/example-mapviewer.png
-
-    \section2 Displaying a Map
+    \section1 Displaying a Map
 
     Drawing a map on-screen is accomplished using the Map type, as shown
     below.
@@ -87,7 +80,7 @@
     with a set latitude and longitude. We also set the initial zoom level to 50% (halfway between
     the maximum and minimum).
 
-    \section2 Finding an Address (Geocoding)
+    \section1 Finding an Address (Geocoding)
 
     To locate a certain address or place on the map uses a process called
     geocoding. In order to perform a geocode operation, we first need to adjust
@@ -122,7 +115,7 @@
 
     \snippet mapviewer/map/MapComponent.qml geocode1
 
-    \section2 Directions and Travel Routes
+    \section1 Directions and Travel Routes
 
     Similar to the GeocodeModel, Qt Location also features the RouteModel type,
     which allows information about routes (for example driving directions) between two
diff --git a/src/location/doc/src/examples/declarative-places.qdoc b/src/location/doc/src/examples/declarative-places.qdoc
index 26bcd228..dc5ef8d0 100644
--- a/src/location/doc/src/examples/declarative-places.qdoc
+++ b/src/location/doc/src/examples/declarative-places.qdoc
@@ -35,6 +35,13 @@
 
     \image qml-places.png
 
+    The Places example demonstrates how to search for Places. In particular it shows
+    how further information such as reviews, images and related content can be retrieved.
+
+    \include examples-run.qdocinc
+
+    \include example-parameters.qdocinc
+
     \section1 Overview
 
     The Places example presents an application window displaying a map.  At the top of the window
@@ -60,19 +67,6 @@
     in the fields.  Click "Go!" to save the place.  To create a new category, select "Category"
     from the "New" menu and fill in the fields.  Click "Go!" to save the category.
 
-    The Places example can work with any of the available geo services plugins.  However, some
-    plugins may require additional \l {QtLocation::PluginParameter}{plugin parameters} in order to
-    function correctly.  \l {QtLocation::PluginParameter}{Plugin parameters} can be passed on the
-    command line using the \c {--plugin} argument, which takes the form:
-
-    \code
-        --plugin.<parameter name> <parameter value>
-    \endcode
-
-    Refer to the documentation for each of the geo services plugins for details on what plugin
-    parameters they support.  The HERE services plugin supplied with Qt requires an \e app_id and
-    \e token pair.  See "\l {Qt Location HERE Plugin}" for details.
-
     \section1 Displaying Categories
 
     Before search by category can be performed, the list of available categories needs to be
diff --git a/src/location/doc/src/examples/example-parameters.qdocinc b/src/location/doc/src/examples/example-parameters.qdocinc
new file mode 100644
index 00000000..2ae351ba
--- /dev/null
+++ b/src/location/doc/src/examples/example-parameters.qdocinc
@@ -0,0 +1,12 @@
+The example can work with any of the available geo services plugins.  However, some
+plugins may require additional \l {QtLocation::PluginParameter}{plugin parameters} in order to
+function correctly.  \l {QtLocation::PluginParameter}{Plugin parameters} can be passed on the
+command line using the \c {--plugin} argument, which takes the form:
+
+\badcode
+    --plugin.<parameter name> <parameter value>
+\endcode
+
+Refer to the documentation for each of the geo services plugins for details on what plugin
+parameters they support. The default plugin used by this example is
+\l {Qt Location Open Street Map Plugin}, which does not require any parameters.
diff --git a/src/location/doc/src/examples/places-list.qdoc b/src/location/doc/src/examples/places-list.qdoc
index 6248afa1..7ef02b99 100644
--- a/src/location/doc/src/examples/places-list.qdoc
+++ b/src/location/doc/src/examples/places-list.qdoc
@@ -33,6 +33,14 @@
     \brief The Places List example demonstrates how to search for and display a list of places using a \l ListView.
     \image places-list.png
 
+    \include examples-run.qdocinc
+
+    The \c {Places List} example demonstrates how to search for a list of places
+    in a certain area and displays the result using a \l ListView. In this particular case, a search
+    for places associated with the term \c pizza is performed.
+
+    \section1 Performing a Place Search
+
     To write a QML application that will show places in a list, we start by
     making the following import declarations.
 
diff --git a/src/location/doc/src/examples/places-map.qdoc b/src/location/doc/src/examples/places-map.qdoc
index cb144521..7796c8ba 100644
--- a/src/location/doc/src/examples/places-map.qdoc
+++ b/src/location/doc/src/examples/places-map.qdoc
@@ -38,6 +38,10 @@
     available, it uses Brisbane/Australia. Subsequently a search for places
     matching the term "pizza" is performed and each result shown on the map.
 
+    \include examples-run.qdocinc
+
+    \section1 Local Search
+
     To write the QML application that will show places on a map, we start by
     making the following import declarations.