Improving documentation for map objects

Task-number: QTBUG-23435
Change-Id: I0de70c1b4ce6ac1493ca3a553bb57eaf4778c6fe
Reviewed-by: David Laing <david.laing@nokia.com>

6 files changed, 250 insertions, 31 deletions

diff --git a/src/imports/location/qdeclarativecirclemapitem.cpp b/src/imports/location/qdeclarativecirclemapitem.cpp
index 328b7ff5..a6dd8ad1 100644
--- a/src/imports/location/qdeclarativecirclemapitem.cpp
+++ b/src/imports/location/qdeclarativecirclemapitem.cpp
@@ -54,11 +54,54 @@ QT_BEGIN_NAMESPACE
     \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.
+    \brief The MapCircle element displays a geographic circle on a Map.
+
+    The MapCircle element displays a geographic circle on a Map, which
+    consists of all points that are within a set distance from one
+    central point. Depending on map projection, a geographic circle
+    may not always be a perfect circle on the screen: for instance, in
+    the Mercator projection, circles become ovoid in shape as they near
+    the poles. To display a perfect screen circle around a point, use a
+    MapQuickItem containing a relevant QML element instead.
+
+    By default, the circle is displayed as a 1 pixel black border with
+    no fill. To change its appearance, use the color, border.color
+    and border.width properties.
+
+    Internally, a MapCircle is implemented as a many-sided polygon. To
+    calculate the radius points it uses a spherical model of the Earth,
+    similar to the atDistanceAndAzimuth method of the QML Coordinate
+    element. These two things can occasionally have implications for the
+    accuracy of the circle's shape, depending on position and map
+    projection.
+
+    \section2 Performance
+
+    MapCircle performance is almost equivalent to that of a MapPolygon with
+    125 vertices. There is a small amount of additional overhead with
+    respect to calculating the vertices first.
+
+    Like the other map objects, MapCircle is normally drawn without a smooth
+    appearance. Setting the opacity property will force the object to be
+    blended, which decreases performance considerably depending on the graphics
+    hardware in use.
+
+    \section2 Example Usage
+
+    The following snippet shows a map containing a MapCircle, centered at
+    the coordinate (-27, 153) with a radius of 5km. The circle is
+    filled in green, with a 3 pixel black border.
+
+    \code
+    Map {
+        MapCircle {
+            center: Coordinate { latitude: -27; longitude: 153.0 }
+            radius: 5000.0
+            color: 'green'
+            border.width: 3
+        }
+    }
+    \endcode
 */
 
 #ifndef M_PI
