Cpp Documentation class documentation + plugin documentation

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

1 files changed, 183 insertions, 39 deletions

diff --git a/src/location/places/qplacemanagerengine.cpp b/src/location/places/qplacemanagerengine.cpp
index f30f72f2..4864857e 100644
--- a/src/location/places/qplacemanagerengine.cpp
+++ b/src/location/places/qplacemanagerengine.cpp
@@ -48,16 +48,19 @@ QT_USE_NAMESPACE
     \class QPlaceManagerEngine
     \inmodule QtLocation
     \ingroup QtLocation-impl
+    \ingroup QtLocation-places
+    \ingroup QtLocation-places-manager
     \since QtLocation 5.0
 
-    \brief The QPlaceManagerEngine class provides an interface and convenience methods to
-    implementers of QGeoServiceProvider plugins who want to provide access to place search
+    \brief The QPlaceManagerEngine class provides an interface for
+    implementers of QGeoServiceProvider plugins who want to provide access to place
     functionality.
 
-    Subclasses of QPlaceManagerEngine need to provide an implementation of getPlaceDetails(),
-    getContent(), postRating(), getReviews(), searchForPlaces(), supportedSearchVisibilityScopes(),
-    recommendations(), textPredictions(), savePlace(), supportedSaveVisibilityScopes(), removePlace(),
-    initializeCategories() and categories().
+    Application developers need not concern themselves with the QPlaceManagerEngine.
+    Backend implementers however will need to derive from QPlaceManagerEngine and provide
+    implementations for the abstract virtual functions.
+
+    For more information on writing a backend see the \l {Places Backend} documentation.
 
     \sa QPlaceManager
 */
