Docs: Bug-6690 fixes. General doc fixes.

Change-Id: I93680ae2da913b67e8a2c22826f43f84ecb4c863
Reviewed-by: abcd <amos.choy@nokia.com>
Reviewed-by: Peter Yard <peter.yard@nokia.com>

15 files changed, 246 insertions, 37 deletions

diff --git a/doc/src/examples/declarative-places.qdoc b/doc/src/examples/declarative-places.qdoc
index 509d6643..45f66eeb 100644
--- a/doc/src/examples/declarative-places.qdoc
+++ b/doc/src/examples/declarative-places.qdoc
@@ -27,7 +27,7 @@
 
 /*!
     \example declarative/places
-    \title Places (QML)
+    \title Places (QML) Example
     \ingroup qtlocation-examples
 
     \brief The Places example demonstrates how to search for Places and access
@@ -122,6 +122,7 @@
     \snippet declarative/places/content/places/CategoryDelegate.qml CategoryModel delegate icon
 
 
+    \target Presenting-Search-Suggestions
     \section1 Presenting Search Suggestions
 
     The \l PlaceSearchSuggestionModel element is used to fetch suggested search terms based on a
@@ -229,9 +230,11 @@
 
     \snippet declarative/places/content/places/CategoryDialog.qml Category save
 
-    Support for place and category remove can be checked at run-time by testing the
-    \l Plugin::supportedPlacesFeatures property for the \e Plugin::RemovePlaceFeature and
-    \e Plugin::RemoveCategoryFeature flags.
+    Support for place and category removal can be checked at run-time by using the
+    \l {Plugin::supportsPlaces} method, passing in a \l {Plugin::supportsPlaces}{Plugin::PlacesFeatures} flag and
+    getting back \e true if the feature is supported. For example one would invoke
+    \e {supportsPlaces(Plugin.RemovePlaceFeature)} to check if the \e Plugin.RemovePlaceFeature is supported.
+
 
     To remove a place, invoke its \l {Place::remove()}{remove()} method.  To remove a category,
     invoke its \l {Category::remove()}{remove()} method.
diff --git a/doc/src/maps.qdoc b/doc/src/maps.qdoc
index 2ff3bfcf..8bc49b88 100644
--- a/doc/src/maps.qdoc
+++ b/doc/src/maps.qdoc
@@ -54,7 +54,7 @@ The Map element supports user interaction through the
 draws the map on-screen using OpenGL (ES), allowing for hardware-accelerated
 rendering where available.
 
-\b{Key elements}
+\b{Key Elements}
 \table
     \row
         \li \l{QtLocation5::Plugin}{Plugin}
@@ -82,7 +82,7 @@ as the ability to implement custom map overlay objects using the
 \l{QtLocation5::MapQuickItem}{MapQuickItem} element, which can contain any
 standard QtQuick item.
 
-\b{Key elements}
+\b{Key Elements}
 \table
     \row
         \li \l{QtLocation5::MapCircle}{MapCircle}
@@ -108,7 +108,7 @@ model (for example a ListModel item), the \l{QtLocation5::MapItemView}{MapItemVi
 element is available. It accepts any map overlay object as its delegate, and can
 only be created within a \l{QtLocation5::Map}{Map}.
 
-\b{Key elements}
+\b{Key Elements}
 \table
     \row
         \li \l{QtLocation5::MapItemView}{MapItemView}
@@ -127,7 +127,7 @@ be changed at any time, and many can also be used in animations. Animating
 coordinate-based map overlay objects, such as MapPolygon and MapPolyline, is not yet
 available.
 
-\b{Key elements}
+\b{Key Elements}
 \table
     \row
         \li \l{QtLocation5::MapMouseArea}{MapMouseArea}
@@ -156,7 +156,7 @@ form of the address to search for. To perform the reverse, the same property
 can be set to a Coordinate instead. Results are made available in the contents
 of the model.
 
-\b{Key elements}
+\b{Key Elements}
 \table
     \row
         \li \l{QtLocation5::Plugin}{Plugin}
@@ -175,6 +175,35 @@ to have access to geocoding translation services and thus data to display.
 
 \section1 Routing and Navigation
 
+Routing is the determination of a navigable path from one point to another on
+a map. Given a map that is aware of features that aid or hinder navigation, such as
+bridges, waterways and so on, a series of segments that make
+up the journey can be constructed. If these \l {RouteSegment}s are simple then we can
+add navigation information at the connecting points, \l {RouteManeuver}s,
+between the segments.
+
+\b{Key Elements}
+\table
+    \row
+        \li \l{QtLocation5::Route}{Routing}
+        \li The entire path to be navigated.
+    \row
+        \li \l{QtLocation5::RouteSegment}{Segments}
+        \li The individual components of a route.
+    \row
+        \li \l{QtLocation5::RouteManeuver}{Maneuvers}
+        \li The navigation information that joins segments.
+    \row
+        \li \l{QtLocation5::RouteModel}{RouteModel}
+        \li The means of making requests on the backend to supply route
+        information.
+\endtable
+
+
+
+
+
+
 */
 
 
