Adding some docs for basic QML map items that have none

Docs for MapCircle, MapQuickItem, MapRectangle and MapRoute, as well
as improvements to MapPolygon so that it appears in the list.

Change-Id: I71e659f65ad3fe467893136acbec71db87f5ede5
Reviewed-by: Alex <alex.blasche@nokia.com>

6 files changed, 154 insertions, 7 deletions

diff --git a/src/imports/location/qdeclarativecirclemapitem.cpp b/src/imports/location/qdeclarativecirclemapitem.cpp
index 66856e20..328b7ff5 100644
--- a/src/imports/location/qdeclarativecirclemapitem.cpp
+++ b/src/imports/location/qdeclarativecirclemapitem.cpp
@@ -48,6 +48,19 @@
 
 QT_BEGIN_NAMESPACE
 
+/*!
+    \qmlclass MapCircle QDeclarativeCircleMapItem
+    \inqmlmodule QtLocation 5
+    \ingroup qml-QtLocation5-maps
+    \since QtLocation 5.0
+
+    \brief The MapCircle element displays a geographic circle on a map.
+
+    A geographic circle consists of all points that are at a set distance
+    from one central point. MapCircle displays such a circle, based on the
+    center and radius properties given.
+*/
+
 #ifndef M_PI
 #define M_PI 3.14159265358979323846
 #endif
@@ -176,6 +189,16 @@ QDeclarativeCircleMapItem::~QDeclarativeCircleMapItem()
 {
 }
 
+/*!
+    \qmlproperty int MapCircle::border.width
+    \qmlproperty color MapCircle::border.color
+
+    These properties hold the width and color used to draw the border of the circle.
+    The width is in pixels and is independent of the zoom level of the map.
+
+    The default values correspond to a black border with a width of 1 pixel.
+    For no line, use a width of 0 or a transparent color.
+*/
 QDeclarativeMapLineProperties *QDeclarativeCircleMapItem::border()
 {
     return &border_;
@@ -197,6 +220,13 @@ void QDeclarativeCircleMapItem::setMap(QDeclarativeGeoMap* quickMap, Map *map)
     }
 }
 
+/*!
+    \qmlproperty Coordinate MapCircle::center
+
+    This property holds the central point about which the circle is defined.
+
+    \sa radius
+*/
 void QDeclarativeCircleMapItem::setCenter(QDeclarativeCoordinate *center)
 {
     if (center_ == center)
@@ -220,6 +250,12 @@ QDeclarativeCoordinate* QDeclarativeCircleMapItem::center()
     return center_;
 }
 
+/*!
+    \qmlproperty color MapCircle::color
+
+    This property holds the fill color of the circle when drawn. For no fill,
+    use a transparent color.
+*/
 void QDeclarativeCircleMapItem::setColor(const QColor &color)
 {
     if (color_ == color)
@@ -235,6 +271,13 @@ QColor QDeclarativeCircleMapItem::color() const
     return color_;
 }
 