@@ -82,11 +85,13 @@ QPlaceManagerEngine::~QPlaceManagerEngine()
 }
 
 /*!
+    \internal
     Sets the name which this engine implementation uses to distinguish itself
     from the implementations provided by other plugins to \a managerName.
 
-    The combination of managerName() and managerVersion() should be unique
-    amongst plugin implementations.
+    This function does not need to be called by engine implementers,
+    it is implicitly called by QGeoServiceProvider to set the manager
+    name to be the same as the provider's.
 */
 void QPlaceManagerEngine::setManagerName(const QString &managerName)
 {
@@ -97,8 +102,8 @@ void QPlaceManagerEngine::setManagerName(const QString &managerName)
     Returns the name which this engine implementation uses to distinguish
     itself from the implementations provided by other plugins.
 
-    The combination of managerName() and managerVersion() should be unique
-    amongst plugin implementations.
+    The manager name is automatically set to be the same
+    as the QGeoServiceProviderFactory::providerName().
 */
 QString QPlaceManagerEngine::managerName() const
 {
@@ -106,6 +111,7 @@ QString QPlaceManagerEngine::managerName() const
 }
 
 /*!
+    \internal
     Sets the version of this engine implementation to \a managerVersion.
 
     The combination of managerName() and managerVersion() should be unique
@@ -119,8 +125,8 @@ void QPlaceManagerEngine::setManagerVersion(int managerVersion)
 /*!
     Returns the version of this engine implementation.
 
-    The combination of managerName() and managerVersion() should be unique
-    amongst plugin implementations.
+    The manager version is automatically set to be the same
+    as the QGeoServiceProviderFactory::providerVersion().
 */
 int QPlaceManagerEngine::managerVersion() const
 {
@@ -135,17 +141,6 @@ QPlaceManager *QPlaceManagerEngine::manager() const
     return d_ptr->manager;
 }
 
-/*!
-    \fn void QPlaceManagerEngine::authenticationRequired(QAuthenticator *authenticator)
-
-    This signal is emitted if authentication details are required by the manager engine
-    to peform certain operations.  If the authentication was successful, the next time
-    the operations are performed, the same credentials are used and the
-    authenticationRequired signal is not emitted again.
-
-    If authentication is unsuccessful, the manager engine will emit the signal again.
-*/
-
 QPlaceManagerEnginePrivate::QPlaceManagerEnginePrivate()
     :   managerVersion(-1), manager(0)
 {
@@ -156,53 +151,202 @@ QPlaceManagerEnginePrivate::~QPlaceManagerEnginePrivate()
 }
 
 /*!
-    \fn void QPlaceManagerEngine::placeAdded(const QString&placeId)
+    \fn QPlaceDetailsReply *QPlaceManagerEngine::getPlaceDetails(const QString &placeId)
 
-    This signal is emitted if a place has been added to the manager engine's datastore.
+    Retrieves a details of place corresponding to the given \a placeId.
+*/
+
+/*! \fn QPlaceContentReply *QPlaceManagerEngine::getContent(const QPlace &place, const QPlaceContentRequest &request)
+
+    Retrieves content for a given \a place according to the parameters specified in
+    \a request.
+*/
+
+/*!
+    \fn QPlaceSearchReply *QPlaceManagerEngine::search(const QPlaceSearchRequest &request)
+
+    Searches for places according to the parameters specified in \a request.
+*/
+
+/*!
+    \fn QPlaceSearchReply *QPlaceManagerEngine::recommendations(const QPlace &place, const QPlaceSearchRequest &request)
+
+    Provides recommendations for places that similar to \a place, and using the parameters as specified in \a request.
+*/
+
+/*!
+    \fn QPlaceTextPredictionReply *QPlaceManagerEngine::textPredictions(const QPlaceSearchRequest &request)
+
+    Requests a set of text predictions according to the parameters specified in \a request.
+*/
+
+/*!
+    \fn QPlaceIdReply *QPlaceManagerEngine::savePlace(const QPlace &place)
+
+    Saves a specified \a place to the manager engine's datastore.
+*/
+
+/*!
+    \fn QPlaceIdReply *QPlaceManagerEngine::removePlace(const QString &placeId)
+
+    Removes the place corresponding to \a placeId from the manager engine's datastore.
+*/
+
+/*!
+    \fn QPlaceIdReply *QPlaceManagerEngine::saveCategory(const QPlaceCategory &category, const QString &parentId)
+
+    Saves a \a category that is a child of the category specified by \a parentId.
+    An empty \a parentId means \a category is saved as a top level category.
+*/
+
+/*!
+    \fn QPlaceIdReply *QPlaceManagerEngine::removeCategory(const QString &categoryId)
+
+    Removes the category corresponding to \a categoryId from the manager engine's datastore.
+*/
+
+/*!
+    \fn QPlaceReply *QPlaceManagerEngine::initializeCategories()
+
+    Initializes the categories of the manager engine.
+*/
 
-    It is generally only emitted by managers that store places locally.
+/*!
+    \fn QString QPlaceManagerEngine::parentCategoryId(const QString &categoryId) const
+
+    Returns the parent category id of the category corresponding to \a categoryId.
+*/
+
+/*!
+    \fn QStringList QPlaceManagerEngine::childrenCategoryIds(const QString &categoryId) const
+
+    Returns the children category ids of the category corresponding to \a categoryId.
+    If \a categoryId is empty then all top level category ids are returned.
+*/
+
+/*!
+    \fn QPlaceCategory QPlaceManagerEngine::category(const QString &categoryId) const
+
+    Returns the category corresponding to the given \a categoryId.
+*/
+
+/*!
+    \fn QList<QPlaceCategory> QPlaceManagerEngine::childCategories(const QString &parentId) const
+
+    Returns a list of categories that are children of the category corresponding to \a parentId.
+    If \a parentId is empty, all the top level categories are returned.
+*/
+
+/*!
+    \fn QLocale QPlaceManagerEngine ::locale() const
+
+    Returns the locale of the manager engine. The locale is used as a hint to determine
+    what language place data should be returned in.
+*/
+
+/*!
+    \fn void QPlaceManagerEngine::setLocale(const QLocale &locale)
+
+    Sets the \a locale of the manager engine.
+*/
+
+/*!
+    \fn QUrl QPlaceManagerEngine::constructIconUrl(const QPlaceIcon &icon, const QSize &size, QPlaceIcon::IconFlags flags)
+
+    Constructs an icon url from a given \a icon, \a size and \a flags.  The URL of the icon
+    image that most closely matches the given parameters is returned.
+*/
+
+/*!
+    \fn QPlaceManager::ManagerFeatures QPlaceManagerEngine::supportedFeatures() const
+
+    Returns a set of flags indicating what particular features this manager engine instance supports.
+*/
+
+/*!
+    \fn void QPlaceManagerEngine::finished(QPlaceReply* reply)
+
+    This signal is emitted when \a reply has finished processing.
+
+    If reply->error() equals QPlaceReply::NoError then the processing
+    finished successfully.
+
+    This signal and QPlaceReply::finished() will be emitted at the same time.
+
+    \note Do no delete the \a reply object in the slot connected to this signal.
+    Use deleteLater() instead.
+*/
+
+/*!
+    \fn void QPlaceManagerEngine::error(QPlaceReply * reply, QPlaceReply::Error error, const QString &errorString = QString());
+
+    This signal is emitted when an error has been detected in the processing of
+    \a reply.  The QPlaceManager::finished() signal will probably follow.
+
+    The error will be described by the error code \a error.  If \a errorString is
+    not empty it will contain a textual description of the error meant for developers
+    and not end users.
+
+    This signal and QPlaceReply::error() will be emitted at the same time.
+
+    \note Do no delete the \a reply object in the slot connected to this signal.
+    Use deleteLater() instead.
+*/
+
+/*!
+    \fn void QPlaceManagerEngine::placeAdded(const QString &placeId)
+
+    This signal is emitted if a place has been added to the manager engine's datastore.
+    The particular added place is specified by \a placeId.
 
+    This signal is only emitted by manager engines that support the QPlaceManager::NotificationsFeature.
 */
 
 /*!
-    \fn void QPlaceManagerEngine::placeUpdated(const QString&placeId)
+    \fn void QPlaceManagerEngine::placeUpdated(const QString &placeId)
 
     This signal is emitted if a place has been modified in the manager engine's datastore.
+    The particular modifed place is specified by \a placeId.
 
-    It is generally only emitted by managers that store places locally.
+    This signal is only emitted by manager engines that support the QPlaceManager::NotificationsFeature.
 */
 
 /*!
-    \fn void QPlaceManagerEngine::placeRemoved(const QString&placeId)
+    \fn void QPlaceManagerEngine::placeRemoved(const QString &placeId)
 
     This signal is emitted if a place has been removed from the manager engine's datastore.
+    The particular place that has been removed is specified by \a placeId.
 
-    It is generally only emitted by managers that store places locally.
+    This signal is only emitted by manager engines that support the QPlaceManager::NotificationsFeature.
 */
 
 /*!
-    \fn void QPlaceManagerEngine::categoryAdded(const QString&categoryId)
+    \fn void QPlaceManagerEngine::categoryAdded(const QPlaceCategory &category, const QString &parentId)
 
-    This signal is emitted if a category has been added to the manager engine's datastore.
+    This signal is emitted if a \a category has been added to the manager engine's datastore.
+    The parent of the \a category is specified by \a parentId.
 
-    It is generally only emitted by managers that store categories locally.
+    This signal is only emitted by manager engines that support the QPlaceManager::NotificationsFeature.
 
 */
 
 /*!
-    \fn void QPlaceManagerEngine::categoryUpdated(const QString&categoryId)
+    \fn void QPlaceManagerEngine::categoryUpdated(const QPlaceCategory &category, const QString &parentId)
 
-    This signal is emitted if a category has been modified in the manager engine's datastore.
+    This signal is emitted if a \a category has been modified in the manager engine's datastore.
+    The parent of the modified category is specified by \a parentId.
 
-    It is generally only emitted by managers that store categories locally.
+    This signal is only emitted by manager engines that support the QPlaceManager::NotificationsFeature.
 */
 
 /*!
-    \fn void QPlaceManagerEngine::categoryRemoved(const QString&categoryId)
+    \fn void QPlaceManagerEngine::categoryRemoved(const QString &categoryId, const QString &parentId)
 
-    This signal is emitted if a category has been removed from the manager engine's datastore.
+    This signal is emitted when the category correspoinding to \a categoryId has
+    been removed from the manager engine's datastore.  The parent of the removed category
+    is specified by \a parentId.
 
-    It is generally only emitted by managers that store categories locally.
+    This signal is only emitted by manager engines that support the QPlaceManager::NotificationsFeature.
 */
 
 #include "moc_qplacemanagerengine.cpp"