@@ -198,7 +227,7 @@ class. For coordinate-to-address queries, the
 on the same class. Instances of QGeocodingManager are available via
 \l{QGeoServiceProvider}.
 
-\b{Key classes}
+\b{Key Classes}
 \table
     \row
         \li \l{QGeoServiceProvider}
diff --git a/doc/src/qtlocation.qdoc b/doc/src/qtlocation.qdoc
index e7e05224..231d8372 100644
--- a/doc/src/qtlocation.qdoc
+++ b/doc/src/qtlocation.qdoc
@@ -108,6 +108,10 @@ require online access or may support on-board maps and data. The default "nokia"
 plugin only supports online use which would be managed by QNetworkInfo and
 QNetworkConfigurationManager.
 
+\note: Plugins may not provide various features such as paging or relevance hints.
+Since plugins may be supplied by other providers, support for these aspects is
+dependent on the provider's implementation.
+
 
 \section2 API Sub-Modules
 
diff --git a/examples/declarative/places/content/places/PlaceReviews.qml b/examples/declarative/places/content/places/PlaceReviews.qml
index b1134c06..86b46ad9 100644
--- a/examples/declarative/places/content/places/PlaceReviews.qml
+++ b/examples/declarative/places/content/places/PlaceReviews.qml
@@ -46,6 +46,7 @@ Item {
 
     clip: true
 
+//! [ReviewModel delegate]
     ListView {
         anchors.fill: parent
 
@@ -53,4 +54,5 @@ Item {
 
         delegate: ReviewDelegate { }
     }
+//! [ReviewModel delegate]
 }
diff --git a/src/imports/location/declarativeplaces/qdeclarativecategory.cpp b/src/imports/location/declarativeplaces/qdeclarativecategory.cpp
index 5c7defd5..3eaaa6e8 100644
--- a/src/imports/location/declarativeplaces/qdeclarativecategory.cpp
+++ b/src/imports/location/declarativeplaces/qdeclarativecategory.cpp
@@ -309,7 +309,7 @@ QString QDeclarativeCategory::errorString() const
     \table
         \row
             \li Category.Ready
-            \li No Error occurred during the last operation, further operations may be performed on
+            \li No error occurred during the last operation, further operations may be performed on
                the category.
         \row
             \li Category.Saving
diff --git a/src/imports/location/declarativeplaces/qdeclarativeplace.cpp b/src/imports/location/declarativeplaces/qdeclarativeplace.cpp
index 7756da43..69ed041a 100644
--- a/src/imports/location/declarativeplaces/qdeclarativeplace.cpp
+++ b/src/imports/location/declarativeplaces/qdeclarativeplace.cpp
@@ -995,7 +995,7 @@ void QDeclarativePlace::synchronizeCategories()
     \table
         \row
             \li Place.UnspecifiedVisibility
-            \li The visibility of the place is unspecified, the default visibility of the \l plugin
+            \li The visibility of the place is unspecified, the default visibility of the \l Plugin
                will be used.
         \row
             \li Place.DeviceVisibility
diff --git a/src/imports/location/declarativeplaces/qdeclarativerecommendationmodel.cpp b/src/imports/location/declarativeplaces/qdeclarativerecommendationmodel.cpp
index eb727d99..1e90db5b 100644
--- a/src/imports/location/declarativeplaces/qdeclarativerecommendationmodel.cpp
+++ b/src/imports/location/declarativeplaces/qdeclarativerecommendationmodel.cpp
@@ -201,8 +201,33 @@ QT_USE_NAMESPACE
     \qmlmethod PlaceRecommendationModel::execute()
 
     Executes a recommendation search query for places similar to the place identified by the
-    \l placeId property.  Once the query completes the model items are updated with the search
-    results.  If an error occurs, the model is cleared.
+    \l placeId property. If the \l plugin supports it, additional prameters such as \l limit,
+    and \l offset may be specified and then \c execute() submits the set of criteria
+    to the \l  plugin to process.
+
+
+    While the query is executing the \l status of the model is set to
+    \c PlaceRecommendationModel.Executing.  If the query successfully completes,
+    the \l status is set to \c PlaceRecommendationModel.Ready, while if it unsuccessfully
+    completes, the \l status is set to \c PlaceRecommendationModel.Error.  Once the query
+    completes, the model items are updated with recommendation results.
+    \code
+    PlaceRecomendationModel {
+        id: model
+        plugin:  backendPlugin
+        ...
+    }
+
+    MouseArea {
+        ...
+        onClicked: {
+            model.placeId = place.placeId
+            limit = -1;
+            offset = 0;
+            model.execute();
+        }
+    }
+    \endcode
 
     \sa cancel(), status
 */
diff --git a/src/imports/location/declarativeplaces/qdeclarativereviewmodel.cpp b/src/imports/location/declarativeplaces/qdeclarativereviewmodel.cpp
index 3b65c418..12186377 100644
--- a/src/imports/location/declarativeplaces/qdeclarativereviewmodel.cpp
+++ b/src/imports/location/declarativeplaces/qdeclarativereviewmodel.cpp
@@ -57,10 +57,22 @@ QT_BEGIN_NAMESPACE
     \brief The ReviewModel element provides access to reviews of a \l Place.
 
     The ReviewModel is a read-only model used to fetch reviews about a \l Place.  The model
-    incrementally fetches reviews.  The number of reviews which are fetched at a time is specified
-    by the \l batchSize property.  The total number of reviews available can be accessed via the
+    incrementally fetches. The number of reviews which are fetched at a time is specified
+    by the \l batchSize property. The total number of reviews available can be accessed via the
     \l totalCount property.
 
+    To use the ReviewModel we need a view and a delegate. In this snippet we
+    see the setting up of a ListView with a ReviewModel model and a delegate.
+
+    \snippet declarative/places/content/places/PlaceReviews.qml  ReviewModel delegate
+
+    The various roles listed below can be selectively displayed, in the \l {Places (QML) Example}
+    the \l {ReviewModel::rating}{rating} is used with the code in \e ReviewPage.qml
+    to provide the format of the displayed data by using the roles from the passed \c data
+    object.
+
+
+
     The model returns data for the following roles:
 
     \table
@@ -109,19 +121,19 @@ QT_BEGIN_NAMESPACE
 */
 
 /*!
-    \qmlproperty Place ReviewModel::place
+    \qmlproperty Place QtLocation5::ReviewModel::place
 
     This property holds the Place that the reviews are for.
 */
 
 /*!
-    \qmlproperty int ReviewModel::batchSize
+    \qmlproperty int QtLocation5::ReviewModel::batchSize
 
     This property holds the batch size to use when fetching more reviews.
 */
 
 /*!
-    \qmlproperty int ReviewModel::totalCount
+    \qmlproperty int QtLocation5::ReviewModel::totalCount
 
     This property holds the total number of reviews for the place.
 */
diff --git a/src/imports/location/declarativeplaces/qdeclarativesearchresultmodel.cpp b/src/imports/location/declarativeplaces/qdeclarativesearchresultmodel.cpp
index 1e5a3dd5..4fcfeb92 100644
--- a/src/imports/location/declarativeplaces/qdeclarativesearchresultmodel.cpp
+++ b/src/imports/location/declarativeplaces/qdeclarativesearchresultmodel.cpp
@@ -253,9 +253,44 @@ QT_USE_NAMESPACE
 /*!
     \qmlmethod PlaceSearchModel::execute()
 
-    Executes a search query using the element's properties as search parameters.  Once the query
-    completes, the model items are updated with the search results.  If an error occurs, the model
-    is cleared.
+    Executes a search query.  Search criteria is specified by setting
+    properties such as the \l searchTerm, \l categories, \l limit and \l offset.
+    Support for these properties may var according to \l plugin.
+    \c execute() then submits the set of criteria to the \l plugin to process.
+
+    While the query is executing the \l status of the model is set to
+    \c PlaceSearchModel.Executing.  If the query successfully completes,
+    the \l status is set to \c PlaceSearchModel.Ready, while if it unsuccessfully
+    completes, the \l status is set to \c PlaceSearchModel.Error.  Once the query
+    completes, the model items are updated with search results.
+
+    \code
+    BoundingCircle {
+        id: searchLocation
+        center: Coordinate {
+            latitude: 10
+            longitude: 10
+        }
+    }
+
+    PlaceSearchModel {
+        id: model
+        plugin: backendPlugin
+        searchArea : searchLocation
+        ...
+    }
+
+    MouseArea {
+        ...
+        onClicked: {
+            model.searchTerm = "pizza";
+            model.categories = null;  //not searching by any category
+            searchLocation.center.latitude = -27.5
+            searchLocation.center.longitude = 153
+            model.execute();
+        }
+    }
+    \endcode
 
     \sa cancel(), status
 */
diff --git a/src/imports/location/declarativeplaces/qdeclarativesearchsuggestionmodel.cpp b/src/imports/location/declarativeplaces/qdeclarativesearchsuggestionmodel.cpp
index 29ac82a0..e64d1f25 100644
--- a/src/imports/location/declarativeplaces/qdeclarativesearchsuggestionmodel.cpp
+++ b/src/imports/location/declarativeplaces/qdeclarativesearchsuggestionmodel.cpp
@@ -138,13 +138,13 @@ QT_USE_NAMESPACE
 
     \table
         \row
-            \li SearchSuggestionModel.Ready
+            \li PlaceSearchSuggestionModel.Ready
             \li The search query has completed, and the results are available.
         \row
-            \li SearchSuggestionModel.Executing
+            \li PlaceSearchSuggestionModel.Executing
             \li A search query is currently being executed.
         \row
-            \li SearchSuggestionModel.Error
+            \li PlaceSearchSuggestionModel.Error
             \li An error occurred when executing the previous search query.
     \endtable
 */
@@ -152,8 +152,46 @@ QT_USE_NAMESPACE
 /*!
     \qmlmethod PlaceSearchSuggestionModel::execute()
 
-    Executes a search suggestion query for the partial \l searchTerm and \l searchArea.  Once the
-    query completes the model items are updated with the suggestions.
+    Executes a search suggestion query for the partial \l searchTerm and a \l searchArea.
+    If the \l plugin supports it, other paramaters such as \l limit and \l offset may
+    be specified.  \c execute() submits the set of parameters to the \l plugin to process.
+
+
+    While the query is executing the \l status of the model is set to
+    \c PlaceSearchSuggestionModel.Executing.  If the query successfully completes,
+    the \l status is set to \c PlaceSearchSuggestionModel.Ready, while if it unsuccessfully
+    completes, the \l status is set to \c PlaceSearchSuggestionModel.Error.  Once the query
+    completes, the model items are updated with search suggestions.
+
+    This example shows use of the model
+    \code
+    BoundingCircle {
+        id: searchLocation
+        center: Coordinate {
+            latitude: 10
+            longitude: 10
+        }
+    }
+
+    PlaceSeachSuggestionModel {
+        id: model
+        plugin: backendPlugin
+        searchArea: searchLocation
+        ...
+    }
+
+    MouseArea {
+        ...
+        onClicked: {
+            model.searchTerm = "piz"
+            searchLocation.center.latitude = -27.5
+            searchLocation.cetner.longitude = 153
+            model.execute();
+        }
+    }
+    \endcode
+
+    A more detailed example can be found in the in \l {Places (QML) Example#Presenting-Search-Suggestions}{places example}.
 
     \sa cancel(), status
 */
diff --git a/src/imports/location/qdeclarativegeomaneuver.cpp b/src/imports/location/qdeclarativegeomaneuver.cpp
index 4b05c536..ac557ece 100644
--- a/src/imports/location/qdeclarativegeomaneuver.cpp
+++ b/src/imports/location/qdeclarativegeomaneuver.cpp
@@ -62,7 +62,7 @@ QT_BEGIN_NAMESPACE
 
     \section1 Example
 
-    The following QML snipplet demonstrates how to print information about a
+    The following QML snippet demonstrates how to print information about a
     route maneuver:
 
     \snippet snippets/declarative/routing.qml QtQuick import
diff --git a/src/imports/location/qdeclarativegeoserviceprovider.cpp b/src/imports/location/qdeclarativegeoserviceprovider.cpp
index ae3aea53..e38fd748 100644
--- a/src/imports/location/qdeclarativegeoserviceprovider.cpp
+++ b/src/imports/location/qdeclarativegeoserviceprovider.cpp
@@ -52,6 +52,8 @@
 
 QT_BEGIN_NAMESPACE
 
+
+
 /*!
     \qmlclass Plugin QDeclarativeGeoServiceProvider
     \inqmlmodule QtLocation 5
@@ -108,6 +110,8 @@ QDeclarativeGeoServiceProvider::~QDeclarativeGeoServiceProvider()
     delete sharedProvider_;
 }
 
+
+
 /*!
     \qmlproperty string Plugin::name
 
@@ -237,13 +241,63 @@ bool QDeclarativeGeoServiceProvider::supportsRouting(const RoutingFeatures &feat
 }
 
 /*!
-    \internal
-*/
-bool QDeclarativeGeoServiceProvider::supportsPlaces(const PlacesFeatures &feature) const
+
+  \qmlmethod Plugin::supportsPlaces(PlacesFeatures features)
+
+  This method returns a boolean indicating whether the specified set of
+  \a features flags is supported or not.  True is returned if it is supported,
+  otherwise false is returned.
+
+  \target PluginPlacesFeatures
+  The \a features parameter can be any flag combination of:
+    \table
+        \header
+            \li Feature
+            \li Description
+        \row
+            \li Plugin.NoPlacesFeatures
+            \li No features supported
+        \row
+            \li Plugin.OnlinePlacesFeature
+            \li Place data online
+        \row
+            \li Plugin.OfflinePlacesFeature
+            \li Supports offline data for places
+        \row
+            \li Plugin.SavePlaceFeature
+            \li Can save place data
+        \row
+            \li Plugin.RemovePlaceFeature
+            \li Supports removal of a place
+        \row
+            \li Plugin.PlaceRecommendationsFeature
+            \li Supports user recommendations
+        \row
+            \li Plugin.SearchSuggestionsFeature
+            \li Supports suggestions to user query
+        \row
+            \li Plugin.CorrectionsFeature
+            \li User can edit saved place data.
+        \row
+            \li Plugin.LocalizedPlacesFeature
+            \li Local places
+        \row
+            \li Plugin.NotificationsFeature
+            \li Notify user of place event
+        \row
+            \li Plugin.PlaceMatchingFeature
+            \li Find places
+        \row
+            \li Plugin.AnyPlacesFeatures
+            \li Are any features supported
+    \endtable
+
+    */
+bool QDeclarativeGeoServiceProvider::supportsPlaces(const PlacesFeatures &features) const
 {
     QGeoServiceProvider *sp = sharedGeoServiceProvider();
     QGeoServiceProvider::PlacesFeatures f =
-            static_cast<QGeoServiceProvider::PlacesFeature>(int(feature));
+            static_cast<QGeoServiceProvider::PlacesFeature>(int(features));
     if (f == QGeoServiceProvider::AnyPlacesFeatures)
         return (sp && (sp->placesFeatures() != QGeoServiceProvider::NoPlacesFeatures));
     else
@@ -533,7 +587,8 @@ void QDeclarativeGeoServiceProviderRequirements::setGeocodingRequirements(const
 
 /*!
     \internal
-*/
+
+    */
 QDeclarativeGeoServiceProvider::PlacesFeatures QDeclarativeGeoServiceProviderRequirements::placesRequirements() const
 {
     return places_;
diff --git a/src/imports/location/qdeclarativepositionsource.cpp b/src/imports/location/qdeclarativepositionsource.cpp
index acb02e8f..4e05d6d8 100644
--- a/src/imports/location/qdeclarativepositionsource.cpp
+++ b/src/imports/location/qdeclarativepositionsource.cpp
@@ -485,8 +485,8 @@ void QDeclarativePositionSource::stop()
 /*!
     \qmlproperty bool PositionSource::active
 
-    This property indicates whether the position source is (/should be)
-    active. Setting this property to false equals calling \l stop, and
+    This property indicates whether the position source is active.
+    Setting this property to false equals calling \l stop, and
     setting this property true equals calling \l start.
 
     \sa start, stop, update
diff --git a/src/location/places/qplace.cpp b/src/location/places/qplace.cpp
index 72bf3cee..4446e459 100644
--- a/src/location/places/qplace.cpp
+++ b/src/location/places/qplace.cpp
@@ -455,7 +455,8 @@ QUrl QPlace::primaryWebsite() const
 }
 
 /*!
-    Returns whether the details of this place have been fetched or not.
+    Returns true if the details of this place have been fetched,
+    otherwise returns false.
 */
 bool QPlace::detailsFetched() const
 {
diff --git a/src/location/qgeocoordinate.cpp b/src/location/qgeocoordinate.cpp
index 85193ecb..ed8c0c07 100644
--- a/src/location/qgeocoordinate.cpp
+++ b/src/location/qgeocoordinate.cpp
@@ -102,7 +102,12 @@ QGeoCoordinatePrivate::~QGeoCoordinatePrivate()
     and altitude). Use distanceTo() and azimuthTo() to calculate the distance
     and bearing between coordinates.
 
-    The coordinate values should be specified using the WGS84 datum.
+    The coordinate values should be specified using the WGS84 datum. For more information
+    on geographical terms see this article on \l {http://en.wikipedia.org/wiki/Geographic_coordinate_system}{coordinates} and
+    another on \l {http://en.wikipedia.org/wiki/Geodetic_system}{geodetic systems}
+    including WGS84.
+
+    Azimuth in this context is equivalent to a compass bearing based on true north.
 */
 
 /*!