Document the usage of plugin parameters more explicitly.

This is especially important when writing about the nokia plugin
since it requires an app id and token.

Change-Id: I202a4df05d1d42cf6d3ca10da516b5d9e829c83f
Reviewed-by: Aaron McCarthy <aaron.mccarthy@nokia.com>

3 files changed, 33 insertions, 16 deletions

diff --git a/doc/src/places.qdoc b/doc/src/places.qdoc
index d4bb5929..b6a8020e 100644
--- a/doc/src/places.qdoc
+++ b/doc/src/places.qdoc
@@ -41,16 +41,20 @@
     \section1 Quickstart Tutorial
 
     \section2 Plugin Initialization
-    A \l Plugin is an abstraction for a backend.  One \l Plugin might access places from a REST server
-    while another may access places from a local database.  The following instantiates a Plugin element
-    by providing a name of "nokia".  The Plugin name identifies which backend to choose from.
-    Note that different Plugin backends may have different nuances and behaviours, refer to
-    the \l {Plugin references and parameters}{Plugin References} for these details.
+    A \l Plugin is an abstraction for a backend. One \l Plugin might access places from a
+    REST server while another may access places from a local database. The following
+    instantiates a \l Plugin element by providing a name of "nokia". The \l Plugin name
+    identifies which backend to choose from. Plugins may also be provided with a set of
+    \l {PluginParameter} {parameters}, which essentially takes the form of a set of
+    key-value pairs. The \l {PluginParameter} {parameters} that can be specified vary
+    among the different \l Plugin backends. For documentation on the possible \l
+    {PluginParameter} {parameters} and nuances of each \l Plugin, see the \l {Plugin
+    references and parameters}{Plugin References}.
 
     \snippet snippets/declarative/places.qml Initialize Plugin
 
-    See also the \l {Places (C++)}{overview for the C++ API} which
-    introduces aspects of the API in greater detail.
+    \note The Nokia plugin must be supplied with some mandatory parameters as outlined
+    in the \l {Mandatory Parameters} {Nokia Plugin} documentation.
 
     \section2 Searching
     Searching is accomplished via the \l PlaceSearchModel.  To instantiate a \l PlaceSearchModel we
diff --git a/doc/src/plugins/nokia.qdoc b/doc/src/plugins/nokia.qdoc
index 55c6a83f..156cd671 100644
--- a/doc/src/plugins/nokia.qdoc
+++ b/doc/src/plugins/nokia.qdoc
@@ -43,10 +43,6 @@ Note that accepting the terms and conditions only applies those terms and condit
 the Nokia geo services plugin and does not limit the use of the other geo services plugins that may
 be included with Qt.
 
-The Nokia geo services plugin requires an application id and token pair to authenticate the
-application with the Nokia services.  To obtain an application id and token pair visit
-\l {https://api.developer.nokia.com/}
-
 The Nokia geo services plugin can be loaded by using the plugin key "nokia".
 
 The online plugin uses the tiled map classes, which caches tile data in heap memory and texture
@@ -54,7 +50,8 @@ memory.
 
 \section1 Parameters
 
-The following table lists optional parameters that can be passed to the Nokia plugin.
+\section2 Mandatory parameters
+The following table lists mandatory parameters that \e must be passed to the Nokia plugin.
 \table
 \header
     \li Parameter
@@ -65,6 +62,18 @@ The following table lists optional parameters that can be passed to the Nokia pl
 \row
     \li token
     \li Client \e token part of the app_id/token pair for the service used for authentication by all managers.
+\endtable
+
+The Nokia geo services plugin requires an application id and token pair to authenticate the
+application with the Nokia services.  To obtain an application id and token pair visit
+\l {https://api.developer.nokia.com/}
+
+\section2 Optional parameters
+The following table lists optional parameters that can be passed to the Nokia plugin.
+\table
+\header
+    \li Parameter
+    \li Description
 \row
     \li proxy
     \li Proxy server URL used by all managers. For usage of the system proxy just pass "system" as value.
@@ -112,15 +121,15 @@ The following table lists optional parameters that can be passed to the Nokia pl
 \section1 Parameter Usage Example
 
 The following two examples show how to create a Nokia plugin instance with
-a proxy server set for use with routing, and a routing token unique to the
-application.
+parameters supplied for an application id and token, which is required for
+authentication.
 
 \section2 QML
 
 \code
 Plugin {
     name: "nokia"
-    PluginParameter { name: "proxy"; value: "system" }
+    PluginParameter { name: "app_id"; value: "myapp" }
     PluginParameter { name: "token"; value: "abcdefg12345" }
 }
 \endcode
@@ -129,7 +138,7 @@ Plugin {
 
 \code
 QMap<QString,QVariant> params;
-params["proxy"] = "system";
+params["app_id"] = "myapp";
 params["token"] = "abcdefg12345";
 
 QGeoServiceProvider *gsp = new QGeoServiceProvider("nokia", params);
diff --git a/doc/src/snippets/declarative/places.qml b/doc/src/snippets/declarative/places.qml
index 2fe1648e..4f7f42e8 100644
--- a/doc/src/snippets/declarative/places.qml
+++ b/doc/src/snippets/declarative/places.qml
@@ -50,6 +50,10 @@ Item {
     Plugin {
         id: myPlugin
         name: "nokia"
+        //specify plugin parameters if necessary
+        //PluginParameter {...}
+        //PluginParameter {...}
+        //...
     }
     //! [Initialize Plugin]