@@ -171,6 +214,7 @@ static void calculatePeripheralPoints(QList<QGeoCoordinate>& path, const QGeoCoo
 QDeclarativeCircleMapItem::QDeclarativeCircleMapItem(QQuickItem *parent):
     QDeclarativeGeoMapItemBase(parent),
     center_(0),
+    color_(Qt::transparent),
     radius_(0),
     zoomLevel_(0.0),
     dirtyPixelGeometry_(true),
@@ -178,7 +222,6 @@ QDeclarativeCircleMapItem::QDeclarativeCircleMapItem(QQuickItem *parent):
     dirtyMaterial_(true)
 {
     setFlag(ItemHasContents, true);
-    border_.setWidth(3.0);
     QObject::connect(&border_, SIGNAL(colorChanged(QColor)),
                      this, SLOT(updateMapItemAssumeDirty()));
     QObject::connect(&border_, SIGNAL(widthChanged(qreal)),
diff --git a/src/imports/location/qdeclarativecoordinate.cpp b/src/imports/location/qdeclarativecoordinate.cpp
index 67283ce9..b604cdf5 100644
--- a/src/imports/location/qdeclarativecoordinate.cpp
+++ b/src/imports/location/qdeclarativecoordinate.cpp
@@ -51,8 +51,50 @@ QT_BEGIN_NAMESPACE
     \ingroup qml-QtLocation5-positioning
     \since QtLocation 5.0
 
-    \brief The Coordinate element holds various positional data, such as \l
-    latitude, \l longitude and \l altitude.
+    \brief The Coordinate element represents and stores a geographic position.
+
+    Coordinate elements represent a geographic location in the form of numbers:
+    in particular, \l latitude, \l longitude and \l altitude. These, together,
+    specify a 3-dimensional position anywhere on or near the Earth's surface.
+
+    Coordinates are used by many other elements in the Qt Location module, for
+    specifying the position of an object on a Map, the current position of
+    a device and many other tasks. They also feature a number of important
+    utility methods that make otherwise complex calculations simple to use,
+    such as atDistanceAndAzimuth.
+
+    \section2 Accuracy
+
+    The latitude, longitude and altitude numbers stored in a Coordinate are
+    represented as doubles, giving them approximately 16 decimal digits of
+    precision -- enough to specify micrometers. The calculations performed
+    in Coordinate's methods such as azimuthTo and distanceTo also use doubles
+    for all intermediate values, but the inherent inaccuracies in their
+    spherical Earth model dominate the amount of error in their output.
+
+    \section2 Example Usage
+
+    The following snippet defines two coordinates near Brisbane, Australia.
+
+    \code
+    Coordinate {
+        id: coord1
+        latitude: -27.2
+        longitude: 153.1
+        altitude: 1.0
+    }
+
+    Coordinate {
+        id: coord2
+        latitude: -27.5
+        longitude: 153.2
+        altitude: 5.0
+    }
+    \endcode
+
+    As an example, the value of \c{coord1.distanceTo(coord2)} would now be
+    approximately 34790 (34.8 km).
+
 */
 
 QDeclarativeCoordinate::QDeclarativeCoordinate(QObject* parent)
diff --git a/src/imports/location/qdeclarativepolygonmapitem.cpp b/src/imports/location/qdeclarativepolygonmapitem.cpp
index c241ed18..5d045fc0 100644
--- a/src/imports/location/qdeclarativepolygonmapitem.cpp
+++ b/src/imports/location/qdeclarativepolygonmapitem.cpp
@@ -51,15 +51,57 @@ QT_BEGIN_NAMESPACE
     \ingroup qml-QtLocation5-maps
     \since QtLocation 5.0
 
-    \brief The MapPolygon element displays a polygon on a map.
-
-    The polygon is specified in terms of an ordered list of coordinates.
-    Any invalid coordinates in the list will be ignored.
-
-    MapPolygon can only display simple, convex polygons. Support may be added
-    in future for concave polygons, but this is not currently available.
-
-    \sa MapItem
+    \brief The MapPolygon element displays a polygon on a Map
+
+    The MapPolygon element displays a polygon on a Map, specified in terms of
+    an ordered list of \l Coordinate elements. For best appearance and results,
+    polygons should be simple (not self-intersecting) -- the result of drawing
+    a non-simple polygon is not well-defined.
+
+    The Coordinate elements on the path can be changed after being added to
+    the Polygon, and these changes will be reflected in the next frame on the
+    display. Coordinates can also be added and removed at any time using
+    the \l addCoordinate and \l removeCoordinate methods.
+
+    For drawing rectangles with "straight" edges (same latitude across one
+    edge, same latitude across the other), the \l MapRectangle element provides
+    a simpler, two-point API.
+
+    By default, the polygon is displayed as a 1 pixel black border with no
+    fill. To change its appearance, use the \l color, \l border.color and
+    \l border.width properties.
+
+    \section2 Performance
+
+    MapPolygons have a rendering cost that is O(n) with respect to the number
+    of vertices. This means that the per frame cost of having a Polygon on the
+    Map grows in direct proportion to the number of points on the Polygon.
+    Additionally, there is a triangulation cost any time the points of the
+    Polygon are updated, which is approximately O(n log n).
+
+    Like the other map objects, MapPolygon is normally drawn without a smooth
+    appearance. Setting the \l opacity property will force the object to be
+    blended, which decreases performance considerably depending on the hardware
+    in use.
+
+    \section2 Example Usage
+
+    The following snippet shows a MapPolygon being used to display a triangle,
+    with three vertices near Brisbane, Australia. The triangle is filled in
+    green, with a 1 pixel black border.
+
+    \code
+    Map {
+        MapPolygon {
+            color: 'green'
+            path: [
+                Coordinate { latitude: -27; longitude: 153.0 },
+                Coordinate { latitude: -27; longitude: 154.1 },
+                Coordinate { latitude: -28; longitude: 153.5 }
+            ]
+        }
+    }
+    \endcode
 */
 
 struct Vertex
@@ -173,9 +215,7 @@ QDeclarativeListProperty<QDeclarativeCoordinate> QDeclarativePolygonMapItem::dec
     \qmlproperty list<Coordinate> MapPolygon::path
 
     This property holds the ordered list of coordinates which
-    define the polygon. Individual coordinates can be accessed with
-    square brackets 'path.[i]' operator and coordinate amount with
-    'path.length'.
+    define the polygon.
 
     \sa addCoordinate removeCoordinate
 */
diff --git a/src/imports/location/qdeclarativepolylinemapitem.cpp b/src/imports/location/qdeclarativepolylinemapitem.cpp
index 37978ec9..5968f755 100644
--- a/src/imports/location/qdeclarativepolylinemapitem.cpp
+++ b/src/imports/location/qdeclarativepolylinemapitem.cpp
@@ -53,9 +53,52 @@ QT_BEGIN_NAMESPACE
 
     \brief The MapPolyline element displays a polyline on a map.
 
-    The polyline is specified in terms of an ordered list of
-    coordinates.  Any invalid coordinates in the list will be ignored.
-
+    The MapPolyline element displays a polyline on a map, specified in terms
+    of an ordered list of \l Coordinate elements. The Coordinate elements
+    on the path can be changed after being added to the Polyline, and these
+    changes will be reflected in the next frame on the display. Coordinates can
+    also be added and removed at any time using the \l addCoordinate and
+    \l removeCoordinate methods.
+
+    By default, the polyline is displayed as a 1-pixel thick black line. This
+    can be changed using the \l line.width and \l line.color properties.
+
+    \section2 Performance
+
+    MapPolylines have a rendering cost that is O(n) with respect to the number
+    of vertices. This means that the per frame cost of having a Polyline on
+    the Map grows in direct proportion to the number of points in the Polyline.
+
+    Like the other map objects, MapPolyline is normally drawn without a smooth
+    appearance. Setting the \l opacity property will force the object to be
+    blended, which decreases performance considerably depending on the hardware
+    in use.
+
+    \bold{NOTE:} MapPolylines are implemented using the OpenGL GL_LINES
+    primitive. There have been occasional reports of issues and rendering
+    inconsistencies on some (particularly quite old) platforms. No workaround
+    is yet available for these issues.
+
+    \section2 Example Usage
+
+    The following snippet shows a MapPolyline with 4 points, making a shape
+    like the top part of a "question mark" (?), near Brisbane, Australia.
+    The line drawn is 3 pixels in width and green in color.
+
+    \code
+    Map {
+        MapPolyline {
+            line.width: 3
+            line.color: 'green'
+            path: [
+                Coordinate { latitude: -27; longitude: 153.0 },
+                Coordinate { latitude: -27; longitude: 154.1 },
+                Coordinate { latitude: -28; longitude: 153.5 },
+                Coordinate { latitude: -29; longitude: 153.5 }
+            ]
+        }
+    }
+    \endcode
 */
 
 QDeclarativeMapLineProperties::QDeclarativeMapLineProperties(QObject *parent) :
@@ -182,10 +225,7 @@ void QDeclarativePolylineMapItem::setMap(QDeclarativeGeoMap* quickMap, Map *map)
     \qmlproperty list<Coordinate> MapPolyline::path
 
     This property holds the ordered list of coordinates which
-    define the polyline. Individual coordinates can be accessed with
-    square brackets 'path.[i]' operator and coordinate amount with
-    'path.length'.
-
+    define the polyline.
 */
 
 QDeclarativeListProperty<QDeclarativeCoordinate> QDeclarativePolylineMapItem::declarativePath()
diff --git a/src/imports/location/qdeclarativerectanglemapitem.cpp b/src/imports/location/qdeclarativerectanglemapitem.cpp
index 327363fb..0e373964 100644
--- a/src/imports/location/qdeclarativerectanglemapitem.cpp
+++ b/src/imports/location/qdeclarativerectanglemapitem.cpp
@@ -52,8 +52,45 @@ QT_BEGIN_NAMESPACE
 
     \brief The MapRectangle element displays a rectangle on a Map.
 
-    The rectangle displayed by MapRectangle is defined by its topLeft and
-    bottomRight coordinates.
+    The MapRectangle element displays a rectangle on a Map. Rectangles are a
+    special case of Polygon with exactly 4 vertices and "straight" sides. In
+    this case, "straight" means that the top-left and top-right points (the
+    top side) have the same latitude, and the points on the left and right sides
+    have the same longitude.
+
+    To specify the rectangle, it requires a \l topLeft and \l bottomRight point,
+    both given by \l Coordinate elements.
+
+    By default, the rectangle is displayed with transparent fill and a 1-pixel
+    thick black border. This can be changed using the \l color, \l border.color
+    and \l border.width properties.
+
+    \section2 Performance
+
+    MapRectangles have a rendering cost identical to a MapPolygon with 4
+    vertices.
+
+    Like the other map objects, MapRectangle is normally drawn without a smooth
+    appearance. Setting the \l opacity property will force the object to be
+    blended, which decreases performance considerably depending on the hardware
+    in use.
+
+    \section2 Example Usage
+
+    The following snippet shows a map containing a MapRectangle, spanning
+    from (-27, 153) to (-28, 153.5), near Brisbane, Australia. The rectangle
+    is filled in green, with a 2 pixel black border.
+
+    \code
+    Map {
+        MapRectangle {
+            color: 'green'
+            border.width: 2
+            topLeft: Coordinate { latitude: -27; longitude: 153 }
+            bottomRight: Coordinate { latitude: -28; longitude: 153.5 }
+        }
+    }
+    \endcode
 */
 
 struct Vertex
@@ -65,6 +102,7 @@ QDeclarativeRectangleMapItem::QDeclarativeRectangleMapItem(QQuickItem *parent):
     QDeclarativeGeoMapItemBase(parent),
     topLeft_(0),
     bottomRight_(0),
+    color_(Qt::transparent),
     zoomLevel_(0.0),
     dirtyGeometry_(true),
     dirtyMaterial_(true)
diff --git a/src/imports/location/qdeclarativeroutemapitem.cpp b/src/imports/location/qdeclarativeroutemapitem.cpp
index 7eccf1a6..33468ead 100644
--- a/src/imports/location/qdeclarativeroutemapitem.cpp
+++ b/src/imports/location/qdeclarativeroutemapitem.cpp
@@ -52,9 +52,25 @@
     \ingroup qml-QtLocation5-maps
     \since QtLocation 5.0
 
-    \brief The MapRoute element displays a route on the map.
+    \brief The MapRoute element displays a Route on a Map.
 
-    \sa MapPolyline
+    The MapRoute element displays a Route obtained through a RouteModel or
+    other means, on the Map as a Polyline following the path of the Route.
+
+    MapRoute is really a \l MapPolyline, but with the path specified using the
+    \l route property instead of directly in Coordinates.
+
+    By default, the route is displayed as a 1-pixel thick black line. This can
+    be changed using the \l line.width and \l line.color properties.
+
+    \section2 Performance
+
+    For notes about the performance on MapRoute, refer to the documentation for
+    \l MapPolyline.
+
+    \section2 Example Usage
+
+    TODO: an example here. do we want to use a RouteModel?
 */
 
 static void updatePolyline(QPolygonF& points,const Map& map, const QList<QGeoCoordinate> &path, qreal& w, qreal& h)