+/*!
+    \qmlproperty qreal MapCircle::radius
+
+    This property holds the radius of the circle, in meters on the ground.
+
+    \sa center
+*/
 void QDeclarativeCircleMapItem::setRadius(qreal radius)
 {
     if (radius_ == radius)
diff --git a/src/imports/location/qdeclarativegeomapquickitem.cpp b/src/imports/location/qdeclarativegeomapquickitem.cpp
index e91d1aa1..55ac572f 100644
--- a/src/imports/location/qdeclarativegeomapquickitem.cpp
+++ b/src/imports/location/qdeclarativegeomapquickitem.cpp
@@ -49,9 +49,23 @@
 QT_BEGIN_NAMESPACE
 
 /*!
-    \qmlclass MapQuickItem
-
-    The MapQuickItem element is part of the \bold{QtLocation 5.0} module.
+    \qmlclass MapQuickItem QDeclarativeGeoMapQuickItem
+    \inqmlmodule QtLocation 5
+    \ingroup qml-QtLocation5-maps
+    \since QtLocation 5.0
+
+    \brief The MapQuickItem element displays an arbitrary Qt Quick element
+           at a specified geographic location on a map.
+
+    The displayed element is contained in the sourceItem property. The
+    anchorPoint property controls the point on the sourceItem that should be
+    kept anchored to the geographic coordinate of the MapQuickItem. One common
+    use of the MapQuickItem is to display a simple image on the map:
+
+    \snippet examples/declarative/mapviewer/content/map/Marker.qml mqi-top
+    \snippet examples/declarative/mapviewer/content/map/Marker.qml mqi-anchor
+    \snippet examples/declarative/mapviewer/content/map/Marker.qml mqi-closeimage
+    \snippet examples/declarative/mapviewer/content/map/Marker.qml mqi-close
 */
 
 QDeclarativeGeoMapQuickItem::QDeclarativeGeoMapQuickItem(QQuickItem *parent)
@@ -67,6 +81,13 @@ QDeclarativeGeoMapQuickItem::QDeclarativeGeoMapQuickItem(QQuickItem *parent)
 
 QDeclarativeGeoMapQuickItem::~QDeclarativeGeoMapQuickItem() {}
 
+/*!
+    \qmlproperty Coordinate MapQuickItem::coordinate
+
+    This property holds the anchor coordinate of the MapQuickItem. The point
+    on the sourceItem that is specified by anchorPoint is kept aligned with
+    this coordinate when drawn on the map.
+*/
 void QDeclarativeGeoMapQuickItem::setCoordinate(QDeclarativeCoordinate *coordinate)
 {
     if (coordinate_ == coordinate)
@@ -122,6 +143,11 @@ QDeclarativeCoordinate* QDeclarativeGeoMapQuickItem::coordinate()
     return coordinate_;
 }
 
+/*!
+    \qmlproperty object MapQuickItem::sourceItem
+
+    This property holds the source item that will be drawn on the map.
+*/
 void QDeclarativeGeoMapQuickItem::setSourceItem(QQuickItem* sourceItem)
 {
     if (sourceItem == sourceItem_)
@@ -138,6 +164,12 @@ QQuickItem* QDeclarativeGeoMapQuickItem::sourceItem()
     return sourceItem_;
 }
 
+/*!
+    \qmlproperty QPointF MapQuickItem::anchorPoint
+
+    This property determines which point on the sourceItem will be lined up
+    with the coordinate on the map.
+*/
 void QDeclarativeGeoMapQuickItem::setAnchorPoint(const QPointF &anchorPoint)
 {
     if (anchorPoint == anchorPoint_)
@@ -152,6 +184,11 @@ QPointF QDeclarativeGeoMapQuickItem::anchorPoint() const
     return anchorPoint_;
 }
 
+/*!
+    \qmlproperty qreal MapQuickItem::zoomLevel
+
+    TODO: document this property
+*/
 void QDeclarativeGeoMapQuickItem::setZoomLevel(qreal zoomLevel)
 {
     if (zoomLevel == zoomLevel_)
diff --git a/src/imports/location/qdeclarativepolygonmapitem.cpp b/src/imports/location/qdeclarativepolygonmapitem.cpp
index bf1fa896..c241ed18 100644
--- a/src/imports/location/qdeclarativepolygonmapitem.cpp
+++ b/src/imports/location/qdeclarativepolygonmapitem.cpp
@@ -56,8 +56,10 @@ QT_BEGIN_NAMESPACE
     The polygon is specified in terms of an ordered list of coordinates.
     Any invalid coordinates in the list will be ignored.
 
-    \sa MapItem
+    MapPolygon can only display simple, convex polygons. Support may be added
+    in future for concave polygons, but this is not currently available.
 
+    \sa MapItem
 */
 
 struct Vertex
@@ -276,7 +278,7 @@ void QDeclarativePolygonMapItem::removeCoordinate(QDeclarativeCoordinate* coordi
 /*!
     \qmlproperty color MapPolygon::color
 
-    This property holds the color used to fill the circle.
+    This property holds the color used to fill the polygon.
 
     The default value is transparent.
 */
diff --git a/src/imports/location/qdeclarativepolylinemapitem.cpp b/src/imports/location/qdeclarativepolylinemapitem.cpp
index e9dab242..37978ec9 100644
--- a/src/imports/location/qdeclarativepolylinemapitem.cpp
+++ b/src/imports/location/qdeclarativepolylinemapitem.cpp
@@ -46,9 +46,9 @@
 QT_BEGIN_NAMESPACE
 
 /*!
-    \qmlclass MapPolyline
+    \qmlclass MapPolyline QDeclarativePolylineMapItem
     \inqmlmodule QtLocation 5
-    \ingroup qml-location-maps
+    \ingroup qml-QtLocation5-maps
     \since QtLocation 5.0
 
     \brief The MapPolyline element displays a polyline on a map.
diff --git a/src/imports/location/qdeclarativerectanglemapitem.cpp b/src/imports/location/qdeclarativerectanglemapitem.cpp
index 1f9b5e83..327363fb 100644
--- a/src/imports/location/qdeclarativerectanglemapitem.cpp
+++ b/src/imports/location/qdeclarativerectanglemapitem.cpp
@@ -44,6 +44,18 @@
 
 QT_BEGIN_NAMESPACE
 
+/*!
+    \qmlclass MapRectangle QDeclarativeRectangleMapItem
+    \inqmlmodule QtLocation 5
+    \ingroup qml-QtLocation5-maps
+    \since QtLocation 5.0
+
+    \brief The MapRectangle element displays a rectangle on a Map.
+
+    The rectangle displayed by MapRectangle is defined by its topLeft and
+    bottomRight coordinates.
+*/
+
 struct Vertex
 {
     QVector2D position;
@@ -78,11 +90,26 @@ void QDeclarativeRectangleMapItem::setMap(QDeclarativeGeoMap* quickMap, Map *map
     }
 }
 
+/*!
+    \qmlproperty int MapRectangle::border.width
+    \qmlproperty color MapRectangle::border.color
+
+    These properties hold the width and color used to draw the border of the rectangle.
+    The width is in pixels and is independent of the zoom level of the map.
+
+    The default values correspond to a black border with a width of 1 pixel.
+    For no line, use a width of 0 or a transparent color.
+*/
 QDeclarativeMapLineProperties *QDeclarativeRectangleMapItem::border()
 {
     return &border_;
 }
 
+/*!
+    \qmlproperty Coordinate MapRectangle::topLeft
+
+    Holds the top-left coordinate of the MapRectangle.
+*/
 void QDeclarativeRectangleMapItem::setTopLeft(QDeclarativeCoordinate *topLeft)
 {
     if (topLeft_ == topLeft)
@@ -111,6 +138,11 @@ void QDeclarativeRectangleMapItem::updateMapItemAssumeDirty()
     updateMapItem();
 }
 
+/*!
+    \qmlproperty Coordinate MapRectangle::bottomRight
+
+    Holds the bottom-right coordinate of the MapRectangle.
+*/
 void QDeclarativeRectangleMapItem::setBottomRight(QDeclarativeCoordinate *bottomRight)
 {
     if (bottomRight_ == bottomRight)
@@ -132,6 +164,12 @@ QDeclarativeCoordinate* QDeclarativeRectangleMapItem::bottomRight()
     return bottomRight_;
 }
 
+/*!
+    \qmlproperty color MapRectangle::color
+
+    This property holds the fill color of the rectangle. For no fill, use
+    a transparent color.
+*/
 QColor QDeclarativeRectangleMapItem::color() const
 {
     return color_;
diff --git a/src/imports/location/qdeclarativeroutemapitem.cpp b/src/imports/location/qdeclarativeroutemapitem.cpp
index 5c50b51a..7eccf1a6 100644
--- a/src/imports/location/qdeclarativeroutemapitem.cpp
+++ b/src/imports/location/qdeclarativeroutemapitem.cpp
@@ -46,6 +46,16 @@
 #include <QtDeclarative/QDeclarativeInfo>
 #include <QtGui/QPainter>
 
+/*!
+    \qmlclass MapRoute QDeclarativeRouteMapItem
+    \inqmlmodule QtLocation 5
+    \ingroup qml-QtLocation5-maps
+    \since QtLocation 5.0
+
+    \brief The MapRoute element displays a route on the map.
+
+    \sa MapPolyline
+*/
 
 static void updatePolyline(QPolygonF& points,const Map& map, const QList<QGeoCoordinate> &path, qreal& w, qreal& h)
 {
@@ -116,6 +126,11 @@ void QDeclarativeRouteMapItem::setMap(QDeclarativeGeoMap* quickMap, Map *map)
     }
 }
 
+/*!
+    \qmlproperty GeoRoute MapRoute::route
+
+    Holds the route to be drawn.
+*/
 QDeclarativeGeoRoute* QDeclarativeRouteMapItem::route() const
 {
     return route_;
@@ -159,6 +174,18 @@ QSGNode* QDeclarativeRouteMapItem::updatePaintNode(QSGNode* oldNode, UpdatePaint
     return node;
 }
 
+/*!
+    \qmlproperty int MapRoute::line.width
+    \qmlproperty color MapRoute::line.color
+
+    These properties hold the width and color used to draw the line.
+
+    The width is in pixels and is independent of the zoom level of the map.
+    The default values correspond to a black border with a width of 1 pixel.
+
+    For no line, use a width of 0 or a transparent color.
+*/
+
 QDeclarativeMapLineProperties *QDeclarativeRouteMapItem::line()
 {
     return &line_;