Update the documentation

Pick-to: 6.5
Change-Id: Icff1282a22c3cefbbbbfb1dc03910066eb7c85f3
Reviewed-by: Volker Hilsheimer <volker.hilsheimer@qt.io>

9 files changed, 69 insertions, 106 deletions

diff --git a/src/location/doc/src/maps.qdoc b/src/location/doc/src/maps.qdoc
index ea147f2d..ad363d5c 100644
--- a/src/location/doc/src/maps.qdoc
+++ b/src/location/doc/src/maps.qdoc
@@ -24,7 +24,7 @@ A more hands-on introduction of the Maps and Navigation types can be found in th
 \section2 Displaying Maps
 
 Displaying a map is done using the \l{QtLocation::Map}{Map} QML types.  The Map type supports
-user interaction through the \l{QtLocation::MapGestureArea}{MapGestureArea} QML type. The Map
+user interaction through the \l{QtLocation::MapView}{MapView} QML type. The Map
 object draws the map on-screen using OpenGL (ES), allowing for hardware-accelerated rendering
 where available.
 
@@ -37,7 +37,7 @@ where available.
         \li \l{QtLocation::Map}{Map}
         \li QtQuick item to display a map on-screen.
     \row
-        \li \l{QtLocation::MapGestureArea}{MapGestureArea}
+        \li \l{QtLocation::MapView}{MapView}
         \li Interaction helper for panning, flicking and pinch-to-zoom gesture on a Map.
 \endtable
 
diff --git a/src/location/doc/src/qt6-changes.qdoc b/src/location/doc/src/qt6-changes.qdoc
index 26941a01..9b3d57b9 100644
--- a/src/location/doc/src/qt6-changes.qdoc
+++ b/src/location/doc/src/qt6-changes.qdoc
@@ -36,12 +36,15 @@
         \li The \c QGeoRouteLeg class and the QML equivalent, \c RouteLeg, have
             been merged into \l QGeoRoute (and the \l route type). A route can
             be an aggregate of several routes.
+        \li The \l {Map} type provides now minimal functionality without handling
+            of user intput. The \c {MapGestureArea} was removed. The \l {MapView}
+            type handles basic user input such as tap and drag events.
     \endlist
 
     \section2 Places
 
     \list
-        \li The \c {QPlaceImage}, {QPlaceEditorial}, and {QPlaceReview} classes
+        \li The \c {QPlaceImage}, \c {QPlaceEditorial}, and \c {QPlaceReview} classes
             have been folded into \l QPlaceContent.
         \li The \l QPlaceContent API has been changed to give access to a list of
             QVariant values.
