Fixes various documentation problems for Location.

- Adds the map items back to the QMl Location page
- Puts the landmark items in their own list
- Adds documentation / clarification for some signals
  of the group and custom map objects
- Adds a note to tilt / bearing methods that they will
  be ignored if the map plugin doesn't support
  tilt / bearing

16 files changed, 53 insertions, 64 deletions

diff --git a/doc/src/plugins/qml-location.qdoc b/doc/src/plugins/qml-location.qdoc
index 6da12f584c..02a92b055e 100644
--- a/doc/src/plugins/qml-location.qdoc
+++ b/doc/src/plugins/qml-location.qdoc
@@ -80,7 +80,16 @@
     bulk of the functionality is provided by a mapping plugin described
     by the plugin element associated with the Map.
 
-    \section2 Landmarks
+    Various map objects can be added to the map.  These map objects are
+    specified in terms of coordinates and meters.
+
+    Interaction with the map objects is done via the MapMouseArea item.
+
+    \section2 Map Elements
+
+    \annotatedlist qml-location-maps
+
+    \section1 Landmarks
 
     Most maps have landmarks. Useful markers identified in the landscape either as destinations
     or things that are noteworthy. In QtMobility the QML Location plugin supports
@@ -151,7 +160,9 @@
     are interested in, then the \l {LandmarkCategoryModel::categories}{categories}
     property is populated with the categories associated with that landmark.
 
+    \section2 Landmark Elements
 
+    \annotatedlist qml-location-landmarks
 */
 
 
diff --git a/plugins/declarative/location/qdeclarativegeomapcircleobject.cpp b/plugins/declarative/location/qdeclarativegeomapcircleobject.cpp
index 8684a30a0b..59b64e0695 100644
--- a/plugins/declarative/location/qdeclarativegeomapcircleobject.cpp
+++ b/plugins/declarative/location/qdeclarativegeomapcircleobject.cpp
@@ -237,13 +237,6 @@ void QDeclarativeGeoMapCircleObject::borderWidthChanged(int width)
     circle is visible.
 */
 
-/*!
-    \qmlproperty bool MapCircle::selected
-
-    This property holds a boolean corresponding to whether or not the
-    circle is selected.
-*/
-
 #include "moc_qdeclarativegeomapcircleobject_p.cpp"
 
 QTM_END_NAMESPACE
