Cpp Documentation class documentation + plugin documentation

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

1 files changed, 88 insertions, 12 deletions

diff --git a/src/location/places/qplaceicon.cpp b/src/location/places/qplaceicon.cpp
index f09bfa98..fcd81d06 100644
--- a/src/location/places/qplaceicon.cpp
+++ b/src/location/places/qplaceicon.cpp
@@ -80,6 +80,72 @@ bool QPlaceIconPrivate::operator == (const QPlaceIconPrivate &other) const
 }
 
 /*!
+    \class QPlaceIcon
+    \inmodule QtLocation
+    \ingroup QtLocation-places
+    \ingroup QtLocation-places-data
+    \since QtLocation 5.0
+
+    \brief The QPlaceIcon class represents an icon.
+
+    \section2 Usage
+    The typical usage of an icon is to use the url() function to specify
+    a preferred size and set of flags.
+
+    \snippet snippets/places/requesthandler.h icon
+
+    Note that the parameters are \e {preferred} only.  If a manager backend
+    does not support one or more of the specified parameters, the url of the icon that most
+    closely matches those parameters is returned.
+
+    \target Icon internals
+    \section2 Internals
+    Icons are tightly coupled to a particular manager and always have a pointer
+    to that manager.  The icon does not have ownership of this pointer.
+
+    The internals of the icon work by specifying either a \e {base} or a
+    \e {full} url.
+
+    A \e {base} url may be an incomplete url of the form \e {http://example.com/icon}.
+    When a set of icon parameters is provided to the url() function, the manager
+    constructs a complete icon url such as \e {http://example.com/icon_32x32_selected.png}.
+
+    A \e {full} url is a complete url which may look something like \e {http://example.com/myicon.png}
+    When a full url is specified the url() will always return the complete url.
+
+    Only one \e {base} or \e {full} url may be specified for a single icon, setting one implies clearing the other.
+    Whether full and or base urls are supported depends on the manager backend.
+
+    Any valid URL may be returned by the backend, but it would typically
+    be either a http://, file://, or data:// URL.
+*/
+
+/*!
+    \enum QPlaceIcon::IconFlag
+
+    This enum is used to specify different icon states and types.
+
+    The state flags are:
+    \value Normal   An icon with no state modifications.  This flag indicates that the user is not
+                    interacting with the icon, but the functionality represented by the icon is
+                    available.
+    \value Disabled An icon with a disabled appearance.  This flag indicates that the functionality
+                    represented by the icon is not available.
+    \value Active   An icon with an active appearance.  This flag indicates that the functionality
+                    represented by the icon is available and the user is interacting with the icon,
+                    for example, touching it.
+    \value Selected An icon with a selected appearance.  This flag indicates that the item represented
+               by the icon is selected.
+
+
+    The type flags are:
+    \value Map An icon intended for display on a map
+    \value List An icon intended for display in a list.
+
+    You can use at most one state and one type flag at a time.
+*/
+
+/*!
     Constructs an icon.
 */
 QPlaceIcon::QPlaceIcon()
@@ -112,7 +178,7 @@ QPlaceIcon &QPlaceIcon::operator=(const QPlaceIcon &other)
 }
 
 /*!
-    Returns true if this icon is equal to \a other.  Otherwise returns false.
+    Returns true if this icon is equal to \a other, otherwise returns false.
 */
 bool QPlaceIcon::operator==(const QPlaceIcon &other) const
 {
@@ -120,11 +186,17 @@ bool QPlaceIcon::operator==(const QPlaceIcon &other) const
 }
 
 /*!
+    \fn QPlaceIcon::operator!=(const QPlaceIcon &other) const
+
+    Returns true if \a other is not equal to this icon, otherwise returns false.
+*/
+
+/*!
     Returns an icon url according to the given \a size and \a flags.
     If a base url has been set by setBaseUrl(), the url to the image that best
     fits the specified parameters is returned.
 
-    If a full url has been set by setUrl(), the full url is returned.
+    If a full url has been set by setFullUrl(), the full url is returned.
 
     If no manager has been assigned to the icon a default constructed QUrl
     is returned.
@@ -142,11 +214,11 @@ QUrl QPlaceIcon::url(const QSize &size, QPlaceIcon::IconFlags flags) const
 }
 
 /*!
-    Sets a full URL of the resource that represents the image of this
+    Sets a full \a url of the resource that represents the image of this
     icon.  Because a full URL is being set, specifying different
     sizes and flags into the url() function will have no effect.
 
-    When calling the setUrl() function, the base url is implictly
+    When calling the this function, the baseUrl() is implictly
     cleared.
 */
 void QPlaceIcon::setFullUrl(const QUrl &url)
@@ -155,16 +227,20 @@ void QPlaceIcon::setFullUrl(const QUrl &url)
     d->baseUrl.clear();
 }
 
+/*!
+    Returns a the full url that the icon is based off.
+    \sa baseUrl()
+*/
 QUrl QPlaceIcon::fullUrl() const
 {
     return d->fullUrl;
 }
 
 /*!
-    Returns a base url that the comlete icon url is based off.
-    E.g. the base url may be http://example.com/icon
-    When calling the url() function the base url may be used as a hint
-    to construct http://example.com/icon_32x32_selected.png
+    Returns a base url that the complete icon url is based off.
+
+    E.g. the base url may be http://example.com/icon.
+    When calling the url() function the, base url may be used to construct: http://example.com/icon_32x32_selected.png
 */
 QUrl QPlaceIcon::baseUrl() const
 {
@@ -172,10 +248,9 @@ QUrl QPlaceIcon::baseUrl() const
 }
 
 /*!
-    Sets a base url that the complete icon url returned by url() is based off.
+    Sets a base \a url that the complete icon url returned by url() is based off.
 
-    When calling setBaseUrl() function, the full url set by
-    setUrl() is implicitly cleared.
+    When calling this function, the fullUrl() is implicitly cleared.
 */
 void QPlaceIcon::setBaseUrl(const QUrl &url)
 {
@@ -192,7 +267,8 @@ QPlaceManager *QPlaceIcon::manager() const
 }
 
 /*!
-    Sets the \a manager that this icon is associated with.
+    Sets the \a manager that this icon is associated with.  The icon does not take
+    ownership of the pointer.
 */
 void QPlaceIcon::setManager(QPlaceManager *manager)
 {