diff --git a/src/location/maps/qgeojson.cpp b/src/location/maps/qgeojson.cpp
index 765fc5ec..f699a6c5 100644
--- a/src/location/maps/qgeojson.cpp
+++ b/src/location/maps/qgeojson.cpp
@@ -18,6 +18,11 @@ QT_BEGIN_NAMESPACE
 
 /*! \namespace QGeoJson
     \inmodule QtLocation
+    \keyword QGeoJson Namespace
+
+    \brief The QGeoJson namespace contains functions to import and export
+           geolocated information from and to GeoJson files.
+
     \since 5.13
 
     The methods in the QGeoJson namespace can be used to convert between a
@@ -44,7 +49,8 @@ QT_BEGIN_NAMESPACE
     MultiPolygon, \c GeometryCollection, \c FeatureCollection. The second pair
     has \c data as key, and the corresponding value can be either a QGeoShape
     or a list, depending on the GeoJSON type. The next section provides details
-    about this node. The \c Feature type is converted into the type of the
+    about the conversation form GeoJson objects to objects known in Qt Location.
+    The \c Feature type is converted into the type of the
     geometry contained within, with an additional (key, value) pair, where the
     key is \c properties and the value is a \l QVariantMap. Thus, a feature Map
     is distinguishable from the corresponding geometry, by looking for a \c
@@ -73,12 +79,12 @@ QT_BEGIN_NAMESPACE
 
         \code
         {
-          type : Point
+          type : "Point"
           data : QGeoCircle({60.000, 11.000}, -1)
         }
         \endcode
 
-    \li When the type is \c LineString the data ia a QGeoPath.
+    \li When the type is \c LineString the data is a QGeoPath.
 
         For example, the following GeoJSON document contains a \c LineString
         geometry:
@@ -94,7 +100,7 @@ QT_BEGIN_NAMESPACE
 
         \code
         {
-          type : LineString,
+          type : "LineString",
           data : QGeoPath([{43.000, 13.500}, {59.920, 10.730}])
         }
         \endcode
@@ -123,7 +129,7 @@ QT_BEGIN_NAMESPACE
 
         \code
         {
-          type : Polygon
+          type : "Polygon"
           data : QGeoPolygon([{51.110, 17.130}, {50.420,30.540}, {58.360, 26.700}, {51.110, 17.130}])
         }
         \endcode
@@ -157,18 +163,18 @@ QT_BEGIN_NAMESPACE
 
         \code
         {
-          type : MultiPoint
+          type : "MultiPoint"
           data : [
             {
-              type : Point
+              type : "Point"
               data : QGeoCircle({60.000, 11.000}, -1)
             },
             {
-              type : Point
+              type : "Point"
               data : QGeoCircle({60.300, 5.500}, -1)
             },
             {
-              type : Point
+              type : "Point"
               data : QGeoCircle({58.900, 5.700}, -1)
             }
           ]
@@ -194,14 +200,14 @@ QT_BEGIN_NAMESPACE
 
         \code
         {
-          type : MultiLineString
+          type : "MultiLineString"
           data : [
             {
-              type : LineString
+              type : "LineString"
               data : QGeoPath([{45.000, 9.150}, {58.900, -3.150}])
             },
             {
-              type : LineString
+              type : "LineString"
               data : QGeoPath([{43.000, 13.500}, {59.920, 10.730}])
             }
           ]
@@ -215,11 +221,24 @@ QT_BEGIN_NAMESPACE
 
         \code
         {
-            "type" : "MultiPoint",
+            "type" : "MultiPolygon",
             "coordinates" : [
-              [11,60],
-              [5.5,60.3],
-              [5.7,58.90]
+               [
+                 [
+                   [17.13, 51.11],
+                   [30.54, 50.42],
+                   [26.74, 58.36],
+                   [17.13, 51.11]
+                 ]
+                ],
+               [
+                 [
+                   [19.84, 41.33],
+                   [30.45, 49.26],
+                   [17.07, 50.10],
+                   [19.84, 41.33]
+                 ]
+               ]
             ]
         }
         \endcode
@@ -228,19 +247,15 @@ QT_BEGIN_NAMESPACE
 
         \code
         {
-          type : MultiPoint
+          type : "MultiPolygon"
           data : [
             {
-              type : Point
-              data : QGeoCircle({60.000, 11.000}, -1)
-            },
-            {
-              type : Point
-              data : QGeoCircle({60.300, 5.500}, -1)
+              type : "Polygon"
+              data : QGeoPolygon([{51.110, 17.130}, {50.420,30.540}, {58.360, 26.700}, {51.110, 17.130}])
             },
             {
-              type : Point
-              data : QGeoCircle({58.900, 5.700}, -1)
+              type : "Polygon"
+              data : QGeoPolygon([{41.330, 19.840}, {49.260,30.450}, {50.100, 17.070}, {41.330, 19.840}])
             }
           ]
         }
@@ -297,36 +312,36 @@ QT_BEGIN_NAMESPACE
 
     \code
     {
-      type : GeometryCollection
+      type : "GeometryCollection"
       data : [
         {
-          type : MultiPolygon
+          type : "MultiPolygon"
           data : [
             {
-              type : Polygon
+              type : "Polygon"
               data : QGeoPolygon([{41.330, 19.840}, {49.260, 30.450}, {50.100, 17.070}, {41.330, 19.840}])
             }
             {
-              type : Polygon
+              type : "Polygon"
               data : QGeoPolygon([{51.110, 17.130}, {50.420, 30.540}, {58.360, 26.740}, {51.110, 17.130}])
             }
           ]
         }
         {
-          type : MultiLineString
+          type : "MultiLineString"
           data : [
             {
-              type : LineString
+              type : "LineString"
               data : QGeoPath([{45.000, 9.150}, {58.900, -3.150}])
             }
             {
-              type : LineString
+              type : "LineString"
               data : QGeoPath([{43.000, 13.500}, {59.920, 10.730}])
             }
           ]
         }
         {
-          type : MultiPoint
+          type : "MultiPoint"
           data : [
             {
               type : Point
@@ -383,9 +398,9 @@ QT_BEGIN_NAMESPACE
 
     \code
     {
-      type : Polygon
+      type : "Polygon"
       data : QGeoPolygon([{51.110, 17.130}, {50.420,30.540}, {58.360, 26.700}, {51.110, 17.130}])
-      properties : {text : This is a Feature with a Polygon}
+      properties : {text : "This is a Feature with a Polygon"}
     }
     \endcode
 
@@ -442,26 +457,26 @@ QT_BEGIN_NAMESPACE
 
     \code
     {
-      type : FeatureCollection
+      type : "FeatureCollection"
       data : [
         {
-          type : MultiLineString
+          type : "MultiLineString"
           data : [
             {
-              type : LineString
+              type : "LineString"
               data : QGeoPath([{45.000, 9.150}, {58.900, -3.150}])
             }
             {
-              type : LineString
+              type : "LineString"
               data : QGeoPath([{43.000, 13.500}, {59.920, 10.730}])
             }
           ]
-          properties : {text : This is a Feature with a MultiLineString}
+          properties : {text : "This is a Feature with a MultiLineString"}
         },
         {
-          type : Polygon
+          type : "Polygon"
           data : QGeoPolygon({51.110, 17.130}, {50.420, 30.540}, {58.360, 26.700}, {51.110, 17.130})
-          properties : {text : This is a Feature with a Polygon}
+          properties : {text : "This is a Feature with a Polygon"}
         }
       ]
     }
diff --git a/src/location/quickmapitems/qdeclarativecirclemapitem.cpp b/src/location/quickmapitems/qdeclarativecirclemapitem.cpp
index 34aa4fb5..e01b724e 100644
--- a/src/location/quickmapitems/qdeclarativecirclemapitem.cpp
+++ b/src/location/quickmapitems/qdeclarativecirclemapitem.cpp
@@ -37,8 +37,8 @@ QT_BEGIN_NAMESPACE
     MapQuickItem containing a relevant Qt Quick type 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.
+    no fill. To change its appearance, use the \l {color}, \l {border.color}
+    and \l {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,
@@ -47,23 +47,12 @@ QT_BEGIN_NAMESPACE
     accuracy of the circle's shape, depending on position and map
     projection.
 
-    \note Dragging a MapCircle (through the use of \l MouseArea)
+    \note Dragging a MapCircle (through the use of \l {MouseArea} or \l {PointHandler})
     causes new points to be generated at the same distance (in meters)
     from the center. This is in contrast to other map items which store
     their dimensions in terms of latitude and longitude differences between
     vertices.
 
-    \section2 Performance
-
-    MapCircle performance is almost equivalent to that of a MapPolygon with
-    the same number of 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
diff --git a/src/location/quickmapitems/qdeclarativegeomap.cpp b/src/location/quickmapitems/qdeclarativegeomap.cpp
index 7033307f..c7f9415a 100644
--- a/src/location/quickmapitems/qdeclarativegeomap.cpp
+++ b/src/location/quickmapitems/qdeclarativegeomap.cpp
@@ -94,18 +94,12 @@ static qreal sanitizeBearing(qreal bearing)
     Maps are rendered using OpenGL (ES) and the Qt Scene Graph stack, and as
     a result perform quite well where GL accelerated hardware is available.
 
-    For "online" Map plugins, network bandwidth and latency can be major
+    For "online" Maps, network bandwidth and latency can be major
     contributors to the user's perception of performance. Extensive caching is
-    performed to mitigate this, but such mitigation is not always perfect. For
-    "offline" plugins, the time spent retrieving the stored geographic data
-    and rendering the basic map features can often play a dominant role. Some
-    offline plugins may use hardware acceleration themselves to (partially)
-    avert this.
+    performed to mitigate this, but such mitigation is not always perfect.
 
     In general, large and complex Map items such as polygons and polylines with
     large numbers of vertices can have an adverse effect on UI performance.
-    Further, more detailed notes on this are in the documentation for each
-    map item type.
 
     \section2 Example Usage
 
diff --git a/src/location/quickmapitems/qdeclarativepolygonmapitem.cpp b/src/location/quickmapitems/qdeclarativepolygonmapitem.cpp
index 1eee3eb0..1acd3e60 100644
--- a/src/location/quickmapitems/qdeclarativepolygonmapitem.cpp
+++ b/src/location/quickmapitems/qdeclarativepolygonmapitem.cpp
@@ -57,25 +57,12 @@ QT_BEGIN_NAMESPACE
     \l border.width properties.
 
     \note Since MapPolygons are geographic items, dragging a MapPolygon
-    (through the use of \l MouseArea) causes its vertices to be
+    (through the use of \l MouseArea or \l PointHander) causes its vertices to be
     recalculated in the geographic coordinate space. The edges retain the
     same geographic lengths (latitude and longitude differences between the
     vertices), but they remain straight. Apparent stretching of the item occurs
     when dragged to a different latitude.
 
-    \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. There
-    is an additional triangulation cost (approximately O(n log n)) which is
-    currently paid with each frame, but in future may be paid only upon adding
-    or removing points.
-
-    Like the other map objects, MapPolygon is normally drawn without a smooth
-    appearance. Setting the \l {Item::opacity}{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,
diff --git a/src/location/quickmapitems/qdeclarativepolylinemapitem.cpp b/src/location/quickmapitems/qdeclarativepolylinemapitem.cpp
index e80afbee..81c135a5 100644
--- a/src/location/quickmapitems/qdeclarativepolylinemapitem.cpp
+++ b/src/location/quickmapitems/qdeclarativepolylinemapitem.cpp
@@ -205,16 +205,6 @@ static QList<QList<QDoubleVector2D> > clipLine(
     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 {Item::opacity}{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 MapPolyline with 4 points, making a shape
diff --git a/src/location/quickmapitems/qdeclarativerectanglemapitem.cpp b/src/location/quickmapitems/qdeclarativerectanglemapitem.cpp
index 0e4e9e02..b1c03fd6 100644
--- a/src/location/quickmapitems/qdeclarativerectanglemapitem.cpp
+++ b/src/location/quickmapitems/qdeclarativerectanglemapitem.cpp
@@ -48,16 +48,6 @@ QT_BEGIN_NAMESPACE
     occurs when dragged to the a different latitude, however, its edges
     remain straight.
 
-    \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
diff --git a/src/location/quickmapitems/qdeclarativeroutemapitem.cpp b/src/location/quickmapitems/qdeclarativeroutemapitem.cpp
index cf59fdd5..373d0b51 100644
--- a/src/location/quickmapitems/qdeclarativeroutemapitem.cpp
+++ b/src/location/quickmapitems/qdeclarativeroutemapitem.cpp
@@ -28,11 +28,6 @@ QT_BEGIN_NAMESPACE
     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
 
     Here is how to draw a \l{route}{route} on a \l{Map}{map}: