Update search result documentation

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

2 files changed, 24 insertions, 5 deletions

diff --git a/src/location/places/qplaceresult.cpp b/src/location/places/qplaceresult.cpp
index 3122a8ef..f1c3c482 100644
--- a/src/location/places/qplaceresult.cpp
+++ b/src/location/places/qplaceresult.cpp
@@ -82,6 +82,13 @@ bool QPlaceResultPrivate::compare(const QPlaceSearchResultPrivate *other) const
     an instance of the place and an indication of whether the result is
     sponsored or \l {http://en.wikipedia.org/wiki/Organic_search}{organic}.
 
+    The intended usage is that a QPlaceSearchResult can be converted into a QPlaceResult
+    like so:
+
+    \snippet snippets/places/requesthandler.h Convert search result
+
+    The implmentation is handled in such a way that object slicing is not an issue.
+
     \sa QPlaceSearchResult
 */
 
diff --git a/src/location/places/qplacesearchresult.cpp b/src/location/places/qplacesearchresult.cpp
index 0af98569..10af8618 100644
--- a/src/location/places/qplacesearchresult.cpp
+++ b/src/location/places/qplacesearchresult.cpp
@@ -77,12 +77,24 @@ bool QPlaceSearchResultPrivate::compare(const QPlaceSearchResultPrivate *other)
     \ingroup QtLocation-places-data
     \since Qt Location 5.0
 
-    \brief The QPlaceSearchResult class is the base class for all place search results.
+    \brief The QPlaceSearchResult class is the base class for search results.
 
-    A list of place search results can be retrieved from the QPlaceSearchReply after it has
-    successfully completed the request.  All place search results contain a \l {type()} which
-    describes the type of search result.  A \l {title()} and an \l {icon()} which can be used to
-    present the search result to the user.
+    A list of search results can be retrieved from the QPlaceSearchReply after it has
+    successfully completed the request.  Common to all search results are the
+    \l {QPlaceSearchResult::title()} {title} and \l {QPlaceSearchResult::icon()}{icon},
+    which can be used to present the search result to the user.
+
+    The intended usage is that depending  on the \l {QPlaceSearchResult::type()} {type},
+    the search result can be converted to a more detailed subclass like so:
+
+    \snippet snippets/places/requesthandler.h Convert search result
+
+    The implmentation is handled in such a way that object slicing is not an issue.
+    It is not expected that client applications or backend plugins instantiate
+    a QPlaceSearchResult directly, but rather client applications simply convert
+    to search result subclasses and backend plugins only instantiate subclasses.
+
+    \sa QPlaceResult
 */
 
 /*!