diff --git a/plugins/declarative/location/qdeclarativegeomapgroupobject.cpp b/plugins/declarative/location/qdeclarativegeomapgroupobject.cpp
index eb81d40c2a..29cbb0c872 100644
--- a/plugins/declarative/location/qdeclarativegeomapgroupobject.cpp
+++ b/plugins/declarative/location/qdeclarativegeomapgroupobject.cpp
@@ -239,13 +239,6 @@ void QDeclarativeGeoMapGroupObject::moveEvent(QDeclarativeGeoMapMouseEvent *even
     group is visible.
 */
 
-/*!
-    \qmlproperty bool MapGroup::selected
-
-    This property holds a boolean corresponding to whether or not the
-    group is selected.
-*/
-
 #include "moc_qdeclarativegeomapgroupobject_p.cpp"
 
 QTM_END_NAMESPACE
diff --git a/plugins/declarative/location/qdeclarativegeomappixmapobject.cpp b/plugins/declarative/location/qdeclarativegeomappixmapobject.cpp
index f7ce555ecb..4533fe8fa8 100644
--- a/plugins/declarative/location/qdeclarativegeomappixmapobject.cpp
+++ b/plugins/declarative/location/qdeclarativegeomappixmapobject.cpp
@@ -347,13 +347,6 @@ void QDeclarativeGeoMapPixmapObject::error(QNetworkReply::NetworkError error)
     image is visible.
 */
 
-/*!
-    \qmlproperty bool MapImage::selected
-
-    This property holds a boolean corresponding to whether or not the
-    image is selected.
-*/
-
 #include "moc_qdeclarativegeomappixmapobject_p.cpp"
 
 QTM_END_NAMESPACE
diff --git a/plugins/declarative/location/qdeclarativegeomappolygonobject.cpp b/plugins/declarative/location/qdeclarativegeomappolygonobject.cpp
index c428304498..38dbcb1954 100644
--- a/plugins/declarative/location/qdeclarativegeomappolygonobject.cpp
+++ b/plugins/declarative/location/qdeclarativegeomappolygonobject.cpp
@@ -299,13 +299,6 @@ void QDeclarativeGeoMapPolygonObject::removeCoordinate(QDeclarativeCoordinate* c
     polygon is visible.
 */
 
-/*!
-    \qmlproperty bool MapPolygon::selected
-
-    This property holds a boolean corresponding to whether or not the
-    polygon is selected.
-*/
-
 #include "moc_qdeclarativegeomappolygonobject_p.cpp"
 
 QTM_END_NAMESPACE
diff --git a/plugins/declarative/location/qdeclarativegeomappolylineobject.cpp b/plugins/declarative/location/qdeclarativegeomappolylineobject.cpp
index 361cc8ac3b..13c8b7a6b9 100644
--- a/plugins/declarative/location/qdeclarativegeomappolylineobject.cpp
+++ b/plugins/declarative/location/qdeclarativegeomappolylineobject.cpp
@@ -274,13 +274,6 @@ void QDeclarativeGeoMapPolylineObject::removeCoordinate(QDeclarativeCoordinate*
     polyline is visible.
 */
 
-/*!
-    \qmlproperty bool MapPolyline::selected
-
-    This property holds a boolean corresponding to whether or not the
-    polyline is selected.
-*/
-
 #include "moc_qdeclarativegeomappolylineobject_p.cpp"
 
 QTM_END_NAMESPACE
diff --git a/plugins/declarative/location/qdeclarativegeomaprectangleobject.cpp b/plugins/declarative/location/qdeclarativegeomaprectangleobject.cpp
index b34b1539cf..c49ea49e9a 100644
--- a/plugins/declarative/location/qdeclarativegeomaprectangleobject.cpp
+++ b/plugins/declarative/location/qdeclarativegeomaprectangleobject.cpp
@@ -272,13 +272,6 @@ void QDeclarativeGeoMapRectangleObject::borderWidthChanged(int width)
     rectangle is visible.
 */
 
-/*!
-    \qmlproperty bool MapRectangle::selected
-
-    This property holds a boolean corresponding to whether or not the
-    rectangle is selected.
-*/
-
 #include "moc_qdeclarativegeomaprectangleobject_p.cpp"
 
 QTM_END_NAMESPACE
diff --git a/plugins/declarative/location/qdeclarativegeomaptextobject.cpp b/plugins/declarative/location/qdeclarativegeomaptextobject.cpp
index f7392589a2..b54943ca35 100644
--- a/plugins/declarative/location/qdeclarativegeomaptextobject.cpp
+++ b/plugins/declarative/location/qdeclarativegeomaptextobject.cpp
@@ -400,13 +400,6 @@ void QDeclarativeGeoMapTextObject::setVerticalAlignment(QDeclarativeGeoMapTextOb
     text is visible.
 */
 
-/*!
-    \qmlproperty bool MapText::selected
-
-    This property holds a boolean corresponding to whether or not the
-    text is selected.
-*/
-
 #include "moc_qdeclarativegeomaptextobject_p.cpp"
 
 QTM_END_NAMESPACE
diff --git a/plugins/declarative/location/qdeclarativelandmark.cpp b/plugins/declarative/location/qdeclarativelandmark.cpp
index ca0554afae..1e1527ba52 100644
--- a/plugins/declarative/location/qdeclarativelandmark.cpp
+++ b/plugins/declarative/location/qdeclarativelandmark.cpp
@@ -46,7 +46,7 @@ QTM_BEGIN_NAMESPACE
 /*!
     \qmlclass Landmark QDeclarativeLandmark
     \brief The Landmark element presents one landmark.
-    \ingroup qml-location
+    \ingroup qml-location-landmarks
     \inherits Place
 
     This element is part of the \bold{QtMobility.location 1.1} module.
diff --git a/plugins/declarative/location/qdeclarativelandmarkcategory.cpp b/plugins/declarative/location/qdeclarativelandmarkcategory.cpp
index bed68470c9..78d480f755 100644
--- a/plugins/declarative/location/qdeclarativelandmarkcategory.cpp
+++ b/plugins/declarative/location/qdeclarativelandmarkcategory.cpp
@@ -46,7 +46,7 @@ QTM_BEGIN_NAMESPACE
 /*!
     \qmlclass LandmarkCategory QDeclarativeLandmarkCategory
     \brief The LandmarkCategory element presents one landmark category.
-    \ingroup qml-location
+    \ingroup qml-location-landmarks
 
     This element is part of the \bold{QtMobility.location 1.1} module.
 
diff --git a/plugins/declarative/location/qdeclarativelandmarkcategorymodel.cpp b/plugins/declarative/location/qdeclarativelandmarkcategorymodel.cpp
index 36ed7bf1e4..9255cae871 100644
--- a/plugins/declarative/location/qdeclarativelandmarkcategorymodel.cpp
+++ b/plugins/declarative/location/qdeclarativelandmarkcategorymodel.cpp
@@ -54,7 +54,7 @@ QTM_BEGIN_NAMESPACE
     \qmlclass LandmarkCategoryModel QDeclarativeLandmarkCategoryModel
     \brief The LandmarkCategoryModel element provides access to categories.
     \inherits LandmarkAbstractModel
-    \ingroup qml-location
+    \ingroup qml-location-landmarks
 
     This element is part of the \bold{QtMobility.location 1.1} module.
 
diff --git a/plugins/declarative/location/qdeclarativelandmarkfilters.cpp b/plugins/declarative/location/qdeclarativelandmarkfilters.cpp
index c75cb8f8ce..798698b6f0 100644
--- a/plugins/declarative/location/qdeclarativelandmarkfilters.cpp
+++ b/plugins/declarative/location/qdeclarativelandmarkfilters.cpp
@@ -47,7 +47,7 @@ QTM_BEGIN_NAMESPACE
 /*!
     \qmlclass LandmarkNameFilter QDeclarativeLandmarkNameFilter
     \brief The LandmarkNameFilter element specifies a name filter for landmark model.
-    \ingroup qml-location
+    \ingroup qml-location-landmarks
 
     The LandmarkNameFilter element specifies a name filter for landmark model.
     Logical combinations of this and other landmark filters can be
@@ -102,7 +102,7 @@ QLandmarkFilter* QDeclarativeLandmarkNameFilter::filter()
 /*!
     \qmlclass LandmarkCategoryFilter QDeclarativeLandmarkCategoryFilter
     \brief The LandmarkCategoryFilter element specifies a category filter for landmark model.
-    \ingroup qml-location
+    \ingroup qml-location-landmarks
 
     This element is part of the \bold{QtMobility.location 1.1} module.
 
@@ -150,7 +150,7 @@ QLandmarkFilter* QDeclarativeLandmarkCategoryFilter::filter()
 /*!
     \qmlclass LandmarkBoxFilter QDeclarativeLandmarkBoxFilter
     \brief The LandmarkBoxFilter element specifies a box (rectangle) filter for landmark model.
-    \ingroup qml-location
+    \ingroup qml-location-landmarks
 
     This element is part of the \bold{QtMobility.location 1.1} module.
 
@@ -231,7 +231,7 @@ QLandmarkFilter* QDeclarativeLandmarkBoxFilter::filter()
 /*!
     \qmlclass LandmarkProximityFilter QDeclarativeLandmarkProximityFilter
     \brief The LandmarkProximityFilter element specifies a proximity filter for landmark model.
-    \ingroup qml-location
+    \ingroup qml-location-landmarks
 
     The LandmarkProximityFilter element specifies a proximity filter for landmark model.
     Logical combinations of this and other landmark filters can be
@@ -386,7 +386,7 @@ template <class T>
 /*!
     \qmlclass LandmarkUnionFilter QDeclarativeLandmarkUnionFilter
     \brief The LandmarkUnionFilter element specifies a union of landmark filters.
-    \ingroup qml-location
+    \ingroup qml-location-landmarks
 
     This element is part of the \bold{QtMobility.location 1.1} module.
 
@@ -415,7 +415,7 @@ QDeclarativeLandmarkUnionFilter::QDeclarativeLandmarkUnionFilter(QObject* parent
 /*!
     \qmlclass LandmarkIntersectionFilter QDeclarativeLandmarkIntersectionFilter
     \brief The LandmarkIntersectionFilter element specifies an insection of landmark filters.
-    \ingroup qml-location
+    \ingroup qml-location-landmarks
 
     This element is part of the \bold{QtMobility.location 1.1} module.
 
diff --git a/plugins/declarative/location/qdeclarativelandmarkmodel.cpp b/plugins/declarative/location/qdeclarativelandmarkmodel.cpp
index c1b0c07b98..b07885c4d0 100644
--- a/plugins/declarative/location/qdeclarativelandmarkmodel.cpp
+++ b/plugins/declarative/location/qdeclarativelandmarkmodel.cpp
@@ -55,7 +55,7 @@ QTM_BEGIN_NAMESPACE
     \brief The LandmarkAbstractModel element is an uncreatable /
     uninstantiable base element for LandmarkModel and LandmarkCategoryModel.
     It defines many common properties for the two models.
-    \ingroup qml-location
+    \ingroup qml-location-landmarks
 
     The LandmarkAbstractModel element is an uncreatable /
     uninstantiable base element for LandmarkModel and LandmarkCategoryModel.
@@ -351,7 +351,7 @@ void QDeclarativeLandmarkAbstractModel::setSortOrder(QDeclarativeLandmarkAbstrac
     \qmlclass LandmarkModel QDeclarativeLandmarkModel
     \brief The LandmarkModel element provides access to landmarks.
     \inherits LandmarkAbstractModel
-    \ingroup qml-location
+    \ingroup qml-location-landmarks
 
     This element is part of the \bold{QtMobility.location 1.1} module.
 
diff --git a/src/location/maps/qgeomapcustomobject.cpp b/src/location/maps/qgeomapcustomobject.cpp
index d873a428c1..2f3080c371 100644
--- a/src/location/maps/qgeomapcustomobject.cpp
+++ b/src/location/maps/qgeomapcustomobject.cpp
@@ -50,7 +50,7 @@ QTM_BEGIN_NAMESPACE
 /*!
     \class QGeoMapCustomObject
     \brief The QGeoMapCustomObject class is a QGeoMapObject used to draw
-    a pixmap on a map.
+    a QGraphicsItem on a map.
 
     \inmodule QtLocation
 
@@ -160,6 +160,11 @@ QGeoMapObject::Type QGeoMapCustomObject::type() const
 }
 
 /*!
+    If the graphics item is modified this
+    method should be called immediately afterwards to inform
+    the map that an update is required. .
+
+    This method causes the triggerUpdate() signal to be emitted.
 */
 void QGeoMapCustomObject::update()
 {
@@ -168,6 +173,9 @@ void QGeoMapCustomObject::update()
 
 /*!
 \fn void QGeoMapCustomObject::triggerUpdate()
+
+    This signal indicates that the graphics item has
+    changed and that the map needs to be updated.
 */
 
 /*!
diff --git a/src/location/maps/qgeomapgroupobject.cpp b/src/location/maps/qgeomapgroupobject.cpp
index dcd953a22f..f49a0f19aa 100644
--- a/src/location/maps/qgeomapgroupobject.cpp
+++ b/src/location/maps/qgeomapgroupobject.cpp
@@ -260,8 +260,15 @@ void QGeoMapGroupObject::setMapData(QGeoMapData *mapData)
 /*!
 \fn void QGeoMapGroupObject::childUpdated(QGeoMapObject *childObject)
 
-    This signal will be emitted when the map object \a childObject
-    belonging to the group is updated.
+    This signal will be emitted if the map object \a childObject has
+    changed such that the corresponding QGeoMapObjectInfo class that handles
+    the map-specific behaviours of the object needs to be informed of
+    the change.
+
+    The map object \a childObject must belong to this group.
+
+    At the moment this is only emitted when the z-value of the
+    child-objects are changed.
 */
 
 /*!
diff --git a/src/location/maps/qgraphicsgeomap.cpp b/src/location/maps/qgraphicsgeomap.cpp
index f7fb49eed8..26870b7966 100644
--- a/src/location/maps/qgraphicsgeomap.cpp
+++ b/src/location/maps/qgraphicsgeomap.cpp
@@ -304,6 +304,9 @@ bool QGraphicsGeoMap::supportsBearing() const
 
     Value in degrees where 0 is equivalent to 90 degrees between view and earth's
     surface i.e. looking straight down to earth.
+
+    Changes to this property will be ignored if supportsBearing()
+    returns false.
 */
 void QGraphicsGeoMap::setBearing(qreal bearing)
 {
@@ -374,6 +377,9 @@ qreal QGraphicsGeoMap::maximumTilt() const
     If \a tilt is less than minimumTilt() then minimumTilt()
     will be used, and if \a tilt is  larger than
     maximumTilt() then maximumTilt() will be used.
+
+    Changes to this property will be ignored if supportsTilting()
+    returns false.
 */
 void QGraphicsGeoMap::setTilt(qreal tilt)
 {
@@ -755,6 +761,9 @@ QGeoCoordinate QGraphicsGeoMap::screenPositionToCoordinate(QPointF screenPositio
     This signal is emitted when the bearing of the map changes.
 
     The new value is \a bearing.
+
+    This signal will not be emitted if supportsBearing()
+    returns false.
 */
 
 /*!
@@ -763,6 +772,9 @@ QGeoCoordinate QGraphicsGeoMap::screenPositionToCoordinate(QPointF screenPositio
     This signal is emitted when the tilt of the map changes.
 
     The new value is \a tilt.
+
+    This signal will not be emitted if supportsTilting()
+    returns false.
 */
 
 /*!